refactor: 팩토리 함수, 타입 스텁, 코드 중복 제거 — 사용자 편의성 개선

SonAIengine · claude · SonAIengine · commit 968fecb33e84 · 2026-03-22T19:46:23.000+09:00
- SynapticGraph.memory() / .sqlite() / .full() 팩토리 클래스메서드 추가
  → 신규 사용자가 preset 기반으로 즉시 시작 가능
- __init__.pyi 타입 스텁 생성 → lazy import 클래스 IDE 자동완성 지원
- _rank_to_score() 헬퍼 추출 (search.py 내 rank→score 변환 중복 제거)
- _EmbedFromBatchMixin 도입 → OpenAI/Ollama EmbeddingProvider embed() 중복 제거
- __init__.py Quick Start docstring 추가 (3단계 예제 + 백엔드 목록)

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/synaptic/__init__.py b/src/synaptic/__init__.py
@@ -1,4 +1,42 @@
-"""Synaptic Memory — Brain-inspired knowledge graph for LLM agents."""
+"""Synaptic Memory — Brain-inspired knowledge graph for LLM agents.
+
+Quick Start
+-----------
+
+1. In-memory (zero dependencies)::
+
+    from synaptic import SynapticGraph
+
+    graph = SynapticGraph.memory()
+    await graph.add("API 장애 대응", "서버 재시작 후 복구", kind=NodeKind.LESSON)
+    result = await graph.search("장애 대응")
+
+2. SQLite (경량 프로덕션)::
+
+    graph = SynapticGraph.sqlite("knowledge.db")
+    await graph.backend.connect()
+    await graph.add("배포 정책", "PR 머지 후 자동 배포", kind=NodeKind.RULE)
+
+3. Full-featured (LLM 분류 + 임베딩 + 관계 탐지)::
+
+    from synaptic.backends.sqlite import SQLiteBackend
+    from synaptic.extensions.llm_provider import OllamaLLMProvider
+
+    graph = SynapticGraph.full(
+        SQLiteBackend("knowledge.db"),
+        llm=OllamaLLMProvider(model="gemma3:4b"),
+        embed_api_base="http://localhost:8080/v1",
+    )
+    await graph.backend.connect()
+
+Backends
+--------
+- ``MemoryBackend`` — 테스트/개발 (zero-dep)
+- ``SQLiteBackend`` — 경량 프로덕션 (``pip install synaptic-memory[sqlite]``)
+- ``PostgreSQLBackend`` — 프로덕션 (``pip install synaptic-memory[postgresql]``)
+- ``Neo4jBackend`` — 그래프 탐색 (``pip install synaptic-memory[neo4j]``)
+- ``CompositeBackend`` — Neo4j + Qdrant + MinIO 조합 (``pip install synaptic-memory[scale]``)
+"""
 
 from __future__ import annotations
 
