Skip to content

Examples Catalog

Catalog of the example applications in the framework's examples/ directory, organized from simplest to most complex.

Getting a runnable copy of an example

pip install symfonic-core installs the library only — the examples/ directory is not importable from a plain install. You have two ways to get a runnable example:

1. From an install (recommended) — symfonic examples add. The curated single-file examples are bundled in the wheel as data. Copy one into your project and run it, no checkout required:

pip install "symfonic-core[cli]"
symfonic examples list                 # see what's available
symfonic examples add minimal_agent    # copies ./minimal_agent/
python -m minimal_agent                # run it

Available via the CLI: minimal_agent, basic_agent, tool_agent, skill_agent, sub_agents, memory_agent, e2e_basic_agent — all run on MockModelProvider (no API key, no extra dependencies). Plus real_agent, which runs against a real Anthropic model:

pip install "symfonic-core[cli,anthropic]"
export ANTHROPIC_API_KEY=sk-ant-...
symfonic examples add real_agent
python -m real_agent "What is the largest planet?"

symfonic examples list prints each example's requirements; add restates them after copying.

2. From a source checkout. Clone the repo and run examples from the repo root — it's running from the root (which puts examples on sys.path), not the install mode, that makes python -m examples.<name> work. Install the extras an example needs first:

git clone <repo-url> symfonic-core && cd symfonic-core
pip install -e ".[dev]"                # pulls the extras some examples need
python -m examples.minimal_agent       # run from the repo root

The PyPI source tarball (sdist) also bundles a curated subset — minimal_agent, basic_agent, tool_agent, skill_agent, sub_agents, memory_agent, e2e_basic_agent, real_agent, demo_app, full_demo, tui_chat. Every other example here (e.g. agent_with_memory, callback_logging, the rest of the real_* set, advanced, server_v1.py) exists only in the repository.

No API keys required unless noted. All examples use MockModelProvider and in-memory stores by default.

Full-code walkthroughs

The core learning-path examples each have a dedicated page with the complete source and a step-by-step explanation of every line — so you can read the code without a source checkout. Look for the → Full walkthrough link under each. Start with minimal_agent.

Level 1: Fundamentals

minimal_agent

Absolute minimum to run an agent. Demonstrates AgentGraph, AgentRuntime, BaseAgentDeps, and ModelProvider with InMemoryDocumentStore.

  • Lines: ~42
  • Prerequisites: None
  • Key concepts: AgentConfig, AgentGraph, AgentRuntime, BaseAgentDeps

→ Full walkthrough & step-by-step code

python -m examples.minimal_agent

basic_agent

SymfonicAgent (the high-level orchestrator) in under 10 lines. Uses the symfonic.agent layer instead of raw symfonic.core.

  • Lines: ~43
  • Prerequisites: None
  • Key concepts: SymfonicAgent, FrameworkConfig, FrameworkTenantScope

→ Full walkthrough & step-by-step code

python -m examples.agent.basic_agent

Level 2: Tools and Skills

tool_agent

Capability-based tool filtering with ToolRegistry. Two tools registered with different capability requirements; only the matching tool appears in the active set.

  • Lines: ~49
  • Prerequisites: None
  • Key concepts: ToolRegistry, capability filtering, requires declaration

→ Full walkthrough & step-by-step code

python -m examples.tool_agent

skill_agent

Skill management with SkillStore protocol and InMemorySkillStore. Demonstrates creating, filtering, and formatting skills for prompt injection.

  • Lines: ~42
  • Prerequisites: None
  • Key concepts: SkillStore, Skill model, filter_skills, format_skills_list

→ Full walkthrough & step-by-step code

python -m examples.skill_agent

tool_registry_demo

Advanced tool registration patterns with the ToolRegistry.

  • Prerequisites: None
  • Key concepts: ToolRegistry, tool metadata, dynamic registration
python -m examples.tool_registry_demo

skill_registry

Skill registry patterns for managing reusable skills.

  • Prerequisites: None
  • Key concepts: SkillStore, skill lifecycle, registry patterns
python -m examples.skill_registry

sub_agents

Delegation: a parent agent hands a self-contained task to a named child via the auto-registered run_agent('researcher', <task>) tool. Shows declaring a SubAgent, wiring children with SymfonicAgent(sub_agents=[...]), and a deterministic delegated call through SubAgentRegistry.

  • Lines: ~90
  • Prerequisites: None (runs on MockModelProvider)
  • Key concepts: SubAgent, SubAgentRegistry, sub_agents= wiring, run_agent / list_agents, depth guard
  • See also: Sub-agents (Delegation) guide

→ Full walkthrough & step-by-step code

python -m examples.sub_agents

Level 3: Memory

memory_agent

Persistent memory across agent turns using DocumentStore. Shows ContextInjectionNode loading stored documents into prompt context.

  • Lines: ~44
  • Prerequisites: None
  • Key concepts: DocumentStore, InMemoryDocumentStore, memory persistence

→ Full walkthrough & step-by-step code

