From 5bd5954b4063517dde2e47ba15226ff2afe34990 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=86=90=EC=84=B1=EC=A4=80?= Date: Fri, 3 Jul 2026 10:27:09 +0900 Subject: [PATCH] Fix README API examples --- README.ko.md | 40 ++++++++++++++++++++++++---------------- README.md | 47 +++++++++++++++++++++++++++-------------------- docs/ADOPTION.md | 2 +- 3 files changed, 52 insertions(+), 37 deletions(-) diff --git a/README.ko.md b/README.ko.md index 0e7d508..f6e5aff 100644 --- a/README.ko.md +++ b/README.ko.md @@ -24,7 +24,7 @@ synaptic-quickstart --db quickstart.db --- -## 두 번의 호출로 그래프 구축 +## 그래프 구축과 검색 ```python import asyncio @@ -34,7 +34,7 @@ async def main(): # 아무 데이터 → 지식 그래프 (CSV, JSONL, 디렉터리) graph = await SynapticGraph.from_data("./내_데이터/", preset="rag") try: - result = await graph.search("내 질문", engine="evidence") + result = await graph.search("내 질문") print(result.nodes[0].node.title if result.nodes else "결과 없음") finally: await graph.close() @@ -129,7 +129,7 @@ async def main(): # CSV 파일 graph = await SynapticGraph.from_data("products.csv") try: - result = await graph.search("내 질문", engine="evidence") + result = await graph.search("내 질문") for activated in result.nodes[:5]: print(activated.node.title, activated.activation) finally: @@ -167,11 +167,13 @@ from synaptic.integrations.langchain import SynapticRetriever async def main(): graph = await SynapticGraph.from_data("./docs/") - retriever = SynapticRetriever(graph=graph, k=5, engine="evidence") - - docs = await retriever.ainvoke("내 질문") - for doc in docs: - print(doc.page_content[:80], " ", doc.metadata["score"]) + try: + retriever = SynapticRetriever(graph=graph, k=5) + docs = await retriever.ainvoke("내 질문") + for doc in docs: + print(doc.page_content[:80], " ", doc.metadata["score"]) + finally: + await graph.close() asyncio.run(main()) ``` @@ -214,13 +216,14 @@ asyncio.run(main()) LLM이 합성한 요약이 필요하면 그래프 위에 별도 에이전트 레이어로 쌓으세요 — Synaptic은 primitive를 제공하고, 합성 여부는 사용자가 선택합니다. -> **v0.16.0**: `graph.search()` 기본 엔진이 **`"evidence"`** 로 전환되었습니다. -> `engine="legacy"`는 `DeprecationWarning`을 띄우며 v0.17.0에서 제거 예정. -> Korean 공개 벤치마크에서 **MRR 0.621 → 0.947** (Allganize RAG-ko) 달성. +> **v0.28+**: `graph.search()`는 하나의 경로만 사용합니다. BM25 + HNSW + +> PPR + cross-encoder + MMR 기반 EvidenceSearch 파이프라인입니다. +> 예전 `engine=` 스위치는 제거되었으므로 예제는 +> `graph.search("질문")`처럼 바로 호출하면 됩니다. --- -## 에이전트 도구 (42개) +## 에이전트 도구 ### 텍스트 검색 도구 | 도구 | 용도 | @@ -242,7 +245,7 @@ Synaptic은 primitive를 제공하고, 합성 여부는 사용자가 선택합 | `join_related` | FK 기반 관련 레코드 조회 — RELATED 엣지 순회 (O(degree)) | ### 인제스트 / CDC 도구 (v0.14.0+) -대화 중에 Claude가 새 자료를 배울 수 있도록 하는 6개 도구. +대화 중에 Claude가 새 자료를 배울 수 있도록 하는 도구. | 도구 | 용도 | |------|------| @@ -302,6 +305,10 @@ await graph.reinforce([node_id], success=True) # 이 결과가 도움 됨 → ## 벤치마크 +아래 숫자는 버전 태그가 붙은 역사적 스냅샷입니다. 정확한 재현은 링크된 +스크립트/보고서를 기준으로 하고, 지속적으로 정리되는 결과 로그는 +[`docs/comparison/synaptic_results.md`](docs/comparison/synaptic_results.md)를 보세요. + ### 재현 가능한 임베더-프리 베이스라인 (노트북 2초) ```bash @@ -395,7 +402,7 @@ StorageBackend (Protocol) ↓ 검색 파이프라인 (BM25 + 벡터 + PRF + PPR + reranker + MMR) ↓ -에이전트 도구 (42개) → MCP 서버 → LLM 에이전트 +에이전트 도구 → MCP 서버 → LLM 에이전트 ``` --- @@ -435,15 +442,16 @@ StorageBackend (Protocol) | [docs/GUIDE.md](docs/GUIDE.md) | 친절한 전체 안내서 (처음 접하는 사람용) | | [docs/TUTORIAL.md](docs/TUTORIAL.md) | 30분 단계별 실습 | | [docs/CONCEPTS.md](docs/CONCEPTS.md) | 파이프라인 심화 설명 | +| [docs/ADOPTION.md](docs/ADOPTION.md) | 설치 옵션, preset, 첫 적용 경로 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 신경망 영감 초기 설계 | | [docs/COMPARISON.md](docs/COMPARISON.md) | GraphRAG / LightRAG 등과 비교 | -| [docs/ROADMAP.md](docs/ROADMAP.md) | 향후 로드맵 | +| [docs/ROADMAP.md](docs/ROADMAP.md) | 역사적 로드맵 | ## 개발 ```bash uv sync --extra dev --extra sqlite --extra mcp -uv run pytest tests/ -q # 818+ 테스트 +uv run pytest tests/ -q uv run ruff check --fix ``` diff --git a/README.md b/README.md index b0456a7..fe3b145 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ zero-dependency smoke test. Full source for the expanded example: --- -## Two calls to build a graph +## Build and search ```python import asyncio @@ -36,7 +36,7 @@ async def main(): # Any data → knowledge graph (CSV, JSONL, directory) graph = await SynapticGraph.from_data("./my_data/", preset="rag") try: - result = await graph.search("my question", engine="evidence") + result = await graph.search("my question") print(result.nodes[0].node.title if result.nodes else "no result") finally: await graph.close() @@ -132,7 +132,7 @@ async def main(): # CSV file graph = await SynapticGraph.from_data("products.csv") try: - result = await graph.search("my question", engine="evidence") + result = await graph.search("my question") for activated in result.nodes[:5]: print(activated.node.title, activated.activation) finally: @@ -173,11 +173,13 @@ from synaptic.integrations.langchain import SynapticRetriever async def main(): graph = await SynapticGraph.from_data("./docs/") - retriever = SynapticRetriever(graph=graph, k=5, engine="evidence") - - docs = await retriever.ainvoke("my question") - for doc in docs: - print(doc.page_content[:80], " ", doc.metadata["score"]) + try: + retriever = SynapticRetriever(graph=graph, k=5) + docs = await retriever.ainvoke("my question") + for doc in docs: + print(doc.page_content[:80], " ", doc.metadata["score"]) + finally: + await graph.close() asyncio.run(main()) ``` @@ -258,15 +260,14 @@ Synaptic does *not* do is LLM-synthesize fuzzy semantic relations or community summaries — if you need those, layer them with your own agent; Synaptic gives you the primitives. -> **v0.16.0+**: `graph.search()` defaults to the hybrid +> **v0.28+**: `graph.search()` has one retrieval path: the hybrid > EvidenceSearch pipeline (BM25 + HNSW + PPR + cross-encoder + MMR). -> `engine="legacy"` still works but raises `DeprecationWarning`; -> removal is pushed to v0.18.0 to bundle with HippoRAG2-style -> architecture work. +> The old `engine=` switch was removed, so examples should call +> `graph.search("question")` directly. --- -## Agent Tools (42 total) +## Agent Tools ### Text search tools | Tool | Purpose | @@ -354,6 +355,11 @@ await graph.reinforce([node_id], success=True) # this result helped → lift it ## Benchmarks +The numbers below are version-tagged historical snapshots. Use the linked +scripts/reports for exact reproduction, and prefer +[`docs/comparison/synaptic_results.md`](docs/comparison/synaptic_results.md) +for a continuously curated result log. + ### Reproducible FTS-only baseline (< 2 seconds on a laptop) ```bash @@ -533,11 +539,11 @@ MuSiQue-Ans-dev 500q full pipeline R@5 **0.453** vs HippoRAG2's published **0.747** (−0.294). Three rounds of targeted fixes (LLM query decomposition, inline phrase hub, DF-filtered entity linker) all regressed the score — the gap is structural. Closing it -requires OpenIE triple extraction + query→triple dense linking, -which is a v0.18.0+ research track rather than a default pipeline -change. Synaptic's strength is Korean / structured-data RAG; +requires OpenIE triple extraction + query→triple dense linking. +That work now lives as an opt-in, bounded, revertible layer rather +than a default deterministic path. Synaptic's strength is Korean / structured-data RAG; English Wikipedia multi-hop is honestly documented as a trade-off. -See [`docs/PLAN-v0.18-architecture.md`](docs/PLAN-v0.18-architecture.md#q2--indexing--llm-free-유지-vs-selective-llm-도입). +See the OpenIE and memory operating layer plans under `docs/PLAN-v0.30+`. ### Multi-turn agent (GPT-4o-mini, 5 turns max) @@ -567,7 +573,7 @@ StorageBackend (Protocol) ↓ Retrieval pipeline (BM25 + vector + PRF + PPR + reranker + MMR) ↓ -Agent tools (42) → MCP server → LLM agent +Agent tools → MCP server → LLM agent ``` --- @@ -612,13 +618,14 @@ Agent tools (42) → MCP server → LLM agent | [docs/comparison/published_numbers.md](docs/comparison/published_numbers.md) | Competitor self-reported numbers (with sources) | | [docs/paper/draft.md](docs/paper/draft.md) | arXiv preprint draft — Streaming Retrieval with Top-K Invariance | | [docs/paper/theorem.md](docs/paper/theorem.md) | Formal theorem + proof sketch | -| [docs/ROADMAP.md](docs/ROADMAP.md) | Future plans | +| [docs/ADOPTION.md](docs/ADOPTION.md) | Install, presets, and first integration path | +| [docs/ROADMAP.md](docs/ROADMAP.md) | Historical roadmap | ## Dev ```bash uv sync --extra dev --extra sqlite --extra mcp -uv run pytest tests/ -q # 809+ tests +uv run pytest tests/ -q uv run ruff check --fix ``` diff --git a/docs/ADOPTION.md b/docs/ADOPTION.md index 4a99e98..e3962a7 100644 --- a/docs/ADOPTION.md +++ b/docs/ADOPTION.md @@ -37,7 +37,7 @@ from synaptic import SynapticGraph graph = await SynapticGraph.from_data("./docs/", preset="rag") try: - result = await graph.search("refund policy exception", engine="evidence") + result = await graph.search("refund policy exception") finally: await graph.close() ```