> ## 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.

# Configuration and composition

> QitOS public API: composition

Load canonical configuration without credentials or Docker first. At composition, explicitly resolve CredentialRef or inject the teaching provider. Use the composition as a context manager: it owns environment, store and scheduler cleanup. Session methods return the public Session facade. Ephemeral configuration cannot restore or fork. Invalid config, missing extensions or a closed composition fail before useful execution.

[完整可运行教程 / Complete tutorial](/quickstart) · [API index](/reference/api)

Signatures and fields below are extracted from the pinned source. Signatures are reference material, not standalone programs. Source links bind the same runtime baseline. Any does not imply arbitrary objects are supported; use the behavioral contract above and the linked tutorial.

<span id="qitos-config-fakecredentialresolver" />

## FakeCredentialResolver

```python theme={null}
from qitos.config import FakeCredentialResolver
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L195)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
resolver = FakeCredentialResolver()  # offline fixtures only
```

```text theme={null}
Deterministic resolver for tests and offline qualification.
```

```text theme={null}
FakeCredentialResolver(values: Mapping[str, str] | None=None) -> None
```

| Parameter | Type                        | Default |
| --------- | --------------------------- | ------- |
| `values`  | `Mapping[str, str] \| None` | `None`  |

<span id="qitos-config-agentcomposition" />

## AgentComposition

```python theme={null}
from qitos.config import AgentComposition
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L134)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
# After loading config and creating the explicit provider:
with build_agent_composition(config, model_override=provider) as composition:
    session = composition.session("Index the notes")
    result = session.run()
```

```text theme={null}
Resource-owning composition root for the existing Engine and Session.
```

| Field                | Type                         | Default                       |
| -------------------- | ---------------------------- | ----------------------------- |
| `config`             | `AgentConfig`                | `required`                    |
| `model`              | `Any`                        | `required`                    |
| `tool_registry`      | `ToolRegistry`               | `required`                    |
| `env`                | `Any`                        | `required`                    |
| `runtime`            | `RuntimeComposition`         | `required`                    |
| `agent`              | `AgentModule[Any, Any, Any]` | `required`                    |
| `engine`             | `Engine[Any, Any, Any]`      | `required`                    |
| `credential_receipt` | `Dict[str, Any]`             | `required`                    |
| `sandbox_backend`    | `Any`                        | `None`                        |
| `sandbox_receipt`    | `Dict[str, Any]`             | `field(default_factory=dict)` |
| `trajectory_path`    | `Optional[Path]`             | `None`                        |

<span id="qitos-config-agentcomposition-session" />

### AgentComposition.session

```text theme={null}
session(task: Optional[str]=None, *, session_id: Any=None) -> Any
```

| Parameter    | Type            | Default |
| ------------ | --------------- | ------- |
| `task`       | `Optional[str]` | `None`  |
| `session_id` | `Any`           | `None`  |

```text theme={null}
Create the existing durable Session from this composition.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L172)

<span id="qitos-config-agentcomposition-restore" />

### AgentComposition.restore

```text theme={null}
restore(session_id: Any=None) -> Any
```

| Parameter    | Type  | Default |
| ------------ | ----- | ------- |
| `session_id` | `Any` | `None`  |

```text theme={null}
Restore with this composition's resolver registry and canonical Engine.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L188)

<span id="qitos-config-agentcomposition-fork" />

### AgentComposition.fork

```text theme={null}
fork(session_id: Any, snapshot: Any=None, *, operation_id: Optional[str]=None) -> Any
```

| Parameter      | Type            | Default    |
| -------------- | --------------- | ---------- |
| `session_id`   | `Any`           | `required` |
| `snapshot`     | `Any`           | `None`     |
| `operation_id` | `Optional[str]` | `None`     |

```text theme={null}
Fork immutable persisted state without claiming the source owner.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L211)

<span id="qitos-config-agentcomposition-close" />

### AgentComposition.close

```text theme={null}
close() -> Dict[str, Any]
```

```text theme={null}
Close every framework-owned resource once and return a stable receipt.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L222)

<span id="qitos-config-build_agent_composition" />

## build\_agent\_composition

```python theme={null}
from qitos.config import build_agent_composition
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L659)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
composition = build_agent_composition(config, model_override=provider)
try:
    result = composition.session("Index the notes").run()
finally:
    composition.close()
```

```text theme={null}
Compose the existing model/tools/Env/runtime/AgentModule/Engine stack.

``agent_factory`` is called once with keyword arguments ``config``, ``model``,
``tool_registry``, ``protocol`` (a resolved protocol), and ``parser``. It
returns an AgentModule bound to those resources; it must not replace them.
The factory may register application tools. Composition retains ownership
of resources it created. Recreate the factory in the restoring process;
no callable is serialized in Session snapshots.
```

