Phase 3: Community & Ecosystem (v0.3.0)

[jkbennitt]

Phase 3 roadmap for the Felix Agent SDK. Builds on v0.2.1 (824 tests, 34 exports, 10 examples).

---

Confirmed

MCP Server (feat/mcp-server)

Wrap Felix workflows as MCP tools so Claude Desktop, Cursor, Windsurf, and other MCP clients can invoke them natively.

Three tools:

• run_workflow — accepts task description + template name or full config JSON → runs workflow → returns synthesis, confidence, metadata
• list_templates — returns available workflow templates (research, analysis, review) with descriptions and default configs
• validate_config — validates a workflow config without running it, returns errors/warnings

Uses the official Anthropic mcp SDK. Reuses the existing CLI yaml_loader for config parsing and run_command provider resolution. Adds felix-mcp console script entry point.

Community Infrastructure (feat/community)

• Expanded CONTRIBUTING.md: how to add memory backends, observability adapters, MCP tools. Code style guide.
• .github/ISSUE_TEMPLATE/: bug report + feature request templates
• .github/PULL_REQUEST_TEMPLATE.md: PR checklist
• New examples: 11_mcp_server.py, 12_vector_search.py, 13_observability.py
• CHANGELOG.md v0.3.0 section, version bump

---

Under Discussion — Feedback Requested

Vector DB Backends (feat/vector-backends)

Add semantic similarity search to KnowledgeStore via pluggable vector backends (ChromaDB, Pinecone).

What it adds:

• ChromaBackend(BaseBackend) and PineconeBackend(BaseBackend) implementing the existing 11-method backend interface
• BaseEmbeddingProvider interface with embed(text) → list[float] for provider-agnostic embeddings
• search_vector(table, embedding, limit) method on BaseBackend (optional, default NotImplementedError)
• Wires into KnowledgeStore.semantic_search() which currently raises NotImplementedError

Open question: Is this the right direction? The current BaseBackend.search_text() with FTS5 handles keyword search well. Adding vector search means users need an embedding model (OpenAI, local sentence-transformers) just to use the memory system. Is the complexity worth it at this stage, or should we focus on making the existing FTS5 search smarter first?

Observability Adapters (feat/observability)

Bridge EventBus events to production monitoring: OpenTelemetry spans/metrics, DataDog custom events/StatsD, Prometheus counters/histograms.

What it adds:

• BaseObservabilityAdapter(ABC) following the EventLogBridge pattern (subscribe to EventBus, transform events, provide detach())
• OpenTelemetryAdapter — workflow = parent span, rounds = child spans, tasks = leaf spans. Counters for rounds/tokens/confidence.
• DataDogAdapter — DogStatsD metrics + custom events with agent_type/phase tags
• PrometheusAdapter — felix_workflow_rounds_total, felix_task_confidence, felix_tokens_total gauges/counters

Open question: Are three adapters too many for a v0.3.0? Should we ship just OpenTelemetry (most universal) and let DataDog/Prometheus be community contributions? Or is there a different monitoring approach (structured JSON logs piped to any backend) that would be more practical?

---

Branching Strategy

Same as Phase 2: dev/phase-3 integration branch, feature PRs merge into it, final PR to main.

Stats Target

• Tests: 900+
• Public exports: ~42
• Examples: 13

[jkbennitt]

@CalebisGross — want your eyes on this before we go further.

Jason here. I've been leaning heavily on Claude (Opus 4.6) to move fast through Phase 2, and it's been productive — but I'm starting to worry we're drifting from your original vision for Felix. The AI is great at generating plausible architecture, but it doesn't have the context you do about why you built things the way you did.

Specifically, I want your gut check on the two items under discussion:

Vector DB Backends (ChromaDB, Pinecone): Claude's plan is to wire up KnowledgeStore.semantic_search() with vector backends and an embedding provider interface. But your original KnowledgeStore was deliberately lightweight — SQLite with FTS5. Adding vector search means every user suddenly needs an embedding model just to use memory. That's a big jump in complexity for what was designed to be a simple, self-contained system. Was there a reason you kept it keyword-based? Should we be going down this path at all, or is there a simpler approach that stays true to what you built?

