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!