python -m examples.memory_agent

agent_with_memory

Full round-trip: populate a DocumentStore, use memory_read / memory_write / memory_search tools via protocol-based DI, then run an agent that leverages document context.

  • Lines: ~99
  • Prerequisites: None
  • Key concepts: DocumentStore, memory tools, metadata round-trips
python -m examples.agent_with_memory

Level 4: Integration

e2e_basic_agent

Everything together: PromptBuilder with composable sections, stream event processing, capability error handling, and a full agent run with a custom system prompt.

  • Lines: ~80
  • Prerequisites: None
  • Key concepts: PromptBuilder, ScopeSection, MemorySection, SkillsSection, stream events, CapabilityError

→ Full walkthrough & step-by-step code

python -m examples.e2e_basic_agent

callback_logging

Demonstrates the callback and observability system with logging hooks.

  • Prerequisites: None
  • Key concepts: CallbackHandler, ObservabilityHook, event tracing
python -m examples.callback_logging

fastapi_app

FastAPI wrapper around SymfonicAgent using create_agent_router(). Shows the minimal HTTP server setup.

  • Lines: ~55
  • Prerequisites: pip install symfonic-core[agent-api]
  • Key concepts: create_agent_router, FastAPI integration, multi-tenant headers
uvicorn examples.agent.fastapi_app:app --reload

Level 5: Production Patterns

demo_app

Production-like application structure with organized modules:

  • deps.py -- Dependency setup
  • state.py -- Custom state schema
  • sections/ -- Custom prompt sections
  • capabilities/ -- External capability wrappers
  • fixtures/ -- Test data

→ Full walkthrough & project structure

Run modes:

python -m examples.demo_app              # Mock mode (default)
python -m examples.demo_app --mode real  # Real LLM (requires API key)
python -m examples.demo_app --mode e2e   # End-to-end mode

Level 6: Real LLM Examples

These examples require an Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-...

real_agent

Minimal agent with real Anthropic Claude provider.

  • Prerequisites: pip install symfonic-core[anthropic], API key
  • Key concepts: AnthropicProvider, real LLM integration

→ Full walkthrough & step-by-step code · copy it with symfonic examples add real_agent

python -m examples.real_agent

real_agent_with_memory

Real Anthropic provider with InMemoryDocumentStore. Demonstrates searching documents via protocol-based tools and injecting context into the system prompt for Claude to reason about.

  • Prerequisites: pip install symfonic-core[anthropic], API key
  • Key concepts: AnthropicProvider, DocumentStore, custom system prompt
python -m examples.real_agent_with_memory

real_skill_registry

Skill registry with a real LLM for dynamic skill creation and retrieval.

  • Prerequisites: pip install symfonic-core[anthropic], API key
  • Key concepts: SkillStore, real LLM skill generation
python -m examples.real_skill_registry

real_tool_registry

Tool registry with a real LLM for dynamic tool selection.

  • Prerequisites: pip install symfonic-core[anthropic], API key
  • Key concepts: ToolRegistry, real LLM tool routing
python -m examples.real_tool_registry

Level 7: Full Demo

full_demo

Complete production-like application with web UI demonstrating all symfonic-core features:

  • All 5 HMS memory layers (Semantic, Episodic, Working, Procedural, Prospective)
  • Postgres primary + MongoDB secondary for graph visualization
  • Deep Sleep consolidation (7-phase)
  • Spreading activation with activation_log
  • Domain plugin configuration (DomainTemplate with SOUL schema)
  • SemanticMerge deduplication for procedures
  • AnomalyDetection sub-agent
  • InProcessScheduler and optional Celery tasks
  • PDF reports, charts, semantic search tools
  • Full observability: traces, analytics, session replay
  • Multi-tenant chat UI with SSE streaming

→ Full walkthrough & project structure

Prerequisites:

pip install -e ".[agent-api,anthropic,mongodb]"

Run modes:

# In-memory (no infrastructure)
python -m examples.full_demo.server

# With Postgres + MongoDB (full persistence)
docker compose up -d
POSTGRES_DSN=postgresql://symfonic:symfonic_dev@localhost:5432/symfonic \
  MONGODB_URI=mongodb://localhost:27018/symfonic \
  python -m examples.full_demo.server

# Real LLM without infrastructure
ANTHROPIC_API_KEY=sk-ant-... python -m examples.full_demo.server

Open http://localhost:8000 in your browser.

See examples/full_demo/README.md for full feature documentation.

Advanced Examples

See examples/advanced/README.md for contributor-tier examples that may require external services or API keys.

Standalone Server Script

server_v1.py

Top-level server script at examples/server_v1.py for quick-start deployment.

python examples/server_v1.py

Next Steps

After completing the learning path:

  1. Read Integration Guide for step-by-step library usage.
  2. Read API Reference for endpoint documentation.
  3. Read Architecture for the full module map.
  4. Read Memory Concepts for the 5-layer HMS deep dive.
  5. Browse tests/ for contract tests and integration patterns.