afx-team / afx-team/hebb-mind

docs(integrations): copy-paste "connect in 10 lines" recipes for LlamaIndex / CrewAI / AutoGen / LangGraph

Aperta
#29 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area: integration documentation effort: simple good first issue
Lingua principale
Python
Stelle
52
Fork
18
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

## Context

Capability goal: **易接入 (easy to integrate)** — lower the barrier to "paste a snippet and you're connected" *before* native per-framework adapters land.

Today only two agent surfaces have first-class integration docs: Claude Code (hooks) and Codex (MCP). For the broader Python agent ecosystem — LlamaIndex, CrewAI, AutoGen, LangGraph — there is no "how do I connect Hebb Mind?" page, even though the generic levers already work today: the **MCP stdio server** (`hebb-mcp`) and the **REST API** (`/api/v1`, search + ingest + memories). The one example we ship for a non-native framework, `examples/05_langchain_adapter.py`, is an unimplemented skeleton.

This is a doc-only task on **existing surfaces** — no new library code required.

## Current state

- `src/hebb/mcp/server.py` exposes four MCP tools over the `hebb-mcp` stdio entrypoint:
- `write_memory(content, tags, importance)` — `src/hebb/mcp/server.py:54`
- `search_memory(query, top_k)` — `src/hebb/mcp/server.py:90`
- `consolidate()` — `src/hebb/mcp/server.py:141`
- `ingest_conversation(content, format_hint, importance)` — `src/hebb/mcp/server.py:160`
- `hebb-mcp` console entrypoint → `hebb.mcp.server:main` — `pyproject.toml:65`
- The MCP server is a thin wrapper over the REST API; default service URL is `http://localhost:8321` (`src/hebb/mcp/server.py:1-10`).
- REST endpoints (all mounted under `/api/v1`, `src/hebb/server/app.py:153-160`):
- `POST /api/v1/search` — `src/hebb/server/routers/search.py:16`; request body is `MemoryQuery` with `query: str` and `top_k: int` (default 10, 1–100) — `src/hebb/models/memory.py:74-99`. Response is `SearchResponse` (`results: list[MemorySearchResult]`, `related: list[Memory]`) — `src/hebb/models/memory.py:113-117`.
- `POST /api/v1/memories` — write a memory — `src/hebb/server/routers/memories.py:74`
- `POST /api/v1/ingest` — ingest a conversation — `src/hebb/server/routers/memories.py:145`
- `examples/05_langchain_adapter.py` is a non-functional skeleton: `HebbChatMessageHistory` and `HebbRetriever` both `raise NotImplementedError` (`examples/05_langchain_adapter.py:46`, `:50`, `:54`, `:69`). `examples/README.md` lists it as **WIP** and names LlamaIndex / CrewAI / AutoGen as wanted-but-missing.
- Existing per-framework docs in the site sidebar (`repo_pages/.vitepress/config.mts:314-316`) cover only **Claude Code**, **Codex**, and a generic **MCP Integration** page (`repo_pages/guide/mcp-integration.md` + zh mirror `repo_pages/zh/guide/mcp-integration.md`). No LlamaIndex / CrewAI / AutoGen / LangGraph page exists.

## Proposed approach

Add one docs guide page (EN + zh mirror, per the CLAUDE.md per-language parity rule) titled "Use Hebb Mind from ``", with a ~10-line copy-paste snippet for each of:

- **LlamaIndex**
- **CrewAI**
- **AutoGen**
- **LangGraph**

Each snippet wraps an **existing** surface — either the MCP tools (`search_memory` / `write_memory` via the framework's MCP-tool adapter against the `hebb-mcp` stdio server) or the REST API (`POST /api/v1/search` and `POST /api/v1/memories`) using `httpx`/`requests`. Prefer whichever is the lower-friction path per framework; the snippet must be self-contained and runnable against a locally running `hebb service` (`http://localhost:8321`).

Then link the new page from:
- the README integrations area (next to the Claude Code / Codex lines around `README.md:107-108`), and
- `examples/README.md` (the "Pick your starting point" / contributing section that currently only points at the WIP LangChain skeleton).
- the docs sidebar (`repo_pages/.vitepress/config.mts`) alongside the existing Claude Code / Codex / MCP entries (EN + zh).

## Acceptance criteria

- [ ] New EN docs page under `repo_pages/guide/` with a copy-paste snippet (~10 lines each) for LlamaIndex, CrewAI, AutoGen, and LangGraph.
- [ ] zh mirror page under `repo_pages/zh/guide/` with the same four snippets (no mixed-language content per CLAUDE.md).
- [ ] Each snippet is runnable against a local `hebb service` on `http://localhost:8321` and uses only existing surfaces (MCP tool names `search_memory`/`write_memory`, or REST `POST /api/v1/search` with `{"query": ..., "top_k": ...}` and `POST /api/v1/memories`).
- [ ] New page added to the VitePress sidebar (`repo_pages/.vitepress/config.mts`) for both EN and zh.
- [ ] Linked from `README.md` (integrations section) and `examples/README.md`.
- [ ] No new runtime library code introduced (documentation-only).

## Scope / out of scope

- **In scope:** documentation + sidebar links for the four frameworks against the already-shipped MCP and REST surfaces.
- **Out of scope:** native Python adapter classes (e.g. completing `examples/05_langchain_adapter.py` or shipping a `langchain`/`llamaindex` integration module). Those are follow-ups; this issue is the low-cost "paste a snippet" bridge that ships first.

## References

- `reports/audit/core-system-audit-2026-06-07.md`
- `reports/audit/newuser-experience-audit-2026-06-08.md`
- `reports/design/capability-gap-roadmap-2026-06-11.md`

Filed from the capability-gap roadmap (reports/design/capability-gap-roadmap-2026-06-11.md).

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.