Skip to content

Fix README API examples #139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SonAIengine merged 1 commit into from
Jul 3, 2026
Merged

Fix README API examples #139

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 24 additions & 16 deletions README.ko.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ synaptic-quickstart --db quickstart.db

---

## 두 번의 호출로 그래프 구축
## 그래프 구축과 검색

```python
import asyncio
Expand All @@ -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()
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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())
```
Expand Down Expand Up @@ -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개)
## 에이전트 도구

### 텍스트 검색 도구
| 도구 | 용도 |
Expand All @@ -242,7 +245,7 @@ Synaptic은 primitive를 제공하고, 합성 여부는 사용자가 선택합
| `join_related` | FK 기반 관련 레코드 조회 — RELATED 엣지 순회 (O(degree)) |

### 인제스트 / CDC 도구 (v0.14.0+)
대화 중에 Claude가 새 자료를 배울 수 있도록 하는 6개 도구.
대화 중에 Claude가 새 자료를 배울 수 있도록 하는 도구.

| 도구 | 용도 |
|------|------|
Expand Down Expand Up @@ -302,6 +305,10 @@ await graph.reinforce([node_id], success=True) # 이 결과가 도움 됨 →

## 벤치마크

아래 숫자는 버전 태그가 붙은 역사적 스냅샷입니다. 정확한 재현은 링크된
스크립트/보고서를 기준으로 하고, 지속적으로 정리되는 결과 로그는
[`docs/comparison/synaptic_results.md`](docs/comparison/synaptic_results.md)를 보세요.

### 재현 가능한 임베더-프리 베이스라인 (노트북 2초)

```bash
Expand Down Expand Up @@ -395,7 +402,7 @@ StorageBackend (Protocol)
↓
검색 파이프라인 (BM25 + 벡터 + PRF + PPR + reranker + MMR)
↓
에이전트 도구 (42개) → MCP 서버 → LLM 에이전트
에이전트 도구 → MCP 서버 → LLM 에이전트
```

---
Expand Down Expand Up @@ -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
```

Expand Down
47 changes: 27 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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()
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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())
```
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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
```

---
Expand Down Expand Up @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion docs/ADOPTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
```
Expand Down
Loading