diff --git a/src/synaptic/__init__.pyi b/src/synaptic/__init__.pyi
@@ -0,0 +1,53 @@
+"""Type stubs for synaptic — IDE autocomplete for lazy-imported classes."""
+
+from synaptic.activity import ActivityTracker as ActivityTracker
+from synaptic.agent_search import AgentSearch as AgentSearch
+from synaptic.agent_search import SearchIntent as SearchIntent
+from synaptic.agent_search import suggest_intent as suggest_intent
+from synaptic.evidence import EvidenceAssembler as EvidenceAssembler
+from synaptic.extensions.classifier_hybrid import HybridClassifier as HybridClassifier
+from synaptic.extensions.classifier_llm import ClassificationResult as ClassificationResult
+from synaptic.extensions.classifier_llm import LLMClassifier as LLMClassifier
+from synaptic.extensions.classifier_rules import RuleBasedClassifier as RuleBasedClassifier
+from synaptic.extensions.embedder import EmbeddingProvider as EmbeddingProvider
+from synaptic.extensions.embedder import MockEmbeddingProvider as MockEmbeddingProvider
+from synaptic.extensions.embedder import OllamaEmbeddingProvider as OllamaEmbeddingProvider
+from synaptic.extensions.embedder import OpenAIEmbeddingProvider as OpenAIEmbeddingProvider
+from synaptic.extensions.llm_provider import OllamaLLMProvider as OllamaLLMProvider
+from synaptic.extensions.llm_provider import OpenAILLMProvider as OpenAILLMProvider
+from synaptic.extensions.phrase_extractor import PhraseExtractor as PhraseExtractor
+from synaptic.extensions.relation_detector import (
+    EmbeddingRelationDetector as EmbeddingRelationDetector,
+)
+from synaptic.extensions.relation_detector import (
+    RuleBasedRelationDetector as RuleBasedRelationDetector,
+)
+from synaptic.extensions.relation_detector_llm import LLMRelationDetector as LLMRelationDetector
+from synaptic.graph import SynapticGraph as SynapticGraph
+from synaptic.models import ActivatedNode as ActivatedNode
+from synaptic.models import ConsolidationLevel as ConsolidationLevel
+from synaptic.models import DigestResult as DigestResult
+from synaptic.models import Edge as Edge
+from synaptic.models import EdgeKind as EdgeKind
+from synaptic.models import EvidenceChain as EvidenceChain
+from synaptic.models import EvidenceStep as EvidenceStep
+from synaptic.models import Node as Node
+from synaptic.models import NodeKind as NodeKind
+from synaptic.models import SearchResult as SearchResult
+from synaptic.ontology import OntologyRegistry as OntologyRegistry
+from synaptic.ontology import PropertyDef as PropertyDef
+from synaptic.ontology import RelationConstraint as RelationConstraint
+from synaptic.ontology import TypeDef as TypeDef
+from synaptic.ontology import build_agent_ontology as build_agent_ontology
+from synaptic.ppr import personalized_pagerank as personalized_pagerank
+from synaptic.protocols import Digester as Digester
+from synaptic.protocols import GraphTraversal as GraphTraversal
+from synaptic.protocols import KindClassifier as KindClassifier
+from synaptic.protocols import QueryRewriter as QueryRewriter
+from synaptic.protocols import RelationDetector as RelationDetector
+from synaptic.protocols import StorageBackend as StorageBackend
+from synaptic.protocols import TagExtractor as TagExtractor
+from synaptic.resonance import ResonanceWeights as ResonanceWeights
+
+__version__: str
+__all__: list[str]
diff --git a/src/synaptic/extensions/embedder.py b/src/synaptic/extensions/embedder.py
@@ -23,6 +23,14 @@ async def embed(self, text: str) -> list[float]: ...
     async def embed_batch(self, texts: list[str]) -> list[list[float]]: ...
 
 
+class _EmbedFromBatchMixin:
+    """embed()를 embed_batch() 위임으로 기본 구현하는 mixin."""
+
+    async def embed(self, text: str) -> list[float]:
+        results = await self.embed_batch([text])  # type: ignore[attr-defined]
+        return results[0]
+
+
 class MockEmbeddingProvider:
     """Mock embedding provider for testing. Returns deterministic vectors."""
 
@@ -39,7 +47,7 @@ async def embed_batch(self, texts: list[str]) -> list[list[float]]:
         return [await self.embed(t) for t in texts]
 
 
-class OpenAIEmbeddingProvider:
+class OpenAIEmbeddingProvider(_EmbedFromBatchMixin):
     """OpenAI-compatible embedding provider.
 
     Works with any server implementing the /v1/embeddings endpoint:
@@ -67,10 +75,6 @@ def __init__(
         self._model = model
         self._timeout = timeout
 
-    async def embed(self, text: str) -> list[float]:
-        results = await self.embed_batch([text])
-        return results[0]
-
     async def embed_batch(self, texts: list[str]) -> list[list[float]]:
         import aiohttp  # noqa: PLC0415
 
@@ -96,7 +100,7 @@ async def embed_batch(self, texts: list[str]) -> list[list[float]]:
         return embeddings
 
 
-class OllamaEmbeddingProvider:
+class OllamaEmbeddingProvider(_EmbedFromBatchMixin):
     """Ollama native embedding endpoint (/api/embed).
 
     For Ollama servers that don't expose /v1/embeddings.