```text theme={null}
build_agent_composition(config: AgentConfig, *, credential_resolver: Optional[CredentialResolver]=None, model_override: Any=None, env_override: Any=None, extensions: Optional[Mapping[str, Any]]=None, agent_factory: Optional[Callable[..., AgentModule[Any, Any, Any]]]=None) -> AgentComposition
```

| Parameter             | Type                                                  | Default    |
| --------------------- | ----------------------------------------------------- | ---------- |
| `config`              | `AgentConfig`                                         | `required` |
| `credential_resolver` | `Optional[CredentialResolver]`                        | `None`     |
| `model_override`      | `Any`                                                 | `None`     |
| `env_override`        | `Any`                                                 | `None`     |
| `extensions`          | `Optional[Mapping[str, Any]]`                         | `None`     |
| `agent_factory`       | `Optional[Callable[..., AgentModule[Any, Any, Any]]]` | `None`     |

<span id="qitos-config-load_agent_config" />

## load\_agent\_config

```python theme={null}
from qitos.config import load_agent_config
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L503)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
config = load_agent_config("agent.yaml")
print(config.digest())
```

```text theme={null}
Load one strict canonical configuration from YAML.
```

```text theme={null}
load_agent_config(path: str | Path, *, compatibility: bool=False, environment_interpolation: bool=False) -> AgentConfig
```

| Parameter                   | Type          | Default    |
| --------------------------- | ------------- | ---------- |
| `path`                      | `str \| Path` | `required` |
| `compatibility`             | `bool`        | `False`    |
| `environment_interpolation` | `bool`        | `False`    |

<span id="qitos-config-agentconfig" />

## AgentConfig

```python theme={null}
from qitos.config import AgentConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L235)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
config = load_agent_config("agent.yaml")
assert config.runtime.session.store == "sqlite"
print(config.to_dict()["model"]["credential"])
```

```text theme={null}
The one canonical declarative agent launch configuration.
```

| Field             | Type                          | Default                                |
| ----------------- | ----------------------------- | -------------------------------------- |
| `name`            | `str`                         | `'agent'`                              |
| `max_steps`       | `int`                         | `10`                                   |
| `model`           | `ModelConfig`                 | `field(default_factory=ModelConfig)`   |
| `dataset`         | `Sequence[DatasetItem]`       | `field(default_factory=tuple)`         |
| `tools`           | `Sequence[str]`               | `field(default_factory=tuple)`         |
| `tool_preset`     | `str`                         | `'none'`                               |
| `tool_options`    | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `tool_use_policy` | `str`                         | `'auto'`                               |
| `protocol`        | `str`                         | `'auto'`                               |
| `parser`          | `str`                         | `'auto'`                               |
| `environment`     | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `seed`            | `int`                         | `0`                                    |
| `metadata`        | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `context`         | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `memory`          | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `compaction`      | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `lifecycle`       | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `failure_policy`  | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `runtime`         | `RuntimeConfig`               | `field(default_factory=RuntimeConfig)` |
| `budgets`         | `Optional[BudgetConfig]`      | `None`                                 |
| `schema`          | `str`                         | `CANONICAL_SCHEMA`                     |
| `source`          | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `compatibility`   | `Sequence[Mapping[str, Any]]` | `field(default_factory=tuple)`         |
| `loss`            | `Sequence[Mapping[str, Any]]` | `field(default_factory=tuple)`         |

<span id="qitos-config-agentconfig-to-dict" />

### AgentConfig.to\_dict

```text theme={null}
to_dict() -> Dict[str, Any]
```

```text theme={null}
Return deterministic JSON/YAML-safe canonical launch data.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L297)

<span id="qitos-config-agentconfig-digest" />

### AgentConfig.digest

```text theme={null}
digest() -> str
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L341)

<span id="qitos-config-credentialref" />

## CredentialRef

```python theme={null}
from qitos.config import CredentialRef
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L25)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
reference = CredentialRef("notes-provider")
print(reference)
```

```text theme={null}
Serializable logical identity of one credential.
```

| Field | Type  | Default    |
| ----- | ----- | ---------- |
| `ref` | `str` | `required` |

<span id="qitos-config-localcredentialfileresolver" />

## LocalCredentialFileResolver

```python theme={null}
from qitos.config import LocalCredentialFileResolver
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L113)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
from pathlib import Path
resolver = LocalCredentialFileResolver(
    Path.home() / ".config/qitos/credentials.yaml",
    repository_root=Path.cwd(),
)
# Pass resolver as credential_resolver to build_agent_composition.
```

