Skip to content

v0.2.0 — Drivers

Choose a tag to compare

View all tags
@kjoshi07 kjoshi07 released this 15 May 02:53
· 82 commits to main since this release
v0.2.0
9389631

AgentForge v0.2.0 — Drivers

The second coordinated release. v0.2 is the "complete the v0.1
surface" tag: every locked ABC from v0.1 (LLMClient,
EmbeddingClient, VectorStore, GraphStore, Reranker,
Migrator, chat history) now has at least one shipped driver in
tree, the production protocol runners for MCP and A2A are live,
vendor observability backends ship, and the deferred v0.2 follow-
ups have all landed. ADR-0015 coordinated release train: every
workspace member bumps to 0.2.0.

Highlights

  • 5 first-party LLM provider sister packages. Pick your
    provider with a single string-id swap — no caller code change.

    from agentforge import Agent

async with Agent(model="anthropic:claude-sonnet-4-7") as agent:
    print((await agent.run("Hi")).output)
# or "openai:gpt-4o", "litellm:groq/llama-3.3-70b",
# "ollama:llama3.1", "bedrock:us.anthropic.claude-sonnet-4-5-…"

    agentforge-anthropic declares {tools, json_mode, caching, thinking, streaming}; agentforge-openai declares {tools, json_mode, streaming, vision} plus text-embedding-3-*
    Matryoshka embeddings; agentforge-voyage and agentforge- ollama ship embedding clients; agentforge-litellm routes a
    single agent to 100+ underlying providers.

  • GitHub Copilot joins the AI-assistant scaffold. Every
    agentforge new now ships .github/copilot-instructions.md
    alongside AGENTS.md / CLAUDE.md / .cursorrules — so
    Copilot users get the same framework-aware idioms as Claude
    Code / Cursor / Aider users.

  • GraphRAG retrieval. Retriever(graph_expansion=…) composes
    with vector / hybrid / reranker (feat-023). Combine a Neo4j
    knowledge graph with a vector store and the retriever expands
    query hits along graph edges before ranking.

  • Native hybrid (BM25 + vector) on every shipped vector
    store.     Postgres tsvector / SQLite FTS5 / Neo4j fulltext /
    SurrealDB BM25 analyser — every driver passes
    run_hybrid_search_conformance (feat-022 + feat-025). RRF
    fusion, configurable from agentforge.yaml > retrieval:.

  • Reranker contract + 4 vendor sister packages.
    agentforge-reranker-sentence-transformers (local CrossEncoder),
    agentforge-reranker-cohere, agentforge-reranker-voyage,
    agentforge-reranker-mixedbread (feat-021). Wire from YAML
    under retrieval.reranker: and rerank top-N candidates.

  • Sentence-window streaming guardrails. safety_mode: "sentence-window" buffers per-token streams at sentence
    boundaries, runs OutputValidator.check_output on each
    sentence, and only emits validated chunks downstream.
    Tradeoff: small latency hit at sentence boundaries; gain:
    PII or unsafe content never reaches the client unredacted
    (feat-020 v0.3 polish).

  • Schema migrations framework. Forward up migrations across
    Postgres / SQLite / Neo4j / SurrealDB drivers + parameterised
    migrations for dimension-sensitive vector schemas (feat-024).
    agentforge db migrate walks the migrations directory.

  • Production protocol runners. MCP stdio + HTTP/SSE runner
    (feat-013 v0.2) and A2A HTTP + per-token streaming +
    discovery (feat-014 v0.2 + v0.3) — both swap in for the v0.1
    fake runners with no caller code change.

  • Vendor observability backends. agentforge-langfuse,
    agentforge-phoenix, agentforge-evidently, agentforge- statsd — pick the dashboard you already operate; the
    framework's on_step / on_finish hook fan-out plus v0.3
    polish (child spans, A2A trace propagation, content-based PII
    redaction) feeds it (feat-009 v0.2 + v0.3).

  • 34 workspace members, every one at 0.2.0. ADR-0015
    coordinated release train; every __version__ constant in
    tree matches.

