synapsekit 0.5.0__py3-none-any.whl

synapsekit/__init__.py

@@ -0,0 +1,158 @@
+"""
+SynapseKit — lightweight, async-first RAG framework.
+
+3-line happy path:
+
+    from synapsekit import RAG
+
+    rag = RAG(model="gpt-4o-mini", api_key="sk-...")
+    rag.add("Your document text here")
+
+    async for token in rag.stream("What is the main topic?"):
+        print(token, end="", flush=True)
+"""
+
+from __future__ import annotations
+
+from .agents import (
+    AgentConfig,
+    AgentExecutor,
+    AgentMemory,
+    AgentStep,
+    BaseTool,
+    CalculatorTool,
+    FileReadTool,
+    FunctionCallingAgent,
+    PythonREPLTool,
+    ReActAgent,
+    SQLQueryTool,
+    ToolRegistry,
+    ToolResult,
+    WebSearchTool,
+)
+from .embeddings.backend import SynapsekitEmbeddings
+from .graph import (
+    END,
+    BaseCheckpointer,
+    CompiledGraph,
+    ConditionalEdge,
+    ConditionFn,
+    Edge,
+    GraphConfigError,
+    GraphRuntimeError,
+    GraphState,
+    InMemoryCheckpointer,
+    Node,
+    NodeFn,
+    SQLiteCheckpointer,
+    StateGraph,
+    agent_node,
+    rag_node,
+)
+from .llm.base import BaseLLM, LLMConfig
+from .loaders.base import Document
+from .loaders.csv import CSVLoader
+from .loaders.directory import DirectoryLoader
+from .loaders.html import HTMLLoader
+from .loaders.json_loader import JSONLoader
+from .loaders.pdf import PDFLoader
+from .loaders.text import StringLoader, TextLoader
+from .loaders.web import WebLoader
+from .memory.conversation import ConversationMemory
+from .observability.tracer import TokenTracer
+from .parsers.json_parser import JSONParser
+from .parsers.list_parser import ListParser
+from .parsers.pydantic_parser import PydanticParser
+from .prompts.template import ChatPromptTemplate, FewShotPromptTemplate, PromptTemplate
+from .rag.facade import RAG
+from .rag.pipeline import RAGConfig, RAGPipeline
+from .retrieval.base import VectorStore
+from .retrieval.retriever import Retriever
+from .retrieval.vectorstore import InMemoryVectorStore
+from .text_splitters import (
+    BaseSplitter,
+    CharacterTextSplitter,
+    RecursiveCharacterTextSplitter,
+    SemanticSplitter,
+    TokenAwareSplitter,
+)
+
+__version__ = "0.5.0"
+__all__ = [
+    # Facade
+    "RAG",
+    # Pipeline
+    "RAGPipeline",
+    "RAGConfig",
+    # LLM
+    "BaseLLM",
+    "LLMConfig",
+    # Embeddings
+    "SynapsekitEmbeddings",
+    # Vector stores
+    "VectorStore",
+    "InMemoryVectorStore",
+    # Retrieval
+    "Retriever",
+    # Memory / observability
+    "ConversationMemory",
+    "TokenTracer",
+    # Loaders
+    "Document",
+    "TextLoader",
+    "StringLoader",
+    "PDFLoader",
+    "HTMLLoader",
+    "CSVLoader",
+    "JSONLoader",
+    "DirectoryLoader",
+    "WebLoader",
+    # Parsers
+    "JSONParser",
+    "PydanticParser",
+    "ListParser",
+    # Prompts
+    "PromptTemplate",
+    "ChatPromptTemplate",
+    "FewShotPromptTemplate",
+    # Agents
+    "BaseTool",
+    "ToolResult",
+    "ToolRegistry",
+    "AgentMemory",
+    "AgentStep",
+    "ReActAgent",
+    "FunctionCallingAgent",
+    "AgentExecutor",
+    "AgentConfig",
+    # Built-in tools
+    "CalculatorTool",
+    "FileReadTool",
+    "PythonREPLTool",
+    "SQLQueryTool",
+    "WebSearchTool",
+    # Text splitters
+    "BaseSplitter",
+    "CharacterTextSplitter",
+    "RecursiveCharacterTextSplitter",
+    "TokenAwareSplitter",
+    "SemanticSplitter",
+    # Graph workflows
+    "END",
+    "GraphState",
+    "GraphConfigError",
+    "GraphRuntimeError",
+    "Node",
+    "NodeFn",
+    "agent_node",
+    "rag_node",
+    "Edge",
+    "ConditionalEdge",
+    "ConditionFn",
+    "StateGraph",
+    "CompiledGraph",
+    # Checkpointers
+    "BaseCheckpointer",
+    "InMemoryCheckpointer",
+    "SQLiteCheckpointer",
+]