@@ -121,10 +125,6 @@ def __init__(
         self._model = model
         self._timeout = timeout
 
-    async def embed(self, text: str) -> list[float]:
-        results = await self.embed_batch([text])
-        return results[0]
-
     async def embed_batch(self, texts: list[str]) -> list[list[float]]:
         import aiohttp  # noqa: PLC0415
 
diff --git a/src/synaptic/graph.py b/src/synaptic/graph.py
@@ -5,6 +5,7 @@
 import json
 from difflib import SequenceMatcher
 from time import time
+from typing import TYPE_CHECKING, Literal
 
 from synaptic.agent_search import AgentSearch, SearchIntent, suggest_intent
 from synaptic.cache import NodeCache
@@ -24,7 +25,7 @@
     NodeKind,
     SearchResult,
 )
-from synaptic.ontology import OntologyRegistry
+from synaptic.ontology import OntologyRegistry, build_agent_ontology
 from synaptic.protocols import (
     Digester,
     KindClassifier,
@@ -36,9 +37,24 @@
 from synaptic.search import HybridSearch
 from synaptic.store import Store
 
+if TYPE_CHECKING:
+    from synaptic.extensions.llm_provider import LLMProvider
+
 
 class SynapticGraph:
-    """Facade over the synaptic memory system."""
+    """Facade over the synaptic memory system.
+
+    Quick Start::
+
+        # 1. In-memory (zero-dep, 테스트/프로토타이핑)
+        graph = SynapticGraph.memory()
+
+        # 2. SQLite (경량 프로덕션)
+        graph = SynapticGraph.sqlite("knowledge.db")
+
+        # 3. Full preset with custom backend
+        graph = SynapticGraph(backend, classifier=..., embedder=...)
+    """
 
     __slots__ = (
         "_agent_search",
@@ -85,6 +101,117 @@ def __init__(
         self._phrase_extractor = phrase_extractor
         self._agent_search = AgentSearch(hybrid=self._search)
 
+    # --- Factory methods ---
+
+    @classmethod
+    def memory(cls, *, cache_size: int = 256) -> SynapticGraph:
+        """In-memory backend — zero dependencies, 테스트/프로토타이핑용.
+
+        Example::
+
+            graph = SynapticGraph.memory()
+            await graph.add("Hello", "World")
+        """
+        from synaptic.backends.memory import MemoryBackend  # noqa: PLC0415
+        from synaptic.extensions.classifier_rules import RuleBasedClassifier  # noqa: PLC0415
+
+        return cls(
+            MemoryBackend(),
+            classifier=RuleBasedClassifier(),
+            cache_size=cache_size,
+        )
+
+    @classmethod
+    def sqlite(
+        cls,
+        db_path: str = "synaptic.db",
+        *,
+        cache_size: int = 256,
+    ) -> SynapticGraph:
+        """SQLite backend — 경량 프로덕션, FTS5 검색 지원.
+
+        Example::
+
+            graph = SynapticGraph.sqlite("knowledge.db")
+            await graph.backend.connect()
+            await graph.add("Hello", "World")
+        """
+        from synaptic.backends.sqlite import SQLiteBackend  # noqa: PLC0415
+        from synaptic.extensions.classifier_rules import RuleBasedClassifier  # noqa: PLC0415
+        from synaptic.extensions.relation_detector import RuleBasedRelationDetector  # noqa: PLC0415
+
+        return cls(
+            SQLiteBackend(db_path),
+            classifier=RuleBasedClassifier(),
+            relation_detector=RuleBasedRelationDetector(),
+            ontology=build_agent_ontology(),
+            cache_size=cache_size,
+        )
+
+    @classmethod
+    def full(
+        cls,
+        backend: StorageBackend,
+        *,
+        llm: LLMProvider | None = None,
+        embed_api_base: str = "",
+        embed_model: str = "default",
+        embed_api_key: str = "",
+        cache_size: int = 512,
+    ) -> SynapticGraph:
+        """Full-featured setup — LLM 분류, 임베딩, 관계 탐지, 온톨로지.
+
+        Example::
+
+            from synaptic.backends.sqlite import SQLiteBackend
+            from synaptic.extensions.llm_provider import OllamaLLMProvider
+
+            graph = SynapticGraph.full(
+                SQLiteBackend("knowledge.db"),
+                llm=OllamaLLMProvider(model="gemma3:4b"),
+                embed_api_base="http://localhost:8080/v1",
+            )
+        """
+        from synaptic.extensions.classifier_rules import RuleBasedClassifier  # noqa: PLC0415
+        from synaptic.extensions.relation_detector import RuleBasedRelationDetector  # noqa: PLC0415
+
+        classifier: KindClassifier
+        relation_detector: RelationDetector
+        embedder: EmbeddingProvider | None = None
+
+        if llm is not None:
+            from synaptic.extensions.classifier_hybrid import HybridClassifier  # noqa: PLC0415
+            from synaptic.extensions.classifier_llm import LLMClassifier  # noqa: PLC0415
+            from synaptic.extensions.relation_detector_llm import LLMRelationDetector  # noqa: PLC0415
+
+            classifier = HybridClassifier(
+                llm=LLMClassifier(llm, fallback=RuleBasedClassifier()),
+                rule=RuleBasedClassifier(),
+            )
+            relation_detector = LLMRelationDetector(llm, fallback=RuleBasedRelationDetector())
+        else:
+            classifier = RuleBasedClassifier()
+            relation_detector = RuleBasedRelationDetector()
+
+        if embed_api_base:
+            from synaptic.extensions.embedder import OpenAIEmbeddingProvider  # noqa: PLC0415
+
+            embedder = OpenAIEmbeddingProvider(
+                api_base=embed_api_base,
+                model=embed_model,
+                api_key=embed_api_key,
+            )
+
+        return cls(
+            backend,
+            classifier=classifier,
+            relation_detector=relation_detector,
+            embedder=embedder,
+            ontology=build_agent_ontology(),
+            phrase_extractor=PhraseExtractor(),
+            cache_size=cache_size,
+        )
+
     @property
     def backend(self) -> StorageBackend:
         return self._backend
diff --git a/src/synaptic/search.py b/src/synaptic/search.py
@@ -37,6 +37,11 @@
 _KIND_BOOST = 0.05  # kind 매칭 시 search_score 부스트량 (보수적)
 
 
+def _rank_to_score(rank: int, *, top: float = 0.95, step: float = 0.05, floor: float = 0.3) -> float:
+    """순위 기반 점수 변환: 1위=top, 순위마다 step 감소, floor 이하 방지."""
+    return max(floor, top - rank * step)
+
+
 def _cosine_sim(a: list[float], b: list[float]) -> float:
     """두 벡터의 코사인 유사도."""
     dot = sum(x * y for x, y in zip(a, b))
@@ -83,8 +88,7 @@ async def search(
         fts_nodes = await backend.search_fts(query, limit=limit * 2)
         stages_used.append("fts")
         for rank, node in enumerate(fts_nodes):
-            # FTS 순위 기반 점수: 1위=0.95, 감소율 0.05
-            score = max(0.3, 0.95 - rank * 0.05)
+            score = _rank_to_score(rank)
             fts_scores[node.id] = score
             all_nodes[node.id] = (node, score)
 
@@ -94,7 +98,7 @@ async def search(
             stages_used.append("vector")
             for rank, node in enumerate(vec_nodes):
                 # Vector 순위 기반 점수 + 실제 cosine similarity 반영
-                rank_score = max(0.3, 0.95 - rank * 0.05)
+                rank_score = _rank_to_score(rank)
                 # cosine similarity 직접 계산 (가능한 경우)
                 if node.embedding and embedding:
                     sim = _cosine_sim(embedding, node.embedding)