```text theme={null}
Resolve one logical credential from a hardened local YAML file.
```

```text theme={null}
LocalCredentialFileResolver(path: str | Path, *, repository_root: str | Path) -> None
```

| Parameter         | Type          | Default    |
| ----------------- | ------------- | ---------- |
| `path`            | `str \| Path` | `required` |
| `repository_root` | `str \| Path` | `required` |

<span id="qitos-config-localcredentialfileresolver-resolve" />

### LocalCredentialFileResolver.resolve

```text theme={null}
resolve(ref: CredentialRef) -> CredentialResolution
```

| Parameter | Type            | Default    |
| --------- | --------------- | ---------- |
| `ref`     | `CredentialRef` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L155)

<span id="qitos-config-budgetconfig" />

## BudgetConfig

```python theme={null}
from qitos.config import BudgetConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L221)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
budget = BudgetConfig(max_steps=6, max_requests=6, max_runtime_seconds=30)
```

| Field                 | Type    | Default |
| --------------------- | ------- | ------- |
| `max_steps`           | `int`   | `10`    |
| `max_runtime_seconds` | `float` | `600.0` |
| `max_requests`        | `int`   | `12`    |

<span id="qitos-config-environmentconfig" />

## EnvironmentConfig

```python theme={null}
from qitos.config import EnvironmentConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L112)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
environment = EnvironmentConfig(workspace="./source", image="python:3.12-slim")
```

| Field                 | Type              | Default              |
| --------------------- | ----------------- | -------------------- |
| `type`                | `str`             | `'docker'`           |
| `image`               | `str`             | `'python:3.12-slim'` |
| `workspace`           | `str`             | `'.'`                |
| `container_workspace` | `str`             | `'/workspace'`       |
| `network`             | `str`             | `'none'`             |
| `read_only_root`      | `bool`            | `True`               |
| `cap_drop`            | `bool`            | `True`               |
| `no_new_privileges`   | `bool`            | `True`               |
| `pids_limit`          | `Optional[int]`   | `256`                |
| `memory_mb`           | `Optional[int]`   | `2048`               |
| `cpus`                | `Optional[float]` | `2.0`                |
| `cleanup_required`    | `bool`            | `True`               |

<span id="qitos-config-modelconfig" />

## ModelConfig

```python theme={null}
from qitos.config import ModelConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L60)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
model = ModelConfig(provider="openai_compatible", model="notes-fake")
```

| Field            | Type                      | Default                                        |
| ---------------- | ------------------------- | ---------------------------------------------- |
| `provider`       | `str`                     | `'openai'`                                     |
| `model`          | `str`                     | `''`                                           |
| `model_name`     | `str`                     | `''`                                           |
| `credential`     | `Optional[CredentialRef]` | `None`                                         |
| `base_url`       | `str`                     | `''`                                           |
| `context_window` | `Optional[int]`           | `None`                                         |
| `api_mode`       | `str`                     | `'chat_completions'`                           |
| `request`        | `ModelRequestConfig`      | `field(default_factory=ModelRequestConfig)`    |
| `api_key`        | `str`                     | `field(default='', repr=False, compare=False)` |
| `temperature`    | `Optional[float]`         | `None`                                         |
| `max_tokens`     | `Optional[int]`           | `None`                                         |

<span id="qitos-config-runtimeconfig" />

## RuntimeConfig

```python theme={null}
from qitos.config import RuntimeConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L205)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
runtime = RuntimeConfig(environment=EnvironmentConfig(workspace="./source"))
```

| Field         | Type                | Default                                    |
| ------------- | ------------------- | ------------------------------------------ |
| `environment` | `EnvironmentConfig` | `field(default_factory=EnvironmentConfig)` |
| `session`     | `SessionConfig`     | `field(default_factory=SessionConfig)`     |
| `trajectory`  | `TrajectoryConfig`  | `field(default_factory=TrajectoryConfig)`  |
| `data_root`   | `str`               | `''`                                       |

<span id="qitos-config-trajectoryconfig" />

## TrajectoryConfig

```python theme={null}
from qitos.config import TrajectoryConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L189)

[Usage and executable example](/quickstart)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
trajectory = TrajectoryConfig(output="./notes-run/trajectory.journal")
```

| Field            | Type   | Default      |
| ---------------- | ------ | ------------ |
| `enabled`        | `bool` | `True`       |
| `output`         | `str`  | `''`         |
| `privacy`        | `str`  | `'private'`  |
| `failure_policy` | `str`  | `'required'` |