> For the complete documentation index, see [llms.txt](https://robodex.gitbook.io/robodex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://robodex.gitbook.io/robodex-docs/research/local-models-prompts.md).

# Local Models And Prompts

## Local chat models

`packages/research/local_chat_models.py` provides ChatOpenAI-compatible model factories for local or configured providers.

Use:

* `make_chat_model()`,
* `make_structured_llm()`.

Avoid direct `ChatOpenAI` imports in research loops and strategies unless a task explicitly requires that fallback.

## Provider selection

Common provider values:

| Provider      | Use case                                          |
| ------------- | ------------------------------------------------- |
| `codex`       | Isolated persistent local Codex MCP-server thread |
| `claude-code` | Persistent Claude Code with Sonnet-class model    |
| `openai`      | Explicit OpenAI fallback                          |

Set:

```bash
export RESEARCH_LLM_PROVIDER=codex
```

or another supported provider before running model-backed experiments.

## Prompt registry

`packages/research/prompts/registry.py` loads and renders YAML templates.

It supports:

* named templates,
* versions,
* variable rendering,
* SHA-256 hashes,
* prompt metadata for reproducibility.

## Prompt templates

Current templates include V1 and V2 contracts.

V1 examples:

* `v1_normalizer.yaml`,
* `v1_rule_builder.yaml`,
* `v1_evaluator.yaml`,
* `v1_materializer.yaml`.

V2 examples:

* `v2_program_builder.yaml`,
* `v2_program_evaluator.yaml`,
* `v2_program_repair.yaml`,
* `v2_component_materializer.yaml`.

## Prompt discipline

When changing prompts:

* keep the output schema explicit,
* keep examples minimal but representative,
* update tests or fixtures that depend on exact prompt shape,
* preserve prompt hashes in experiment metadata,
* avoid product-route imports of prompt registry internals.

## Deterministic fallback

Many generation paths include deterministic fallback behavior. This is not a bug. It keeps local tests, docs, and non-networked development usable.

When publishing research claims, clearly distinguish:

* model-backed generation,
* fallback generation,
* benchmarked simulation evidence,
* smoke-test-only evidence.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://robodex.gitbook.io/robodex-docs/research/local-models-prompts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.