Config¶

Bases: BaseModel

Per-model launch parameters for local providers.

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• num_ctx (int | None)
• num_gpu_layers (int | None)
• num_threads (int | None)
• num_batch (int | None)
• repeat_penalty (float | None)

repeat_penalty = None

Bases: BaseModel

Configuration for an LLM provider.

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• driver (NotBlankStr)
• litellm_provider (NotBlankStr | None)
• family (NotBlankStr | None)
• auth_type (AuthType)
• connection_name (NotBlankStr | None)
• api_key (NotBlankStr | None)
• subscription_token (NotBlankStr | None)
• tos_accepted_at (AwareDatetime | None)
• base_url (NotBlankStr | None)
• oauth_token_url (NotBlankStr | None)
• oauth_client_id (NotBlankStr | None)
• oauth_client_secret (NotBlankStr | None)
• oauth_scope (NotBlankStr | None)
• custom_header_name (NotBlankStr | None)
• custom_header_value (NotBlankStr | None)
• models (tuple[ProviderModelConfig, ...])
• retry (RetryConfig)
• rate_limiter (RateLimiterConfig)
• subscription (SubscriptionConfig)
• degradation (DegradationConfig)
• defaults (ProviderModelDefaults)
• preset_name (NotBlankStr | None)

Validators:

• _validate_auth_fields
• _warn_embedded_api_key
• _validate_unique_model_identifiers

driver = 'litellm'

litellm_provider = None

family = None

auth_type = API_KEY

connection_name = None

api_key = None

subscription_token = None

tos_accepted_at = None

base_url = None

oauth_token_url = None

oauth_client_id = None

oauth_client_secret = None

oauth_scope = None

custom_header_name = None

custom_header_value = None

models = ()

retry

rate_limiter

subscription

degradation

defaults

preset_name = None

Bases: BaseModel

Configuration for a single LLM model within a provider.

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• id (NotBlankStr)
• alias (NotBlankStr | None)
• cost_per_1k_input (float)
• cost_per_1k_output (float)
• max_context (int)
• estimated_latency_ms (int | None)
• local_params (LocalModelParams | None)

id

alias = None

cost_per_1k_input = 0.0

cost_per_1k_output = 0.0

max_context = 200000

estimated_latency_ms = None

local_params = None

Bases: BaseModel

A single model routing rule.

At least one of role_level or task_type must be set so the rule can match incoming requests.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• role_level (SeniorityLevel | None)
• task_type (NotBlankStr | None)
• preferred_model (NotBlankStr)
• fallback (NotBlankStr | None)

Validators:

• _at_least_one_matcher

role_level = None

task_type = None

preferred_model

fallback = None

Bases: BaseModel

Model routing configuration.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• strategy (NotBlankStr)
• rules (tuple[RoutingRuleConfig, ...])
• fallback_chain (tuple[NotBlankStr, ...])

Validators:

• _apply_mirrors

strategy = 'cost_aware'

rules = ()

fallback_chain = ()

Bases: BaseModel

Agent configuration from YAML.

Uses raw dicts for personality, model, memory, tools, and authority because :class:~synthorg.core.agent.AgentIdentity has runtime fields (id, hiring_date, status) that are not present in config. The engine constructs full AgentIdentity objects at startup.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• name (NotBlankStr)
• role (NotBlankStr)
• department (NotBlankStr)
• level (SeniorityLevel)
• personality_preset (NotBlankStr | None)
• personality (dict[str, Any])
• model (dict[str, Any])
• memory (dict[str, Any])
• tools (dict[str, Any])
• authority (dict[str, Any])
• autonomy_level (AutonomyLevel | None)
• strategic_output_mode (StrategicOutputMode | None)
• tier (Literal['large', 'medium', 'small'] | None)
• model_requirement (dict[str, Any] | None)

name

role

department

level = MID

personality_preset = None

personality

model

memory

tools

authority

autonomy_level = None

strategic_output_mode = None

tier = None

model_requirement = None

Bases: BaseModel

Configuration for graceful shutdown behaviour.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• strategy (Literal['cooperative_timeout', 'immediate', 'finish_tool', 'checkpoint'])
• grace_seconds (float)
• cleanup_seconds (float)
• tool_timeout_seconds (float)

strategy = 'cooperative_timeout'

grace_seconds = 30.0

cleanup_seconds = 5.0

tool_timeout_seconds = 60.0

Bases: BaseModel

Configuration for task assignment behaviour.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• strategy (NotBlankStr)
• min_score (float)
• max_concurrent_tasks_per_agent (int)

Validators:

• _validate_strategy_name

strategy = 'role_based'

min_score = 0.1

max_concurrent_tasks_per_agent = 5

Bases: BaseModel

Root company configuration -- the top-level validation target.

Aggregates all sub-configurations into a single frozen model that represents a fully validated company setup.

Attributes:

Config:

• frozen: True
• allow_inf_nan: False
• extra: forbid

Fields:

