Configuration and 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 · API index 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.

FakeCredentialResolver

from qitos.config import FakeCredentialResolver

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

resolver = FakeCredentialResolver()  # offline fixtures only

Deterministic resolver for tests and offline qualification.

FakeCredentialResolver(values: Mapping[str, str] | None=None) -> None

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

AgentComposition

from qitos.config import AgentComposition

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# 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()

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`

AgentComposition.session

session(task: Optional[str]=None, *, session_id: Any=None) -> Any

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

Create the existing durable Session from this composition.

Source

AgentComposition.restore

restore(session_id: Any=None) -> Any

Parameter	Type	Default
`session_id`	`Any`	`None`

Restore with this composition's resolver registry and canonical Engine.

Source

AgentComposition.fork

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`

Fork immutable persisted state without claiming the source owner.

Source

AgentComposition.close

close() -> Dict[str, Any]

Close every framework-owned resource once and return a stable receipt.

Source

build_agent_composition

from qitos.config import build_agent_composition

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

composition = build_agent_composition(config, model_override=provider)
try:
    result = composition.session("Index the notes").run()
finally:
    composition.close()

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.

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`

load_agent_config

from qitos.config import load_agent_config

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

config = load_agent_config("agent.yaml")
print(config.digest())

Load one strict canonical configuration from YAML.

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`

AgentConfig

from qitos.config import AgentConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

config = load_agent_config("agent.yaml")
assert config.runtime.session.store == "sqlite"
print(config.to_dict()["model"]["credential"])

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)`

AgentConfig.to_dict

to_dict() -> Dict[str, Any]

Return deterministic JSON/YAML-safe canonical launch data.

Source

AgentConfig.digest

digest() -> str

Source

CredentialRef

from qitos.config import CredentialRef

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

reference = CredentialRef("notes-provider")
print(reference)

Serializable logical identity of one credential.

Field	Type	Default
`ref`	`str`	`required`

LocalCredentialFileResolver

from qitos.config import LocalCredentialFileResolver

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

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.

Resolve one logical credential from a hardened local YAML file.

LocalCredentialFileResolver(path: str | Path, *, repository_root: str | Path) -> None

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

LocalCredentialFileResolver.resolve

resolve(ref: CredentialRef) -> CredentialResolution

Parameter	Type	Default
`ref`	`CredentialRef`	`required`

Source

BudgetConfig

from qitos.config import BudgetConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

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`

EnvironmentConfig

from qitos.config import EnvironmentConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

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`

ModelConfig

from qitos.config import ModelConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

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`

RuntimeConfig

from qitos.config import RuntimeConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

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`	`''`

TrajectoryConfig

from qitos.config import TrajectoryConfig

Source @ d000a42 Usage and executable example Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

trajectory = TrajectoryConfig(output="./notes-run/trajectory.journal")

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

​FakeCredentialResolver

​AgentComposition

​AgentComposition.session

​AgentComposition.restore

​AgentComposition.fork

​AgentComposition.close

​build_agent_composition

​load_agent_config

​AgentConfig

​AgentConfig.to_dict

​AgentConfig.digest

​CredentialRef

​LocalCredentialFileResolver

​LocalCredentialFileResolver.resolve

​BudgetConfig

​EnvironmentConfig

​ModelConfig

​RuntimeConfig

​TrajectoryConfig

FakeCredentialResolver

AgentComposition

AgentComposition.session

AgentComposition.restore

AgentComposition.fork

AgentComposition.close

build_agent_composition

load_agent_config

AgentConfig

AgentConfig.to_dict

AgentConfig.digest

CredentialRef

LocalCredentialFileResolver

LocalCredentialFileResolver.resolve

BudgetConfig

EnvironmentConfig

ModelConfig

RuntimeConfig

TrajectoryConfig