> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expectedparrot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Language Models

> Discover model availability, configure providers, and compare model outputs.

A `Model` selects the language model that will generate answers to your survey. Its **service** identifies where EDSL sends the requests; its **parameters** control supported generation settings, such as response length. An [Agent](https://docs.expectedparrot.com/en/latest/agents.md) supplies a respondent profile, while the Model supplies the language model answering from that profile.

Use one Model to run a study or a ModelList to compare several model configurations on the same inputs. Select from the current catalog because model availability and supported settings change.

## Discover and select models

```python theme={null}
from edsl import Model

Model.services()
Model.available()
```

`Model.services()` lists inference services; `Model.available()` lists models you can select. Run each expression in its own notebook cell to display both tables. Discovery may contact provider or Expected Parrot services. The [model catalog](https://www.expectedparrot.com/models) includes availability and pricing. See [Managing Keys](https://docs.expectedparrot.com/en/latest/api_keys.md) for hosted and provider credentials.

`Model()` selects the configured default. Inspect `model.model` and `model.parameters` and save the configuration with your study. For a named selection, use `Model(model_name, service_name=provider)` with values you have verified in the catalog.

## Compare models on matched inputs

Construct a `ModelList` from your selected configurations and apply it with `job.by(models)`. Hold the questions, scenarios, and agent instructions constant so differences can be traced to model configuration. See [Model comparisons](https://docs.expectedparrot.com/en/latest/guides/model_comparisons.md).

Do not assume settings such as temperature, token limits, or reasoning effort have the same meaning or valid values across providers. Unsupported values can fail at execution time even when a configuration serializes successfully.

## Reasoning and provider configuration

OpenAI adapters accept reasoning settings, with request formatting depending on the adapter. Explicit `reasoning_effort` is forwarded for provider validation; with the Responses adapter, an explicit effort overrides the effort inside a `reasoning` dictionary. Supported values depend on the selected model.

See [Provider configuration](https://docs.expectedparrot.com/en/latest/guides/providers.md) for selecting services and inspecting parameters, and the [adapter source](https://github.com/expectedparrot/edsl/tree/main/edsl/inference_services) for implementation details. Record effective settings with results and check provider documentation before adopting a model-specific option.

## Connect to your own model server

Use EDSL's `openai_compatible` service to connect to a server that exposes an OpenAI-compatible chat-completions endpoint. Start the server first, then replace `MODEL_NAME` with a model identifier it serves and `SERVER_BASE_URL` with its API base URL, including `/v1` if required by that server.

```python theme={null}
from edsl import Model

model = Model(
    "MODEL_NAME",
    service_name="openai_compatible",
    base_url="SERVER_BASE_URL",
    # For an authenticated server, also set:
    # api_key_env="MY_MODEL_API_KEY",
)
```

If the server requires authentication, set an environment variable containing its key and pass that variable's name as `api_key_env`. EDSL saves the variable name with the model configuration, without including its secret value.

With a `survey` you have already constructed, run it through the configured endpoint:

```python theme={null}
results = survey.by(model).run(
    disable_remote_inference=True,
    disable_remote_cache=True,
)
results.select("answer.*")
# In a script, append .print() to display the answers.
```

`disable_remote_inference=True` runs orchestration on your machine; requests go to the configured server, which may be local or remote. `disable_remote_cache=True` disables Expected Parrot's remote cache. The CLI equivalent for local orchestration is `--local`.

Supported model parameters and response formats depend on the server and model. Use the server's own documentation for installation and tuning—for example, the [llama.cpp server guide](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md).

For an offline execution check, use the test model in the [Run your first survey](https://docs.expectedparrot.com/en/latest/starter_tutorial.md) tutorial. Test responses demonstrate the data flow and do not measure model performance.

## Common methods

| Call | Arguments and result |
| - | - |
| `Model()` | Create a configuration for your default model. |
| `Model(model_name, service_name=provider, **parameters)` | Choose a model and provider, with provider-specific parameters. |
| `Model.available(search_term=None, service_name=None)` | Return a ModelList from the available catalog, optionally filtered by name or service. Discovery can contact remote services. |
| `Model.services()` | Return a ScenarioList describing registered inference services. |
| `ModelList([model, ...])` | Collect configurations for a comparison. |
| `model.model` / `model.parameters` | Inspect the selected name and parameter dictionary. |

You can practice configuring multiple models locally:

```python theme={null}
from edsl import Model, ModelList

models = ModelList([
    Model("test", canned_response="Clear"),
    Model("test", canned_response="Unclear"),
])
models
# In a script: models.print()
```

These test models return fixed answers. Replace them with configurations from the catalog for a real model comparison, then pass the list to `job.by(models)`.

## Narrow the catalog and reuse selections

`Model.available(service_name=provider)` restricts discovery to a service; add `search_term` to filter names. `Model.search_models(search_term)` provides name search. To inspect only services for which you have configured provider keys, use `Model.services_with_local_keys()`; `Model.available_with_local_keys()` lists their models. These are discovery methods, not guarantees that a particular API call will succeed.

`Model.check_working_models(works_with_text=True, works_with_images=True)` retrieves Expected Parrot's working-model catalog with capability filters. It reads catalog information rather than running your survey. Use `output_format="scenario_list"` when you want catalog rows instead of model configurations.

For PDF, video, and audio inputs, choose a model that supports the specific media type; the image filter only describes image support. See [Files and media as scenarios](https://docs.expectedparrot.com/en/latest/scenarios.md#data-and-files) for examples, including Google video and audio inputs.

A ModelList can be inspected with `to_scenario_list()` or `to_dataset()`, filtered with `filter(expression)`, and saved with `save("models.ep")` for later `ModelList.load("models.ep")`. `ModelList.from_names(names)` constructs configurations from a list of model names; use explicit `Model(name, service_name=provider)` objects when the provider needs to be unambiguous.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.