What's new

Added

  • feat-003 v0.2 — first-party LLM provider sister packages.
    Five new Tier-3 modules following the Runner-Protocol +
    lazy-SDK-import pattern:
    • agentforge-anthropic — Anthropic native Messages API.
      Declares {tools, json_mode, caching, thinking, streaming}.
      Caching via cache_control: ephemeral breakpoints,
      extended thinking via thinking={"type": "enabled", "budget_tokens": ...}, per-token streaming via
      messages.stream().
    • agentforge-openai — OpenAI chat.completions +
      text-embedding-3-* embeddings. Declares
      {tools, json_mode, streaming} (+vision for gpt-4o*).
      Matryoshka dimension override on embeddings.
    • agentforge-voyage — Voyage AI embeddings
      (voyage-3-*, voyage-code-3, voyage-multimodal-3).
      Declares {matryoshka, multimodal} where applicable.
    • agentforge-litellm — wraps litellm.acompletion so a
      single agent routes to 100+ underlying providers.
      Conservatively declares only {tools}.
    • agentforge-ollama — local Ollama daemon via
      ollama.AsyncClient. Declares {tools, streaming}.
      OllamaEmbeddingClient requires explicit dimensions=
      since Ollama's API doesn't expose model→dim mapping.
  • feat-019 v0.2 — GitHub Copilot support. Every scaffolded
    agent now ships .github/copilot-instructions.md as a
    one-line pointer to the canonical AGENTS.md. Joins the
    existing CLAUDE.md and .cursorrules pointer files;
    inject_shared_scaffold picks the new file up automatically
    via _shared/.github/copilot-instructions.md. Unit test in
    test_new_cmd.py::test_scaffold_ships_ai_assistant_instructions
    guards against future drift.
  • feat-019 v0.2 polish — 5 new runbooks auto-discovered by
    agentforge docs: 17-add-reranker.md,
    18-add-hybrid-search.md, 19-add-graphrag.md,
    20-apply-schema-migrations.md,
    21-use-streaming-guardrails.md.
  • feat-021 — Reranker abstraction + 4 vendor sister packages.
    Reranker ABC + RerankResult + RetrievalConfig.reranker:
    config block + build_retriever_from_config wiring.
    Drivers: agentforge-reranker-sentence-transformers (local),
    agentforge-reranker-cohere, agentforge-reranker-voyage,
    agentforge-reranker-mixedbread.
  • feat-022 — BM25 + vector hybrid search.
    VectorStore.lexical_search ABC + BM25 reference impl +
    Retriever(mode="hybrid") with RRF fusion + agentforge.yaml
    retrieval.mode: hybrid + retrieval.rrf_k: knob.
  • feat-022 v0.2 follow-up — native lexical paths. Postgres
    uses to_tsvector + ts_rank_cd + GIN index. SQLite uses
    FTS5 + BM25 ranking. Both drivers pass
    run_hybrid_search_conformance against the in-memory
    baseline.
  • feat-023 — GraphRAG hybrid retrieval. GraphExpansion
    value + Retriever(graph_expansion=…) kwarg +
    RetrievalConfig.graph_expansion: config block. Composes
    cleanly with mode="hybrid" and reranker=….
  • feat-024 — Schema migrations framework. Migrator ABC +
    agentforge db migrate CLI command + per-driver
    implementations (Postgres / SQLite / Neo4j / SurrealDB). Down
    migrations deferred to v0.3.
  • feat-024 v0.3 polish — parameterised migrations.
    Migration files accept template parameters (vector
    dimensions, table names) so the same migration drives
    embeddings of different sizes without divergence.
  • feat-025 — Neo4jVectorStore + SurrealDB native lexical.
    Neo4jVectorStore ships vector search over Neo4j native
    vector indexes; SurrealDB's lexical_search switches from
    the in-memory BM25 fallback to the native BM25 analyser.
  • feat-013 v0.2 — production MCP runner. Live MCPStdioRunner
    • MCPHTTPRunner over the upstream MCP SDK. Replaces the v0.1
      FakeMCPRunner for production use; tests still inject the
      fake.
  • feat-014 v0.2 + v0.3 — production A2A runner + discovery +
    streaming.     A2AHTTPRunner over httpx + agent registry
    • per-token streaming + run_id / budget header propagation.
  • feat-009 v0.2 — vendor observability sister packages.
    • agentforge-langfuse — LangfuseHook over Langfuse SDK.
    • agentforge-phoenix — Arize Phoenix OTel collector wiring.
    • agentforge-evidently — drift / quality reports via
      Evidently (local JSON; Cloud dashboards deferred to v0.3).
    • agentforge-statsd — counter / timer fan-out for StatsD /
      DogStatsD daemons.
  • feat-009 v0.3 — OTel polish. Child spans for strategy
    iterations (ReAct / Plan-Execute / ToT / MultiAgent), A2A
    trace-context propagation, and content-based PII redaction
    in span attributes.
  • feat-020 v0.2 follow-up — chat history backends + Slack.
    agentforge-chat-history-postgres (asyncpg), agentforge- chat-history-redis (hiredis + cross-process session lock),
    agentforge-chat-slack adapter (SlackChatAdapter).
    Provider-aware tokeniser landed for token-budget truncation.
  • feat-020 v0.3 polish — sentence-window streaming
    guardrails.     ChatSessionConfig.safety_mode Literal expanded
    with "sentence-window"; _stream_per_token dispatches on
    the mode and runs OutputValidator.check_output on each
    completed sentence before emitting downstream.
    "stream-then-redact" accepted by the schema as an alias
    for now; true regex-inline stream-then-redact deferred to
    v0.3+.
  • feat-002 + feat-009 v0.3 polish — strategy streams +
    iteration spans.     PlanExecute.stream() / ToT.stream() /
    MultiAgent.stream() overrides land per-phase / per-depth
    / per-agent events. Matching strategy.iteration OTel spans.

