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

# Add a model-family preset

> How to extend QitOS v0.4 with a new family preset without forking the runtime.

A family preset (a configuration bundle that maps a model family to its default protocol, adapter, and tool delivery) lets you add support for a new model family without writing a new runtime. Do not start by writing one.

Start by answering five questions:

1. What model names should resolve to this family?
2. Which transport (the adapter layer that handles API communication with the model provider) builds the model object?
3. What is the default protocol (the output format the model is expected to follow)?
4. What fallback protocol chain should remain stable?
5. How should tools and context be delivered by default?

## The minimal path

Add one `FamilyPreset` entry under `qitos/harness/_presets.py`.

```python theme={null}
FamilyPreset(
    id="my-family",
    display_name="My Family",
    model_matchers=("my-family", "my-model-prefix"),
    adapter_kind="openai-compatible",
    default_protocol="json_decision_v1",
    fallback_protocols=("react_text_v1",),
    tool_policy=ToolPolicy(
        primary_delivery="api_parameter",
        fallback_delivery="prompt_injection",
    ),
    context_policy=ContextPolicy(
        context_window_hint=128_000,
        fallback_context_window=128_000,
    ),
    recommended_models=("my-family-32b",),
    recommended_max_steps=30,
    recommended_max_tokens=500_000,
    recommended_retry_budget=3,
    recommended_temperature=0.2,
)
```

## Reuse protocol objects instead of inventing new ones

QitOS v0.4 reuses the existing `ModelProtocol` set, so most new families should choose from:

* `react_text_v1`
* `json_decision_v1`
* `xml_decision_v1`
* `terminus_json_v1`
* `terminus_xml_v1`
* `minimax_tool_call_v1`

Only create a new protocol when the model truly emits a different contract.

## Reuse adapters when possible

For v0.4, the default adapter is:

```python theme={null}
OpenAICompatibleAdapter
```

If the model is served through an OpenAI-compatible endpoint, prefer reusing that adapter.

Only add a new adapter when the transport itself is different, not just because the family is different.

## Keep the preset traceable

The preset becomes valuable only if researchers can see it later.

Make sure the resolved harness metadata is visible through:

* `RunSpec.metadata`
* trace manifest (the JSON record of the full run history)
* `qita`

## Validation checklist

* `resolve_family_preset(...)` resolves the family from both family id and model name
* `build_harness_policy(...)` returns the right protocol and parser (the component that converts raw model output into a structured `Decision`)
* `infer_model_profile(...)` stays aligned with preset defaults
* the flagship example can switch into the new family without changing agent code
* `recommended_*` fields are set if the family has been tested enough to provide stable baseline advice
* `preset.override()` works for users who need to tweak your preset without editing source