symfonic.agent.types

types

Type definitions for the symfonic agent framework.

Provides the unified FrameworkTenantScope (bridging core and memory scopes), request/response models, streaming chunk types, and the exception hierarchy.

ActivationLogEntry

Bases: BaseModel

A single activated node from spreading activation.

AgentRequest

Bases: BaseModel

Inbound request for agent execution.

to_scope

to_scope() -> FrameworkTenantScope

Extract a FrameworkTenantScope from this request.

Source code in src/symfonic/agent/types.py

def to_scope(self) -> FrameworkTenantScope:
    """Extract a ``FrameworkTenantScope`` from this request."""
    return FrameworkTenantScope(
        tenant_id=self.tenant_id,
        sub_tenant_id=self.sub_tenant_id,
        namespace=self.namespace,
    )

AgentResponse

Bases: BaseModel

Response from agent execution.

Attachment

Bases: BaseModel

Non-text content to send alongside a query.

The semantic query string is used for HMS hydration and embeddings; attachments are forwarded to the LLM as additional content blocks but do NOT participate in memory hydration or tool routing in v1.

Attributes:

Name	Type	Description
kind	Literal['image', 'document']	Content type -- "image" or "document".
source_type	Literal['url', 'base64']	How data is encoded -- "url" (http/https only -- other schemes such as file:// are rejected to prevent SSRF) or "base64".
data	str	URL string or base64-encoded content.
media_type	str	MIME type (e.g. "image/png", "application/pdf"). Defaults to image/png for kind="image" and application/pdf for kind="document".
filename	str | None	Optional filename for documents / PDFs.

FrameworkTenantScope

Bases: TenantScope

Thin subclass of the unified TenantScope for the agent framework layer.

TenantScope in symfonic.core.scope now carries all three fields (tenant_id, sub_tenant_id, namespace), so this subclass only adds extra validation and the backward-compatible converter methods that existing consumers may still call.

from_core_scope classmethod

from_core_scope(scope: TenantScope) -> FrameworkTenantScope

Build from any TenantScope.

Source code in src/symfonic/agent/types.py

@classmethod
def from_core_scope(cls, scope: TenantScope) -> FrameworkTenantScope:
    """Build from any ``TenantScope``."""
    return cls(
        tenant_id=scope.tenant_id,
        sub_tenant_id=scope.sub_tenant_id,
        namespace=scope.namespace,
    )

from_memory_scope classmethod

from_memory_scope(
    scope: TenantScope,
) -> FrameworkTenantScope

Build from any TenantScope.

Source code in src/symfonic/agent/types.py

@classmethod
def from_memory_scope(cls, scope: TenantScope) -> FrameworkTenantScope:
    """Build from any ``TenantScope``."""
    return cls(
        tenant_id=scope.tenant_id,
        sub_tenant_id=scope.sub_tenant_id,
        namespace=scope.namespace,
    )

model_post_init

model_post_init(__context: Any) -> None

Validate that sub_tenant_id and namespace are consistent.

Source code in src/symfonic/agent/types.py

def model_post_init(self, __context: Any) -> None:
    """Validate that sub_tenant_id and namespace are consistent."""
    if (
        self.sub_tenant_id is not None
        and self.namespace is not None
        and self.sub_tenant_id != self.namespace
    ):
        raise ValueError(
            "sub_tenant_id and namespace must match when both are provided, "
            "or leave one as None for automatic mapping"
        )

to_core_scope

to_core_scope() -> TenantScope

Return self as TenantScope (identity — no conversion needed).

Source code in src/symfonic/agent/types.py

def to_core_scope(self) -> TenantScope:
    """Return self as ``TenantScope`` (identity — no conversion needed)."""
    return self

to_memory_scope

to_memory_scope() -> TenantScope

Return self as TenantScope (identity — no conversion needed).

Source code in src/symfonic/agent/types.py

def to_memory_scope(self) -> TenantScope:
    """Return self as ``TenantScope`` (identity — no conversion needed)."""
    return self

HydratedMemory

Bases: BaseModel

Typed result from memory hydration.

Returned by SymfonicAgent._hydrate(). Replaces the previous tuple[dict[str, Any], int] return type with a structured model that makes all hydration fields explicit and type-safe.

MemoryBlockStatus

Bases: BaseModel

API response model for a single memory block's status.

ScopeValidationError

ScopeValidationError(message: str, code: str | None = None)

Bases: SymfonicAgentError

Raised when tenant scope validation fails.

Source code in src/symfonic/agent/types.py

def __init__(self, message: str, code: str | None = None) -> None:
    super().__init__(message)
    self.code = code

SecurityScopeError

SecurityScopeError(message: str, code: str | None = None)

Bases: SymfonicAgentError

Raised when tenant scope is missing or invalid for a security-critical operation.

Source code in src/symfonic/agent/types.py

def __init__(self, message: str, code: str | None = None) -> None:
    super().__init__(message)
    self.code = code

StreamChunk

Bases: BaseModel

A single streaming event from the agent.

SymfonicAgentError

SymfonicAgentError(message: str, code: str | None = None)

Bases: Exception

Base exception for all agent framework errors.

Source code in src/symfonic/agent/types.py

def __init__(self, message: str, code: str | None = None) -> None:
    super().__init__(message)
    self.code = code

TranscriptUnsupportedError

TranscriptUnsupportedError(
    message: str, code: str | None = None
)

Bases: SymfonicAgentError

Raised when a transcript query needs a saver capability it lacks (v7.27.0).

get_transcript(time_range=...) requires the checkpointer to support alist (to read per-checkpoint timestamps). A minimal saver without alist cannot honour a time-range query, so the engine fails loud (naming the saver class) rather than silently returning [] -- a silent empty result is indistinguishable from "no messages in range" and would mislead callers. Ordinal (index) and full-transcript reads use aget_tuple and are unaffected.

Source code in src/symfonic/agent/types.py

def __init__(self, message: str, code: str | None = None) -> None:
    super().__init__(message)
    self.code = code