symfonic.agent

agent

symfonic.agent -- High-level orchestration layer for multi-memory agents.

Integrates symfonic.core (execution engine) and symfonic.memory (5-layer HMS) into a unified, engine-first Python module with an optional FastAPI bridge.

Public API re-exports. Internal modules should not be imported directly.

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.

StreamChunk

Bases: BaseModel

A single streaming event from the agent.