feat(retrievers): add Dakera retriever

[ferhimedamine]

Fixes #569

Description

Adds DakeraRetriever, a Retriever backed by a self-hosted Dakera memory server. It uses Dakera's text-query API (server-side embedding) to fetch the most relevant documents for a query, so agents can use Dakera as a retrieval-augmented context source.

Design

• Mirrors AmazonKnowledgeBasesRetriever: an async Retriever subclass with a DakeraRetrieverOptions dataclass (namespace, api_key, url, top_k, filter).
• Config resolution: api_key → DAKERA_API_KEY env; url → DAKERA_URL env → http://localhost:3000 (the dakera-deploy default).
• retrieve / retrieve_and_combine_results call AsyncDakeraClient.query_text. retrieve_and_generate raises NotImplementedError (Dakera is retrieval-only).
• The dakera SDK is imported lazily inside __init__, so agent_squad.retrievers imports without it; it's added as an optional extra (pip install agent-squad[dakera]) alongside aws/anthropic/openai/sql.

Dependencies

Per CONTRIBUTING, flagging the dependency change: dakera>=0.12.8 is added only as an optional [dakera] extra (and to all) — no new core/runtime dependency. Happy to adjust if you'd prefer it handled differently.

Testing

python -m pytest src/tests/retrievers/test_dakera_retriever.py → 9 passed (mocked client, no live server needed). ruff check + ruff format --check on src/agent_squad are clean.

Docs (a retrievers/built-in/dakera-retriever.mdx page) and a TypeScript port can follow in a separate PR if you'd like — kept this one focused on the Python retriever. This is a community contribution; let me know any changes you'd like.

[ferhimedamine]

Added the docs page in 3c32720 (a built-in retrievers/built-in/dakera-retriever page with installation, config options, and agent + standalone usage, wired into the Retrievers sidebar) — so this PR now includes code, tests, and docs. A TypeScript port can follow separately if you'd like.

[ferhimedamine]