Changed

  • All workspace members bumped to 0.2.0 per ADR-0015.
    Every __version__ constant in tree updated to match.
  • agentforge.providers resolver category picks up five
    new registrations at import time: anthropic, openai,
    ollama, litellm (plus existing bedrock).
    agentforge.embeddings picks up openai, voyage,
    ollama (plus existing bedrock).
  • CI workflow split per-OS. .github/workflows/ci.yml
    became ci-linux.yml (per-PR gate), ci-windows.yml +
    ci-mac.yml (workflow_dispatch only). Cuts ~⅔ of per-PR
    CI minutes; trigger Windows / macOS runs manually before
    cutting a release.
  • ChatSessionConfig.safety_mode Literal gains
    "sentence-window". Additive; default stays
    "buffer-then-stream".

Deprecated

  • Nothing newly deprecated in v0.2. The v0.1
    agentforge_chat_http.BearerAuthPolicy alias remains; planned
    removal still v0.3.

Removed

  • Nothing.

Fixed

  • Nothing release-blocking; per-feature fixes are recorded in
    the matching PR.

Security

  • Bandit clean across every package. bandit -c pyproject.toml
    runs on every PR via ci-linux.yml.
  • New provider sister packages register # pragma: no cover on
    the production SDK runner — coverage stays ≥ 90% because the
    contract surface is fully tested via the Runner Protocol
    fake.

Breaking changes

None. v0.2 only adds to the locked surface; every v0.1
caller continues to work unchanged. The string-id model swap
("bedrock:…" → "anthropic:…") is purely additive — old
strings keep resolving.

Migration guide

No required migrations. Optional upgrades:

Pick a different LLM provider

 from agentforge import Agent

-async with Agent(model="bedrock:us.anthropic.claude-sonnet-4-5-20250929") as agent:
+async with Agent(model="anthropic:claude-sonnet-4-7") as agent:
     result = await agent.run("Say hello.")