synapsekit/_compat.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """
+    Run an async coroutine synchronously.
+    Works both inside and outside a running event loop.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop is not None and loop.is_running():
+        # Running inside an existing loop (e.g., Jupyter).
+        # Use a new thread with its own loop to avoid deadlock.
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(asyncio.run, coro)
+            return future.result()
+    else:
+        return asyncio.run(coro)

synapsekit/agents/__init__.py

@@ -0,0 +1,33 @@
+from .base import BaseTool, ToolResult
+from .executor import AgentConfig, AgentExecutor
+from .function_calling import FunctionCallingAgent
+from .memory import AgentMemory, AgentStep
+from .react import ReActAgent
+from .registry import ToolRegistry
+from .tools import (
+    CalculatorTool,
+    FileReadTool,
+    PythonREPLTool,
+    SQLQueryTool,
+    WebSearchTool,
+)
+
+__all__ = [
+    # Core
+    "BaseTool",
+    "ToolResult",
+    "ToolRegistry",
+    "AgentMemory",
+    "AgentStep",
+    # Agents
+    "ReActAgent",
+    "FunctionCallingAgent",
+    "AgentExecutor",
+    "AgentConfig",
+    # Built-in tools
+    "CalculatorTool",
+    "FileReadTool",
+    "PythonREPLTool",
+    "SQLQueryTool",
+    "WebSearchTool",
+]

synapsekit/agents/base.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolResult:
+    """Result returned by any tool execution."""
+
+    output: str
+    error: str | None = None
+
+    @property
+    def is_error(self) -> bool:
+        return self.error is not None
+
+    def __str__(self) -> str:
+        return self.error if self.error is not None else self.output
+
+
+class BaseTool(ABC):
+    """Abstract base class for all agent tools."""
+
+    name: str
+    description: str
+
+    # JSON Schema for the tool's input parameters.
+    # Subclasses must define this as a class attribute.
+    parameters: dict = field(default_factory=dict)
+
+    @abstractmethod
+    async def run(self, **kwargs: Any) -> ToolResult:
+        """Execute the tool. kwargs come from the parsed Action Input."""
+        ...
+
+    def schema(self) -> dict:
+        """OpenAI-compatible function-calling schema."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": getattr(self, "parameters", {"type": "object", "properties": {}}),
+            },
+        }
+
+    def anthropic_schema(self) -> dict:
+        """Anthropic-compatible tool schema."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": getattr(self, "parameters", {"type": "object", "properties": {}}),
+        }
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(name={self.name!r})"

synapsekit/agents/executor.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from typing import Literal
+
+from .._compat import run_sync
+from ..llm.base import BaseLLM
+from .base import BaseTool
+from .function_calling import FunctionCallingAgent
+from .memory import AgentMemory
+from .react import ReActAgent
+
+
+@dataclass
+class AgentConfig:
+    llm: BaseLLM
+    tools: list[BaseTool]
+    agent_type: Literal["react", "function_calling"] = "react"
+    max_iterations: int = 10
+    system_prompt: str = "You are a helpful AI assistant."
+    verbose: bool = False
+
+
+class AgentExecutor:
+    """
+    High-level agent runner. Picks ReActAgent or FunctionCallingAgent based on config.
+
+    Usage::
+
+        executor = AgentExecutor(AgentConfig(
+            llm=OpenAILLM(config),
+            tools=[CalculatorTool(), WebSearchTool()],
+            agent_type="function_calling",
+        ))
+
+        answer = await executor.run("What is 2 ** 10?")
+        answer = executor.run_sync("What is 2 ** 10?")
+    """
+
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config
+        self._agent = self._build_agent()
+
+    def _build_agent(self) -> ReActAgent | FunctionCallingAgent:
+        memory = AgentMemory(max_steps=self.config.max_iterations)
+        if self.config.agent_type == "react":
+            return ReActAgent(
+                llm=self.config.llm,
+                tools=self.config.tools,
+                max_iterations=self.config.max_iterations,
+                memory=memory,
+            )
+        elif self.config.agent_type == "function_calling":
+            return FunctionCallingAgent(
+                llm=self.config.llm,
+                tools=self.config.tools,
+                max_iterations=self.config.max_iterations,
+                memory=memory,
+                system_prompt=self.config.system_prompt,
+            )
+        else:
+            raise ValueError(
+                f"Unknown agent_type: {self.config.agent_type!r}. "
+                "Use 'react' or 'function_calling'."
+            )
+
+    async def run(self, query: str) -> str:
+        """Async: run agent and return final answer."""
+        return await self._agent.run(query)
+
+    async def stream(self, query: str) -> AsyncGenerator[str]:
+        """Async: stream final answer tokens."""
+        async for token in self._agent.stream(query):
+            yield token
+
+    def run_sync(self, query: str) -> str:
+        """Sync: run agent (for scripts / notebooks)."""
+        return run_sync(self.run(query))
+
+    @property
+    def memory(self) -> AgentMemory:
+        return self._agent.memory

synapsekit/agents/function_calling.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from ..llm.base import BaseLLM
+from .base import BaseTool
+from .memory import AgentMemory, AgentStep
+from .registry import ToolRegistry
+
+
+class FunctionCallingAgent:
+    """
+    Agent that uses native LLM function-calling (OpenAI tool_calls / Anthropic tool_use).
+
+    Falls back gracefully: if the LLM doesn't support call_with_tools(),
+    raises RuntimeError with a suggestion to use ReActAgent instead.
+    """
+
+    def __init__(
+        self,
+        llm: BaseLLM,
+        tools: list[BaseTool],
+        max_iterations: int = 10,
+        memory: AgentMemory | None = None,
+        system_prompt: str = "You are a helpful AI assistant.",
+    ) -> None:
+        self._llm = llm
+        self._registry = ToolRegistry(tools)
+        self._max_iterations = max_iterations
+        self._memory = memory or AgentMemory(max_steps=max_iterations)
+        self._system_prompt = system_prompt
+
+    def _check_support(self) -> None:
+        # Check if the provider has overridden call_with_tools (not just the base NotImplementedError)
+        method = getattr(type(self._llm), "call_with_tools", None)
+        if method is getattr(BaseLLM, "call_with_tools", None):
+            raise RuntimeError(
+                f"{type(self._llm).__name__} does not support native function calling. "
+                "Use ReActAgent instead, or switch to OpenAILLM / AnthropicLLM / GeminiLLM / MistralLLM."
+            )
+
+    async def run(self, query: str) -> str:
+        """Run the function-calling loop and return the final answer."""
+        self._check_support()
+        self._memory.clear()
+
+        messages: list[dict] = [
+            {"role": "system", "content": self._system_prompt},
+            {"role": "user", "content": query},
+        ]
+
+        tool_schemas = self._registry.schemas()
+
+        for _ in range(self._max_iterations):
+            result: dict[str, Any] = await self._llm.call_with_tools(messages, tool_schemas)
+
+            tool_calls = result.get("tool_calls")
+            content = result.get("content")
+
+            # No tool calls → final answer
+            if not tool_calls:
+                return content or ""
+
+            # Append assistant message with tool_calls
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": tc["id"],
+                            "type": "function",
+                            "function": {
+                                "name": tc["name"],
+                                "arguments": json.dumps(tc["arguments"]),
+                            },
+                        }
+                        for tc in tool_calls
+                    ],
+                }
+            )
+
+            # Execute each tool and append observations
+            for tc in tool_calls:
+                try:
+                    tool = self._registry.get(tc["name"])
+                    tool_result = await tool.run(**tc["arguments"])
+                    observation = str(tool_result)
+                except KeyError as e:
+                    observation = f"Error: {e}"
+                except Exception as e:
+                    observation = f"Tool error: {e}"
+
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc["id"],
+                        "content": observation,
+                    }
+                )
+
+                self._memory.add_step(
+                    AgentStep(
+                        thought="",
+                        action=tc["name"],
+                        action_input=json.dumps(tc["arguments"]),
+                        observation=observation,
+                    )
+                )
+
+        return "I was unable to complete the task within the allowed number of steps."
+
+    async def stream(self, query: str) -> AsyncGenerator[str]:
+        """Stream the final answer (intermediate tool calls run silently)."""
+        answer = await self.run(query)
+        for word in answer.split(" "):
+            yield word + " "
+
+    @property
+    def memory(self) -> AgentMemory:
+        return self._memory

synapsekit/agents/memory.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentStep:
+    """One complete Thought → Action → Observation cycle."""
+
+    thought: str
+    action: str
+    action_input: str
+    observation: str
+
+
+class AgentMemory:
+    """Scratchpad that records agent steps for the current run."""
+
+    def __init__(self, max_steps: int = 20) -> None:
+        self._max_steps = max_steps
+        self._steps: list[AgentStep] = []
+
+    def add_step(self, step: AgentStep) -> None:
+        self._steps.append(step)
+
+    @property
+    def steps(self) -> list[AgentStep]:
+        return list(self._steps)
+
+    def format_scratchpad(self) -> str:
+        """Format all steps as a ReAct scratchpad string."""
+        parts = []
+        for step in self._steps:
+            parts.append(f"Thought: {step.thought}")
+            parts.append(f"Action: {step.action}")
+            parts.append(f"Action Input: {step.action_input}")
+            parts.append(f"Observation: {step.observation}")
+        return "\n".join(parts)
+
+    def is_full(self) -> bool:
+        return len(self._steps) >= self._max_steps
+
+    def clear(self) -> None:
+        self._steps.clear()
+
+    def __len__(self) -> int:
+        return len(self._steps)

synapsekit/agents/react.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import re
+from collections.abc import AsyncGenerator
+
+from ..llm.base import BaseLLM
+from .base import BaseTool
+from .memory import AgentMemory, AgentStep
+from .registry import ToolRegistry
+
+_REACT_SYSTEM = """\
+You are a helpful AI assistant with access to tools.
+
+Available tools:
+{tools}
+
+Use EXACTLY this format for every response until you have a final answer:
+
+Thought: (your reasoning about what to do next)
+Action: (the exact tool name from the list above)
+Action Input: (the input to pass to the tool, as a plain string)
+
+When you have enough information to answer:
+
+Thought: I now know the final answer.
+Final Answer: (your complete answer to the original question)
+
+Rules:
+- Only use tools from the list above.
+- Never invent tool results — always call the tool and wait for the Observation.
+- Never skip the Thought step.
+- Provide Final Answer only when you are confident.
+"""
+
+_ACTION_RE = re.compile(r"Action:\s*(.+)", re.IGNORECASE)
+_ACTION_INPUT_RE = re.compile(r"Action Input:\s*(.+)", re.IGNORECASE | re.DOTALL)
+_THOUGHT_RE = re.compile(
+    r"Thought:\s*(.+?)(?=\n(?:Action|Final Answer)|$)", re.IGNORECASE | re.DOTALL
+)
+_FINAL_ANSWER_RE = re.compile(r"Final Answer:\s*(.+)", re.IGNORECASE | re.DOTALL)
+
+
+def _parse_thought(text: str) -> str:
+    m = _THOUGHT_RE.search(text)
+    return m.group(1).strip() if m else ""
+
+
+def _parse_action(text: str) -> tuple[str, str]:
+    action_m = _ACTION_RE.search(text)
+    input_m = _ACTION_INPUT_RE.search(text)
+    action = action_m.group(1).strip() if action_m else ""
+    action_input = input_m.group(1).strip() if input_m else ""
+    return action, action_input
+
+
+def _parse_final_answer(text: str) -> str | None:
+    m = _FINAL_ANSWER_RE.search(text)
+    return m.group(1).strip() if m else None
+
+
+class ReActAgent:
+    """
+    Reasoning + Acting agent.
+
+    Loops: Thought → Action → Observation → repeat until Final Answer.
+    Works with any BaseLLM — no native function-calling required.
+    """
+
+    def __init__(
+        self,
+        llm: BaseLLM,
+        tools: list[BaseTool],
+        max_iterations: int = 10,
+        memory: AgentMemory | None = None,
+    ) -> None:
+        self._llm = llm
+        self._registry = ToolRegistry(tools)
+        self._max_iterations = max_iterations
+        self._memory = memory or AgentMemory(max_steps=max_iterations)
+
+    def _build_system_prompt(self) -> str:
+        return _REACT_SYSTEM.format(tools=self._registry.describe())
+
+    def _build_messages(self, query: str) -> list[dict]:
+        scratchpad = self._memory.format_scratchpad()
+        user_content = f"Question: {query}"
+        if scratchpad:
+            user_content += f"\n\n{scratchpad}"
+        return [
+            {"role": "system", "content": self._build_system_prompt()},
+            {"role": "user", "content": user_content},
+        ]
+
+    async def run(self, query: str) -> str:
+        """Run the ReAct loop and return the final answer."""
+        self._memory.clear()
+
+        for _ in range(self._max_iterations):
+            messages = self._build_messages(query)
+            response = await self._llm.generate_with_messages(messages)
+
+            # Check for final answer first
+            final = _parse_final_answer(response)
+            if final is not None:
+                return final
+
+            # Parse action
+            action_name, action_input = _parse_action(response)
+            thought = _parse_thought(response)
+
+            if not action_name:
+                # LLM didn't follow format — treat whole response as final answer
+                return response.strip()
+
+            # Execute tool
+            try:
+                tool = self._registry.get(action_name)
+                result = await tool.run(input=action_input)
+                observation = str(result)
+            except KeyError as e:
+                observation = f"Error: {e}"
+            except Exception as e:
+                observation = f"Tool error: {e}"
+
+            self._memory.add_step(
+                AgentStep(
+                    thought=thought,
+                    action=action_name,
+                    action_input=action_input,
+                    observation=observation,
+                )
+            )
+
+        return "I was unable to find the answer within the allowed number of steps."
+
+    async def stream(self, query: str) -> AsyncGenerator[str]:
+        """
+        Stream the final answer. Intermediate tool calls run silently.
+        Yields the final answer string (may be multi-token on last LLM call).
+        """
+        answer = await self.run(query)
+        for word in answer.split(" "):
+            yield word + " "
+
+    @property
+    def memory(self) -> AgentMemory:
+        return self._memory