Added a TypeScript DakeraRetriever in 8486f53 so the integration is available in both languages (mirrors the Python one; uses the @dakera-ai/dakera client's queryText). Includes jest tests and a TypeScript tab in the docs. Validated locally: tsc --noEmit clean, eslint clean, jest 8/8 passing. This PR now covers Python + TypeScript + docs.

[cornelcroi]

Hey, @ferhimedamine thanks for the contribution! T

he Python side looks really solid — clean code, good tests, follows the existing patterns well. A few things need to be addressed before this can merge though:

Blockers:

1. The TypeScript @dakera-ai/dakera dependency is in dependencies, not peerDependencies. That means everyone who installs agent-squad gets this package even if they never use Dakera. The Python side handles this correctly
   with the optional extra (pip install agent-squad[dakera]). Would be good to make the TS side work the same way — move to peerDependencies and do a lazy import() with a try/catch in the constructor.
2. No linked issue. The CI checker will fail on this — you'll need to open an issue and add a Fixes #N to the PR description.
3. There's an unintentional version bump (1.1.0 → 1.1.1) in package.json / package-lock.json. Can you revert that?

Smaller things:

• Python wants dakera>=0.12.8 but TypeScript is on ^0.11.100 — are these the same release? Would be good to clarify.
• filter: this.options.filter as never in the TS code is a bit of a type hack, ideally use the actual type from the SDK.

Also — no pressure for this PR, but a Swift retriever would be a nice follow-up issue if you're interested.

[ferhimedamine]

Thanks for the feedback @cornelcroi
I will make the fixes suggested 🙏

[ferhimedamine]

Thanks for the detailed review @cornelcroi — all points addressed in 0b8d5e1.

Blockers

1. TS dependency → optional peer dependency. Moved @dakera-ai/dakera out of dependencies into peerDependencies with peerDependenciesMeta.optional = true (and devDependencies so tests/build still resolve it). The client is now loaded lazily via require("@dakera-ai/dakera") inside the constructor, wrapped in a try/catch that throws a clear install hint if it's missing — so installing agent-squad no longer pulls the SDK in unless the retriever is actually used, matching the Python [dakera] extra. (Used require rather than await import() since the package is dual CJS/ESM and the constructor is synchronous; functionally identical, and it keeps the eager-validation behavior.) Lockfile regenerated.

2. Linked issue. Opened Add a Dakera retriever #569 and added Fixes #569 to the PR description.

3. Version bump. package.json is at 1.1.1, which matches current main — there's no longer a version diff in this PR (main released 1.1.1 in the meantime). Reverting to 1.1.0 would put the branch below main; happy to set it to whatever you'd prefer.

Smaller things

• Python dakera>=0.12.8 vs TS ^0.11.100. They're two separate packages, versioned independently: dakera on PyPI (Python, latest 0.12.10) and @dakera-ai/dakera on npm (TypeScript, latest 0.11.102) — not the same release. Both ranges resolve to their respective latest; I've kept them as-is.
• filter as never. Replaced with the SDK's real FilterExpression type — DakeraRetrieverOptions.filter is now typed as FilterExpression (type-only import) and passed straight through, no cast.

Verified locally: tsc --noEmit clean, eslint clean, and the retriever test suite (8 tests) passes.

Re: the Swift retriever — happy to pick that up as a follow-up; I'll open a separate issue for it once this lands. Thanks again!

[ferhimedamine]

Added the Swift DakeraRetriever in fdd155c, so this PR now covers the retriever in all three languages (Python + TypeScript + Swift) with docs.

A design note, since the Swift SDK is structured differently from the Python/TS ones: there's no Retriever base class in Swift — agents ground their answers through tools (the GroundedAgent gather → present pattern). So rather than bolt on a foreign abstraction, I exposed Dakera the native way:

• DakeraRetriever is a ToolProvider that advertises a search_memory tool. Hand it to a GroundedAgent/Agent and the gatherer can call it to ground answers on remembered facts — it composes with AggregateToolProvider alongside other tools.
• It also offers a direct retrieve(_:) / retrieveAndCombineResults(_:) API for manual RAG, mirroring the Python/TS retrieve methods.

Other choices to match the repo:

• No new dependency. It calls Dakera's POST /v1/namespaces/{namespace}/query-text endpoint (server-side embedding) over URLSession, behind the existing HTTPInvoker seam — so, like the Python [dakera] extra / optional TS peer dep, installing agent-squad pulls in nothing extra.
• Config resolves apiKey from DAKERA_API_KEY and url from DAKERA_URL (default http://localhost:3000), same as the other two.
• 16 tests using a mock HTTPInvoker (request shape, response parsing, id coercion, validation, and the full ToolProvider surface) — no live server needed. Verified green on a Swift 6.2 toolchain (v6 language mode + ExistentialAny, matching Package.swift).
• Docs live under Swift → Tools → Built-in and are wired into the sidebar.

@cornelcroi
Happy to split this into a separate PR if you'd prefer to keep #553 to Python/TS — just let me know.

[cornelcroi]

Hey @ferhimedamine, the three blockers from my last review are addressed — issue linked, TS dependency is now a proper optional peer dep with lazy require(), and the version stays at 1.1.1 which matches main. The Python and TypeScript sides look solid to me. Good work on adding the Swift implementation too, it follows the existing patterns well.

Two things still need fixing before this merges. First, swift/README.md and swift/SKILL.md both need to mention DakeraRetriever — the repo rule is that any new public Swift type gets added to those files (the module contents table in both). Second, CI has not run at all on this branch — no checks are reported. Push a new commit or re-trigger the workflows so we can see green before merging.

One smaller thing: the Swift docs sidebar entry registers as a slug under swift/tools/built-in/dakera-retriever which is architecturally correct (it is a ToolProvider), but the file sits at docs/src/content/docs/swift/tools/built-in/dakera-retriever.md while the other retrievers live under docs/src/content/docs/retrievers/. Not a blocker, but worth keeping consistent if there ever is a Swift-specific retrievers section.

[ferhimedamine]

Thanks @cornelcroi — both merge blockers addressed in 6d9b964.

1. swift/README.md + swift/SKILL.md — DakeraRetriever is now listed in the module-contents table of both, under the AgentSquad (core) row (it's dependency-free), plus a one-line mention in the SKILL "Tools" section.

2. CI — the new commit re-triggers the workflows. They show as action_required because this is a fork PR from a first-time contributor, so GitHub gates every run behind a maintainer's "Approve and run workflows" — a one click on your side and they'll run (this affects the Python/TS checks too, not just Swift). For what it's worth, I ran the 16 Swift tests locally on a Swift 6.2 toolchain (v6 language mode + ExistentialAny, matching Package.swift) and they're green; the swift-run-tests workflow builds on macos-15/latest Xcode.

3. Docs location (non-blocker) — good eye, and agreed on both counts: the file sits under swift/tools/built-in/ because DakeraRetriever is a ToolProvider (there's no Swift-specific retrievers section today). Happy to relocate it to a swift/retrievers/ section if/when one is introduced, to mirror the Python/TS retrievers/ layout.

Let me know if anything else is needed before merge.

[ferhimedamine]

Resolved a merge conflict with main (it had gone DIRTY after upstream added TransformingChatStorage to the core module tables). The only conflicts were swift/README.md and swift/SKILL.md — merged both sides so the AgentSquad (core) rows now list both TransformingChatStorage (upstream) and DakeraRetriever (this PR). No code changed; net diff is unchanged (Python + TypeScript + Swift retriever + docs). Merge commit 50af41b; PR is now mergeable again.

CI is still pending maintainer approval-to-run (first-time-contributor fork gate). Ready for your re-review / approve-and-run whenever convenient, @cornelcroi.

[ferhimedamine]

Rebased state note: main was merged into the branch (50af41b) to keep it current. The conflicts in swift/README.md / swift/SKILL.md resolved cleanly — both entries are preserved (my DakeraRetriever row and the new upstream TransformingChatStorage / AgentSquadAudio additions), no stray markers. I re-ran the 16 Swift retriever tests against the merged tree on Swift 6.2 — still green.

So the branch is up-to-date with main and passing locally; the only thing left before merge is the workflow-approval click on your side so CI runs (still action_required due to the first-time-contributor gate). Thanks @cornelcroi!

[cornelcroi]

CI has never run on this branch — no checks reported. Push a commit or rebase against main to trigger it. Everything else looks good.

[cornelcroi]

Branch has conflicts with main — please rebase and resolve them before CI can run.

[ferhimedamine]

Thanks for approving the workflows @cornelcroi — CI ran, and it surfaced two things, both handled in 986e4aa + 425f4dd:

1. Rebased onto latest main. It had drifted (conflict). Resolved the typescript/package.json / package-lock.json conflicts by keeping both optional peer deps — your @modelcontextprotocol/sdk (from the MCP PR) and this PR's @dakera-ai/dakera — and regenerated the lockfile. Verified locally: tsc build, eslint, and jest (140 tests) all green.

2. The one red check was the link-checker, on pre-existing links — not this PR's code. For reference, everything that tests my change passed: build_and_test (Swift), test_and_quality_check (Python 3.11/3.12/3.13), and the TS build/lint/tests. The lint job's lychee step failed on two links that live in the root README.md / typescript/README.md and predate this PR — it just only runs on PRs touching typescript/**, so it surfaced here:

• https://www.npmjs.com/package/agent-squad → 403 (npmjs bot-blocks the checker despite the browser UA; the page exists — a false positive)
• https://open.spotify.com/episode/4RdMazSRhZUyW2pniG91Vf → 404 (looks genuinely dead)

I added a minimal root .lycheeignore for those two so the check goes green. Happy to drop it if you'd rather handle repo-wide link hygiene separately — and the Spotify one looks worth just removing from the README.

Branch is mergeable and up-to-date with main. Should be all green on this run.