Install the matching sister package (pip install "agentforge-anthropic[anthropic]") and the provider registers
itself at import time.

Enable sentence-window streaming guardrails

 # agentforge.yaml
 modules:
   chat:
     session:
-      safety_mode: buffer-then-stream
+      safety_mode: sentence-window

Validated sentences are emitted as ChatChunk(kind="text")
once each sentence boundary is reached.

Pick up the new runbooks in an existing scaffolded agent

agentforge upgrade --to 0.2.0

Three-way merge per feat-011. The five new runbooks (17–21),
.github/copilot-instructions.md, and the polished provider
table in runbook 13 land in your scaffold's managed sections.
Custom blocks survive untouched.

Coordinated release train

Per ADR-0015, every framework release bumps every in-scope
workspace package to the same minor version simultaneously.
The release train cut on 2026-05-14 bumps every in-scope
package to 0.2.0:

Package Version Surface change
agentforge-core 0.2.0 Reranker ABC + RerankResult + Migrator ABC + GraphExpansion value + RetrievalConfig (mode / rrf_k / reranker / graph_expansion) + ChatSessionConfig.safety_mode Literal expanded.
agentforge 0.2.0 Retriever(mode="hybrid", graph_expansion=…, reranker=…); agentforge db migrate CLI; strategy stream() overrides; OTel iteration spans + content-based PII redaction.
agentforge-bedrock 0.2.0 No new surface; rebuilt against 0.2.0 core.
agentforge-memory-sqlite 0.2.0 Native FTS5 + BM25 lexical_search; migration framework integration.
agentforge-memory-postgres 0.2.0 Native tsvector + ts_rank_cd lexical_search; migration framework integration; parameterised migrations.
agentforge-memory-neo4j 0.2.0 Native fulltext lexical_search; Neo4jVectorStore; migration framework integration.
agentforge-memory-surrealdb 0.2.0 Native BM25 analyser lexical_search; migration framework integration; parameterised migrations.
agentforge-eval-geval 0.2.0 Rebuilt against 0.2.0 core.
agentforge-otel 0.2.0 Strategy iteration child spans; A2A trace-context propagation; content-based PII redaction.
agentforge-testing 0.2.0 Rebuilt against 0.2.0 core.
agentforge-guard-llmguard / -presidio / -nemo / -llamaguard 0.2.0 Rebuilt against 0.2.0 core.
agentforge-mcp 0.2.0 Production MCP stdio + HTTP/SSE runners.
agentforge-a2a 0.2.0 Production HTTP runner + discovery + per-token streaming + run_id / budget propagation.
agentforge-chat 0.2.0 safety_mode: "sentence-window" (and "stream-then-redact" alias) wired into _stream_per_token.
agentforge-chat-http 0.2.0 Rebuilt against 0.2.0 core.
agentforge-chat-history-postgres 0.2.0 New — asyncpg-backed ChatHistoryStore.
agentforge-chat-history-redis 0.2.0 New — hiredis-backed history + cross-process RedisSessionLock.
agentforge-chat-slack 0.2.0 New — SlackChatAdapter over slack_sdk.
agentforge-statsd 0.2.0 New — StatsDHook over statsd / DogStatsD.
agentforge-langfuse 0.2.0 New — LangfuseHook.
agentforge-phoenix 0.2.0 New — Arize Phoenix OTel collector wiring.
agentforge-evidently 0.2.0 New — drift / quality JSON reports.
agentforge-reranker-sentence-transformers 0.2.0 New — local CrossEncoder reranker.
agentforge-reranker-cohere 0.2.0 New — Cohere Rerank API driver.
agentforge-reranker-voyage 0.2.0 New — Voyage Rerank API driver.
agentforge-reranker-mixedbread 0.2.0 New — Mixedbread Rerank API driver.
agentforge-anthropic 0.2.0 New — Anthropic native Messages API + caching + thinking + streaming.
agentforge-openai 0.2.0 New — OpenAI chat.completions + text-embedding-3-* embeddings (Matryoshka).
agentforge-voyage 0.2.0 New — Voyage AI embeddings (matryoshka + multimodal).
agentforge-litellm 0.2.0 New — LiteLLM router wrapper (100+ underlying providers).
agentforge-ollama 0.2.0 New — local Ollama daemon (chat + embeddings).

