symfonic-core 4.9.0__py3-none-any.whl

symfonic/agent/__init__.py

@@ -0,0 +1,66 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from symfonic.agent.types import (
+        AgentRequest,
+        AgentResponse,
+        FrameworkTenantScope,
+        StreamChunk,
+    )
+
+__all__ = [
+    "AgentRequest",
+    "AgentResponse",
+    "DomainTemplate",
+    "FrameworkConfig",
+    "FrameworkTenantScope",
+    "HMSFactory",
+    "SessionManager",
+    "StreamChunk",
+    "SymfonicAgent",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazy-load public API symbols to avoid circular imports."""
+    if name in ("AgentRequest", "AgentResponse", "FrameworkTenantScope", "StreamChunk"):
+        from symfonic.agent import types
+
+        return getattr(types, name)
+
+    if name in ("DomainTemplate",):
+        from symfonic.agent import domain
+
+        return getattr(domain, name)
+
+    if name in ("FrameworkConfig",):
+        from symfonic.agent import config
+
+        return getattr(config, name)
+
+    if name in ("SymfonicAgent",):
+        from symfonic.agent import engine
+
+        return getattr(engine, name)
+
+    if name in ("HMSFactory",):
+        from symfonic.agent import factory
+
+        return getattr(factory, name)
+
+    if name in ("SessionManager",):
+        from symfonic.agent import sessions
+
+        return getattr(sessions, name)
+
+    raise AttributeError(f"module 'symfonic.agent' has no attribute {name!r}")

symfonic/agent/cli/__init__.py

@@ -0,0 +1 @@
+"""Symfonic agent CLI package."""

symfonic/agent/cli/main.py

@@ -0,0 +1,119 @@
+"""Symfonic agent CLI.
+
+Commands:
+    chat     -- Run a single query against the agent.
+    migrate  -- Placeholder for future HMS data migration.
+
+Usage:
+    python -m symfonic.agent.cli.main chat "Hello" --tenant-id t1
+    symfonic chat "Hello" --tenant-id t1
+    symfonic migrate old://db new://db
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+
+try:
+    import typer
+except ImportError as _err:  # pragma: no cover
+    raise ImportError(
+        "typer is required for the CLI. "
+        "Install it with: pip install symfonic-core[cli]"
+    ) from _err
+
+from symfonic.agent.config import FrameworkConfig
+from symfonic.agent.domain import DomainTemplate
+from symfonic.agent.engine import SymfonicAgent
+from symfonic.agent.types import AgentResponse, FrameworkTenantScope
+from symfonic.core.testing import MockModelProvider
+
+app = typer.Typer(
+    name="symfonic",
+    help="Symfonic agent command-line interface.",
+    add_completion=False,
+)
+
+
+@app.command()
+def chat(
+    query: str = typer.Argument(..., help="Query to send to the agent."),
+    tenant_id: str = typer.Option(..., "--tenant-id", help="Tenant identifier (required)."),
+    dsn: str | None = typer.Option(None, "--dsn", help="Postgres DSN for persistent memory."),
+    model: str = typer.Option("mock", "--model", help="Model provider name (default: mock)."),
+    enable_hms: bool = typer.Option(False, "--enable-hms", help="Enable HMS-aware system prompt."),
+    domain: str = typer.Option(
+        "default",
+        "--domain",
+        help="Domain template name. Use 'default' for generic agent. "
+        "Custom domains should be injected programmatically.",
+    ),
+) -> None:
+    """Run a single query against the Symfonic agent."""
+    if dsn:
+        typer.echo(
+            "Warning: --dsn is not yet wired to Postgres backends. Using in-memory.",
+            err=True,
+        )
+
+    if model == "mock":
+        provider = MockModelProvider(response=f"[mock] Responding to: {query}")
+    elif model == "anthropic":
+        try:
+            from symfonic.core.providers import AnthropicProvider  # pragma: no cover
+            provider = AnthropicProvider()  # pragma: no cover
+        except ImportError as exc:
+            typer.echo(
+                "Anthropic provider requires: pip install symfonic-core[anthropic]",
+                err=True,
+            )
+            raise SystemExit(1) from exc
+    else:
+        typer.echo(f"Unknown model provider: {model}. Use 'mock' or 'anthropic'.", err=True)
+        raise SystemExit(1)
+    domain_template = DomainTemplate(name=domain)
+    config = FrameworkConfig(domain=domain_template)
+    agent = SymfonicAgent(
+        model_provider=provider, config=config, enable_hms_prompt=enable_hms,
+    )
+    scope = FrameworkTenantScope(tenant_id=tenant_id)
+
+    if enable_hms:
+        print("Thinking (HMS enabled)...", file=sys.stderr)
+
+    async def _run_and_flush() -> AgentResponse:
+        response = await agent.run(query, scope=scope)
+        await agent.flush_background_tasks()
+        return response
+
+    start = time.monotonic()
+    response = asyncio.run(_run_and_flush())
+    elapsed_ms = (time.monotonic() - start) * 1000
+
+    typer.echo(response.final_response or "(no response)")
+    in_tok = len(query) // 3
+    out_tok = len(response.final_response or "") // 3
+    sys_tok = response.system_prompt_tokens
+    total_tok = in_tok + sys_tok + out_tok
+    print(
+        f"tokens=~{total_tok} (in=~{in_tok} +system=~{sys_tok} out=~{out_tok})  "
+        f"memory={response.memory_entries_used}  "
+        f"duration_ms={elapsed_ms:.1f}",
+        file=sys.stderr,
+    )
+
+
+@app.command()
+def migrate(
+    source_uri: str = typer.Argument(..., help="Source data URI."),
+    target_uri: str = typer.Argument(..., help="Target data URI."),
+) -> None:
+    """Migrate HMS data between storage backends (stub)."""
+    typer.echo(f"Migration from {source_uri} to {target_uri} is not yet implemented")
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

symfonic/agent/config.py

@@ -0,0 +1,103 @@
+"""FrameworkConfig -- unified configuration for the symfonic agent framework.
+
+Composes core AgentConfig and memory OrchestratorConfig with
+framework-specific behaviour flags.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from symfonic.agent.domain import DEFAULT_DOMAIN, DomainTemplate
+from symfonic.core.config import AgentConfig
+from symfonic.infra.protocols import NullScheduler, TaskSchedulerProtocol
+from symfonic.memory.orchestrator.config import OrchestratorConfig
+
+
+class FrameworkConfig(BaseModel, frozen=True):
+    """Immutable configuration composing core and memory configs.
+
+    Framework-specific flags control automatic hydration, consolidation,
+    lazy tool routing, and streaming.
+    """
+
+    agent: AgentConfig = Field(
+        default_factory=AgentConfig,
+        description="Core agent runtime configuration",
+    )
+    orchestrator: OrchestratorConfig = Field(
+        default_factory=OrchestratorConfig,
+        description="Memory orchestrator configuration",
+    )
+
+    # -- Framework behaviour flags -------------------------------------------
+
+    auto_hydrate: bool = Field(
+        default=True,
+        description="Automatically hydrate memory context before LLM execution",
+    )
+    auto_consolidate: bool = Field(
+        default=True,
+        description="Automatically extract and commit memories after execution",
+    )
+    lazy_tooling: bool = Field(
+        default=True,
+        description="Dynamically filter tools via CapabilityRouter per query",
+    )
+    streaming_enabled: bool = Field(
+        default=True,
+        description="Enable the stream() interface on SymfonicAgent",
+    )
+    enabled_layers: set[str] = Field(
+        default_factory=lambda: {
+            "working", "episodic", "semantic", "procedural", "prospective",
+        },
+        description="Set of memory layer names to hydrate during auto_hydrate",
+    )
+    domain: DomainTemplate = Field(
+        default_factory=lambda: DEFAULT_DOMAIN,
+        description="Pluggable domain template for business-specific behavior",
+    )
+    scheduler: Any = Field(
+        default=None,
+        description=(
+            "Optional TaskSchedulerProtocol implementation for background "
+            "task scheduling.  None uses NullScheduler (no-op)."
+        ),
+    )
+    spreading_activation: bool = Field(
+        default=True,
+        description=(
+            "Enable spreading activation: auto-fetch 1st-degree neighbor "
+            "nodes when semantic retrieval produces hits."
+        ),
+    )
+    self_reflection: bool = Field(
+        default=False,
+        description=(
+            "Enable post-interaction self-reflection to extract business "
+            "insights from the conversation and commit them to semantic memory."
+        ),
+    )
+    reflection_prompt: str | None = Field(
+        default=None,
+        description=(
+            "Custom prompt template for the InsightExtractor. "
+            "Overrides the default general-purpose extraction prompt. "
+            "Must contain a {conversation} placeholder."
+        ),
+    )
+
+    @property
+    def task_scheduler(self) -> TaskSchedulerProtocol:
+        """Return the configured scheduler or a NullScheduler fallback."""
+        if self.scheduler is not None:
+            return self.scheduler
+        return NullScheduler()
+
+    @classmethod
+    def with_defaults(cls) -> FrameworkConfig:
+        """Create a config with all default values."""
+        return cls()

symfonic/agent/domain.py

@@ -0,0 +1,74 @@
+"""DomainTemplate -- pluggable domain configuration for business-specific behavior.
+
+External apps inject their own domain logic by creating a DomainTemplate
+and passing it to FrameworkConfig. The framework stays generic; all
+business-specific labels, onboarding flows, and schema definitions live
+in the consuming application.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MonitoringBlueprint(BaseModel, frozen=True):
+    """Configuration for sub-agent monitoring and anomaly detection.
+
+    Defines thresholds, check intervals, and which metrics trigger
+    alerts. Consumed by monitoring skills (e.g. AnomalyDetectionSkill)
+    in the application layer.
+
+    Attributes:
+        anomaly_thresholds: Metric name to deviation percentage threshold.
+            When a metric deviates beyond this percentage, it triggers
+            an alert.  Example: ``{"sales": 20.0, "inventory": 30.0}``.
+        check_interval_seconds: How often automated checks should run.
+        alert_on: List of metric names to monitor.  Only metrics listed
+            here produce findings.
+    """
+
+    anomaly_thresholds: dict[str, float] = Field(default_factory=dict)
+    check_interval_seconds: int = 300
+    alert_on: list[str] = Field(default_factory=list)
+
+
+class DomainTemplate(BaseModel, frozen=True):
+    """Pluggable domain configuration for business-specific behavior.
+
+    External apps inject their own domain logic by creating a DomainTemplate
+    and passing it to FrameworkConfig. The framework stays generic.
+
+    Attributes:
+        name: Human-readable domain identifier (e.g. "amazon-expert").
+        required_labels: Graph labels the domain expects to exist.
+            Used by DiscoveryService to flag missing blocks as pending.
+        onboarding_checklist: Items the agent should collect during
+            initial conversations with a new tenant.
+        soul_schema: Schema definition for the SOUL label -- maps
+            field names to their expected types as strings.
+        description: Optional description of the domain's purpose.
+        tool_manifest: Short descriptions of available tools. Each entry
+            is ``"tool_name: short description"``.  Injected into the
+            system prompt so the LLM knows which tools exist without
+            loading full schemas upfront.
+        tool_catalog: Full JSON schemas keyed by tool name.  Used for
+            JIT hydration -- the engine loads the full schema only when
+            the LLM selects a tool from the manifest.
+        monitoring: Blueprint for sub-agent monitoring and anomaly
+            detection.  Provides thresholds, intervals, and alert
+            configuration.
+    """
+
+    name: str = "default"
+    required_labels: list[str] = Field(default_factory=list)
+    onboarding_checklist: list[str] = Field(default_factory=list)
+    soul_schema: dict[str, str] = Field(default_factory=dict)
+    description: str = ""
+    tool_manifest: list[str] = Field(default_factory=list)
+    tool_catalog: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    monitoring: MonitoringBlueprint = Field(default_factory=MonitoringBlueprint)
+
+
+DEFAULT_DOMAIN = DomainTemplate()