Observability Adapters (OpenTelemetry, DataDog, Prometheus): Claude wants to build three separate monitoring adapters. That feels like enterprise bloat for an SDK that's supposed to be elegant and focused. Your original Felix didn't have any of this — the helix geometry and confidence monitoring are the observability. Do we actually need OpenTelemetry spans, or is the structured JSON logging we already have (EventLogBridge) enough? I don't want to turn this into a kitchen-sink framework.

I trust your instincts on this more than mine. If you think we're heading in the wrong direction on either of these, say so — I'd rather course-correct now than ship something that doesn't feel like Felix.

The MCP server and community docs are things I'm confident about. But these two... I want to hear from you first.

[CalebisGross]

kill Observability Adapters (feat/observability). check out what kind of db would be best suited for this kind of project. might need some more research.

mcp could be useful though, let's dig a little deeper.

community docs for sure

[jkbennitt]

Research done on both items. Posting findings for discussion.

---

Database Research: sqlite-vec (not ChromaDB/Pinecone)

@CalebisGross — you were right to push back. After researching the options, the answer isn't "add ChromaDB" — it's extend your existing SQLite approach with sqlite-vec.

What is sqlite-vec? A 150KB SQLite extension that adds vector columns and similarity search. No server, no cloud, no transitive dependencies. It sits right next to the FTS5 extension you already use.

Why it fits Felix:

• Your SQLiteBackend stays almost entirely intact — we just add vector column support
• Hybrid search: FTS5 keyword results + sqlite-vec similarity results merged via Reciprocal Rank Fusion. Best of both worlds in one .db file
• 150KB total vs ChromaDB at 500MB+ or LanceDB at 200MB+. Stays lightweight.
• Optional dependency (pip install felix-agent-sdk[vectors]). Without it, everything works exactly as today.
• At our scale (hundreds to low thousands of entries), brute-force vector search is sub-millisecond. No HNSW index needed.

What changes:

• SQLiteBackend gets search_vector() method
• KnowledgeStore.semantic_search() gets wired to it (currently raises NotImplementedError)
• New hybrid_search() combines both, falls back to keyword-only gracefully
• BaseProvider gets optional embed(text) method for generating vectors

What doesn't change: Everything Caleb built. Same BaseBackend interface, same operator filters, same FTS5 keyword search. Vector is additive.

Comparison: https://alexgarcia.xyz/blog/2024/sqlite-vec-hybrid-search/index.html

---

MCP Research: Outcome-Oriented Tools

The official mcp Python package (v1.26+) uses a decorator API. Here's what a Felix MCP server would look like:

5 tools:

Tool	What it does
felix_run_workflow	The main one. Takes task + template + optional config overrides. Returns synthesis + confidence + metadata.
felix_list_templates	Discovery. Returns research/analysis/review with descriptions and default configs.
felix_get_template_config	Inspect full config before committing to a run.
felix_validate_config	Validate YAML/JSON config, return errors.
felix_list_providers	Show available/configured LLM providers.

Design rationale: MCP best practices say design around outcomes, not API surface. Felix's value IS the orchestration — exposing create_team/run_round/synthesize separately would force the LLM to replicate Felix's loop. One composite run_workflow with discovery helpers is the right granularity.

Transport: stdio (default, local). Streamable HTTP for remote/multi-user later. SSE is deprecated.

Progress: EventBus events bridge to MCP ctx.report_progress() per round. Full token streaming isn't possible through MCP tools (single return value), but round-level progress works.

Registration: pip install "felix-agent-sdk[mcp]" then add "command": "felix-mcp" to client config (Claude Desktop, Cursor, Windsurf, Claude Code).

---

Revised Phase 3 Plan

1. feat/mcp-server — 5 tools, stdio transport, EventBus progress bridge
2. feat/sqlite-vec — extend SQLiteBackend with hybrid search, optional dep
3. feat/community — contributor docs, templates, examples, version bump
4. feat/observability — killed per Caleb's feedback

Waiting for your thoughts before we start building.