• company_name (NotBlankStr)
• company_type (CompanyType)
• departments (tuple[Department, ...])
• agents (tuple[AgentConfig, ...])
• custom_roles (tuple[CustomRole, ...])
• config (CompanyConfig)
• budget (BudgetConfig)
• communication (CommunicationConfig)
• providers (dict[str, ProviderConfig])
• routing (RoutingConfig)
• logging (LogConfig | None)
• graceful_shutdown (GracefulShutdownConfig)
• workflow_handoffs (tuple[WorkflowHandoff, ...])
• escalation_paths (tuple[EscalationPath, ...])
• coordination_metrics (CoordinationMetricsConfig)
• task_assignment (TaskAssignmentConfig)
• memory (CompanyMemoryConfig)
• persistence (PersistenceConfig)
• cost_tiers (CostTiersConfig)
• org_memory (OrgMemoryConfig)
• api (ApiConfig)
• sandboxing (SandboxingConfig)
• mcp (MCPConfig)
• security (SecurityConfig)
• trust (TrustConfig)
• promotion (PromotionConfig)
• performance (PerformanceConfig)
• training (TrainingConfig)
• task_engine (TaskEngineConfig)
• queue (QueueConfig)
• coordination (CoordinationSectionConfig)
• strategy (StrategyConfig)
• git_clone (GitCloneNetworkPolicy)
• backup (BackupConfig)
• workflow (WorkflowConfig)
• notifications (NotificationConfig)
• integrations (IntegrationsConfig)
• a2a (A2AConfig)
• ontology (OntologyConfig)
• telemetry (TelemetryConfig)
• web (WebToolsConfig | None)
• database (DatabaseConfig | None)
• terminal (TerminalConfig | None)
• design_tools (DesignToolsConfig | None)
• communication_tools (CommunicationToolsConfig | None)
• analytics_tools (AnalyticsToolsConfig | None)
• tool_disclosure (ToolDisclosureConfig)

Validators:

• _validate_unique_agent_names
• _validate_unique_department_names
• _validate_queue_requires_distributed_bus
• _validate_routing_references
• _validate_degradation_fallback_providers

company_name

company_type = CUSTOM

departments = ()

agents = ()

custom_roles = ()

config

budget

communication

providers

routing

logging = None

graceful_shutdown

workflow_handoffs = ()

escalation_paths = ()

coordination_metrics

task_assignment

memory

persistence

cost_tiers

org_memory

api

sandboxing

mcp

security

trust

promotion

performance

training

task_engine

queue

coordination

strategy

git_clone

backup

workflow

notifications

integrations

a2a

ontology

telemetry

web = None

database = None

terminal = None

design_tools = None

communication_tools = None

analytics_tools = None

tool_disclosure

Source location for a configuration error.

Attributes:

Bases: DomainError

Base exception for configuration errors.

Attributes:

44
45
46
47
48
49
50
51

def __init__(
    self,
    message: str,
    locations: tuple[ConfigLocation, ...] = (),
) -> None:
    self.message = message
    self.locations = locations
    super().__init__(message)

__str__()

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

def __str__(self) -> str:
    """Format error message with source locations."""
    if not self.locations:
        return self.message
    parts = [self.message]
    for loc in self.locations:
        loc_parts: list[str] = []
        if loc.key_path:
            loc_parts.append(f"  {loc.key_path}")
        if loc.file_path:
            if loc.line is not None and loc.column is not None:
                line_info = f" at line {loc.line}, column {loc.column}"
            elif loc.line is not None:
                line_info = f" at line {loc.line}"
            else:
                line_info = ""
            loc_parts.append(f"    in {loc.file_path}{line_info}")
        parts.extend(loc_parts)
    return "\n".join(parts)

Bases: ConfigError

Raised when a configuration file does not exist.

44
45
46
47
48
49
50
51

def __init__(
    self,
    message: str,
    locations: tuple[ConfigLocation, ...] = (),
) -> None:
    self.message = message
    self.locations = locations
    super().__init__(message)

Bases: ConfigError

Raised when YAML parsing fails.

44
45
46
47
48
49
50
51

def __init__(
    self,
    message: str,
    locations: tuple[ConfigLocation, ...] = (),
) -> None:
    self.message = message
    self.locations = locations
    super().__init__(message)

Bases: ConfigError

Raised when Pydantic validation fails.

Attributes:

107
108
109
110
111
112
113
114

def __init__(
    self,
    message: str,
    locations: tuple[ConfigLocation, ...] = (),
    field_errors: tuple[tuple[str, str], ...] = (),
) -> None:
    super().__init__(message, locations)
    self.field_errors = field_errors

__str__()

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

def __str__(self) -> str:
    """Format validation error with per-field details."""
    if not self.field_errors:
        return super().__str__()
    parts = [f"{self.message} ({len(self.field_errors)} errors):"]
    loc_by_key: dict[str, ConfigLocation] = {
        loc.key_path: loc for loc in self.locations if loc.key_path
    }
    for key_path, msg in self.field_errors:
        parts.append(f"  {key_path}: {msg}")
        loc = loc_by_key.get(key_path)
        if loc and loc.file_path:
            if loc.line is not None and loc.column is not None:
                line_info = f" at line {loc.line}, column {loc.column}"
            elif loc.line is not None:
                line_info = f" at line {loc.line}"
            else:
                line_info = ""
            parts.append(f"    in {loc.file_path}{line_info}")
    return "\n".join(parts)