echo-sdk

Router for any non-trivial echo-sdk task. Maps user intent to the right module skill and diagram. Invoke FIRST for any change to src/echo/ before reaching for a specific module skill.

Recipe for adding a new provider (LLM, transcriber, eval, prompt). Use whenever adding Cohere, Mistral, Deepgram, Phoenix, Promptlayer, etc. — anything that plugs into an existing get_*() factory.

End-to-end recipe for defining a Skill bundle and wiring it into a GenericAgent with the right activation mode and tool registry. Use when extending agent capability via swappable skills rather than baking tools in.

Building agents with BaseAgent / GenericAgent, including skill registration, activation modes (llm vs manual), and system-prompt composition. Use when editing src/echo/agents/ or building a new agent subclass.

Audio transcription provider abstraction (Gemini, EkaCare). Use when transcribing audio, adding a new transcriber, or shaping AudioInput.

Postgres support — asyncpg client, schema-aware binder, PgQueryTool surface. Use when querying postgres from a tool, modifying the binder, or adding a new DB engine.

Evaluation provider abstraction for dataset experiments (Langfuse today). Use when running an experiment, adding a new eval backend, or wiring evals into CI.

LLM provider abstraction — get_llm factory, BaseLLM contract, agentic tool-calling loop, streaming, thinking config. Use when editing src/echo/llm/ or debugging provider behavior.

Conversation data model — ConversationContext, Message, ToolCall/ToolResult, polymorphic content. Use when reading/writing context, adding a new content type, or debugging tool-call pairing.

External prompt-provider abstraction (Langfuse today). Use when fetching prompts at runtime, adding a new prompt provider, or wiring agent config from a managed prompt.

Building tools — BaseTool contract, MCP tool wrapping, elicitation tools, schema conversion, tool_context injection. Use when adding a tool, debugging tool calls, or wiring an MCP server.

Default to no comments. Only write one when the WHY is non-obvious. Never comments that restate the code. Use any time you're about to write a comment.

Validate at system boundaries, trust internally. No defensive fallbacks for impossible cases. Use whenever adding try/except, validation, or null-checks.

Don't design for hypothetical future needs. Three similar lines beats a premature abstraction. Use whenever you're tempted to add a helper, base class, or config flag "in case".

Keep diffs surgical — no drive-by refactors, no opportunistic cleanups. Use whenever you're about to edit code.

Async/await rules for echo-sdk — never block the loop, cancellation safety, asyncio.gather over sequential awaits. Use any time you write or modify async code in src/echo/.

Avoiding memory leaks and resource leaks in echo-sdk — close async resources, generators over lists, avoid retain cycles. Use when touching anything that opens connections, spawns subprocesses, or holds references long-term.

How to add and guard optional dependencies (provider SDKs, asyncpg, langfuse, mcp, etc.) so the core package stays installable without extras. Use any time you import a provider SDK or DB driver.

Use orjson, never stdlib json. orjson is a hard dep of echo-sdk and used throughout. Fires any time you serialize/deserialize JSON.

uv + pyproject.toml conventions for echo-sdk — adding deps, extras, scripts; Python 3.11+. Use when editing pyproject.toml or running dep commands.

Pydantic v2 patterns used across echo-sdk configs and schemas — ConfigDict, model_validate, field_validator, no v1 patterns. Use when adding/editing config or schema models.

Conventions for tests in echo-sdk — pytest + pytest-asyncio, async fixtures, dotenv loading, mocking provider SDKs. Use when adding or modifying tests under tests/.

Type-hint rules for echo-sdk — no Any unless boundary, Protocol for structural typing, narrow Unions, PEP 604 syntax. Use when writing public API signatures.