34 packages total at 0.2.0 (up from 18 at 0.1.0).

Cross-language status

Per ADR-0002, Python ships first during 0.x; TypeScript catches
up to parity by v0.4.

  • Python: released as 0.2.0 on PyPI.
  • TypeScript: not yet started. The typescript/agentforge-ts/
    workspace is empty. TS parity to Python's v0.2 surface is
    slated for v0.4.

Install / upgrade

# New install — pick the provider(s) you need
pip install "agentforge[anthropic]==0.2.0"
# or
pip install "agentforge[openai]==0.2.0" "agentforge-memory-postgres==0.2.0"

# From a fresh scaffold
pip install agentforge==0.2.0
agentforge new my-agent --template minimal
cd my-agent
agentforge run "Hi"

# Upgrade an existing scaffolded agent
agentforge upgrade --to 0.2.0

(Three-way merge per feat-011; review the diff before
accepting.)

Shipped features

Spec Surface delivered in v0.2.0
feat-002 v0.3 polish PlanExecute.stream() / ToT.stream() / MultiAgent.stream() per-phase / per-depth / per-agent event overrides.
feat-003 v0.2 5 first-party LLM provider sister packages (-anthropic / -openai / -voyage / -litellm / -ollama).
feat-009 v0.2 + v0.3 4 vendor observability sister packages (Langfuse / Phoenix / Evidently / StatsD) + OTel polish (child spans, A2A trace propagation, content-based PII redaction).
feat-013 v0.2 Production MCP stdio + HTTP/SSE runners.
feat-014 v0.2 + v0.3 Production A2A HTTP runner + discovery + per-token streaming + run_id / budget header propagation.
feat-019 v0.2 5 new runbooks (17–21); GitHub Copilot instructions; provider-capability table polish for runbook 13.
feat-020 v0.2 + v0.3 Postgres / Redis history backends + Slack adapter + cross-process session lock + provider-aware tokeniser; sentence-window streaming output guardrails.
feat-021 Reranker ABC + 4 vendor sister packages (sentence-transformers / Cohere / Voyage / Mixedbread).
feat-022 BM25 + vector hybrid search; native lexical paths for Postgres (tsvector) + SQLite (FTS5).
feat-023 GraphRAG retrieval — Retriever(graph_expansion=…).
feat-024 Schema migrations framework + agentforge db migrate + parameterised migrations.
feat-025 Neo4jVectorStore + SurrealDB native BM25 lexical search.

Acknowledgements

Thanks to kjoshi — designer, implementer, reviewer across
the v0.2 cycle. Generated with Claude
Code (Anthropic) as the
primary AI co-author across every feat-NNN PR per the
Co-Authored-By: commit trailers.

Full changelog

What's next — v0.3.0 backlog

Tracked in docs/roadmap.md. Summary:

  • down migrations / schema rollback (feat-024 v0.3+).
  • Native single-Cypher / SurrealQL graph-augmented retrieval
    (feat-023 sister-package follow-ups).
  • Multi-cluster Redlock for RedisSessionLock (feat-020 v0.3+).
  • True streaming-aware stream-then-redact (regex-inline
    redaction without buffering) (feat-020 v0.3+).
  • Evidently real-time drift dashboards via Cloud
    (feat-009 v0.3+).
  • Optional eval adapters: agentforge-eval-ragas /
    -deepeval / -toxicity / -codeexec.
  • TypeScript port of the v0.2 surface (target: v0.4).
Assets 2
Loading