synapsekit 0.6.2__tar.gz → 0.6.3__tar.gz

{synapsekit-0.6.2 → synapsekit-0.6.3}/CHANGELOG.md

@@ -7,6 +7,38 @@ SynapseKit uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.6.3] — 2026-03-14
+
+### Added
+
+- **Typed state with reducers** — `TypedState` and `StateField` for safe parallel state merging in graph workflows; per-field reducers control how concurrent node outputs are combined (closes #253)
+- **Parallel subgraph execution** — `fan_out_node()` runs multiple subgraphs concurrently with `asyncio.gather()`, supports per-subgraph input mappings and custom merge functions (closes #248)
+- **SSE streaming** — `sse_stream()` streams graph execution as Server-Sent Events for HTTP responses (closes #238)
+- **Event callbacks** — `EventHooks` and `GraphEvent` for registering callbacks on node_start, node_complete, wave_start, wave_complete events during graph execution (closes #240)
+- **Semantic LLM cache** — `SemanticCache` uses embeddings for similarity-based cache lookup instead of exact match; configurable threshold and maxsize (closes #196)
+- **Summarization tool** — `SummarizationTool` summarizes text using an LLM with concise, bullet_points, or detailed styles (closes #223)
+- **Sentiment analysis tool** — `SentimentAnalysisTool` analyzes text sentiment (positive/negative/neutral) with confidence and explanation (closes #225)
+- **Translation tool** — `TranslationTool` translates text between languages with optional source language specification (closes #224)
+- 28 new tests (540 total)
+
+---
+
+## [0.6.2] — 2026-03-13
+
+### Added
+
+- **CRAG (Corrective RAG)** — `CRAGRetriever` grades retrieved documents for relevance using an LLM, rewrites the query and retries when too few are relevant (closes #152)
+- **Query Decomposition** — `QueryDecompositionRetriever` breaks complex queries into sub-queries, retrieves for each, and deduplicates results (closes #156)
+- **Contextual Compression** — `ContextualCompressionRetriever` compresses retrieved documents to only the relevant excerpts using an LLM (closes #146)
+- **Ensemble Retrieval** — `EnsembleRetriever` fuses results from multiple retrievers using weighted Reciprocal Rank Fusion (closes #147)
+- **SQLite Conversation Memory** — `SQLiteConversationMemory` persists chat history to SQLite with multi-conversation support and optional sliding window (closes #138)
+- **Summary Buffer Memory** — `SummaryBufferMemory` tracks token budget and progressively summarizes older messages when the buffer exceeds the limit (closes #135)
+- **Human Input Tool** — `HumanInputTool` pauses agent execution to ask the user a question, supports custom sync/async input functions (closes #228)
+- **Wikipedia Tool** — `WikipediaTool` searches and fetches Wikipedia article summaries using the REST API, no extra dependencies (closes #202)
+- 30 new tests (512 total)
+
+---
+
 ## [0.6.1] — 2026-03-13
 
 ### Added

{synapsekit-0.6.2 → synapsekit-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapsekit
-Version: 0.6.2
+Version: 0.6.3
 Summary: Async-native Python framework for building production-grade LLM applications. Streaming-first, 2 dependencies, fully transparent.
 Project-URL: Homepage, https://github.com/SynapseKit/SynapseKit
 Project-URL: Repository, https://github.com/SynapseKit/SynapseKit

{synapsekit-0.6.2 → synapsekit-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synapsekit"
-version = "0.6.2"
+version = "0.6.3"
 description = "Async-native Python framework for building production-grade LLM applications. Streaming-first, 2 dependencies, fully transparent."
 authors = [{ name = "Amit", email = "de.amit.nautiyal@gmail.com" }]
 license = { text = "MIT" }
@@ -13,6 +13,7 @@ requires-python = ">=3.14"
 keywords = ["rag", "llm", "ai", "async", "streaming", "retrieval"]
 classifiers = [
     "Development Status :: 3 - Alpha",
+
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/__init__.py

@@ -32,9 +32,12 @@ from .agents import (
     PythonREPLTool,
     ReActAgent,
     RegexTool,
+    SentimentAnalysisTool,
     SQLQueryTool,
+    SummarizationTool,
     ToolRegistry,
     ToolResult,
+    TranslationTool,
     WebSearchTool,
     WikipediaTool,
     tool,
@@ -47,7 +50,9 @@ from .graph import (
     ConditionalEdge,
     ConditionFn,
     Edge,
+    EventHooks,
     GraphConfigError,
+    GraphEvent,
     GraphInterrupt,
     GraphRuntimeError,
     GraphState,
@@ -56,10 +61,14 @@ from .graph import (
     Node,
     NodeFn,
     SQLiteCheckpointer,
+    StateField,
     StateGraph,
+    TypedState,
     agent_node,
+    fan_out_node,
     llm_node,
     rag_node,
+    sse_stream,
     subgraph_node,
 )
 from .llm.base import BaseLLM, LLMConfig
@@ -104,7 +113,7 @@ from .text_splitters import (
     TokenAwareSplitter,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 __all__ = [
     # Facade
     "RAG",
@@ -190,7 +199,10 @@ __all__ = [
     "JSONQueryTool",
     "PythonREPLTool",
     "RegexTool",
+    "SentimentAnalysisTool",
     "SQLQueryTool",
+    "SummarizationTool",
+    "TranslationTool",
     "WebSearchTool",
     "WikipediaTool",
     # Text splitters
@@ -215,8 +227,14 @@ __all__ = [
     "Edge",
     "ConditionalEdge",
     "ConditionFn",
+    "EventHooks",
+    "GraphEvent",
+    "StateField",
     "StateGraph",
+    "TypedState",
     "CompiledGraph",
+    "fan_out_node",
+    "sse_stream",
     # Checkpointers
     "BaseCheckpointer",
     "InMemoryCheckpointer",

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/agents/__init__.py

@@ -16,7 +16,10 @@ from .tools import (
     JSONQueryTool,
     PythonREPLTool,
     RegexTool,
+    SentimentAnalysisTool,
     SQLQueryTool,
+    SummarizationTool,
+    TranslationTool,
     WebSearchTool,
     WikipediaTool,
 )
@@ -46,7 +49,10 @@ __all__ = [
     "JSONQueryTool",
     "PythonREPLTool",
     "RegexTool",
+    "SentimentAnalysisTool",
     "SQLQueryTool",
+    "SummarizationTool",
+    "TranslationTool",
     "WebSearchTool",
     "WikipediaTool",
 ]

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/agents/tools/__init__.py

@@ -8,7 +8,10 @@ from .human_input import HumanInputTool
 from .json_query import JSONQueryTool
 from .python_repl import PythonREPLTool
 from .regex_tool import RegexTool
+from .sentiment import SentimentAnalysisTool
 from .sql_query import SQLQueryTool
+from .summarization import SummarizationTool
+from .translation import TranslationTool
 from .web_search import WebSearchTool
 from .wikipedia import WikipediaTool
 
@@ -23,7 +26,10 @@ __all__ = [
     "JSONQueryTool",
     "PythonREPLTool",
     "RegexTool",
+    "SentimentAnalysisTool",
     "SQLQueryTool",
+    "SummarizationTool",
+    "TranslationTool",
     "WebSearchTool",
     "WikipediaTool",
 ]

synapsekit-0.6.3/src/synapsekit/agents/tools/sentiment.py

@@ -0,0 +1,57 @@
+"""Sentiment Analysis Tool: analyze sentiment using an LLM."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..base import BaseTool, ToolResult
+
+
+class SentimentAnalysisTool(BaseTool):
+    """Analyze the sentiment of text using an LLM.
+
+    Usage::
+
+        tool = SentimentAnalysisTool(llm=llm)
+        result = await tool.run(text="I love this product!")
+    """
+
+    name = "sentiment_analysis"
+    description = (
+        "Analyze the sentiment of a piece of text. "
+        "Input: the text to analyze. "
+        "Returns: sentiment (positive/negative/neutral), confidence, and explanation."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "text": {
+                "type": "string",
+                "description": "The text to analyze for sentiment",
+            },
+        },
+        "required": ["text"],
+    }
+
+    def __init__(self, llm: Any) -> None:
+        self._llm = llm
+
+    async def run(self, text: str = "", **kwargs: Any) -> ToolResult:
+        input_text = text or kwargs.get("input", "")
+        if not input_text:
+            return ToolResult(output="", error="No text provided for sentiment analysis.")
+
+        prompt = (
+            "Analyze the sentiment of the following text. "
+            "Respond with exactly three lines:\n"
+            "Sentiment: positive/negative/neutral/mixed\n"
+            "Confidence: high/medium/low\n"
+            "Explanation: one sentence explaining why\n\n"
+            f"Text:\n{input_text}"
+        )
+
+        try:
+            result: str = await self._llm.generate(prompt)
+            return ToolResult(output=result.strip())
+        except Exception as e:
+            return ToolResult(output="", error=f"Sentiment analysis failed: {e}")

synapsekit-0.6.3/src/synapsekit/agents/tools/summarization.py

@@ -0,0 +1,79 @@
+"""Text Summarization Tool: summarize text using an LLM."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..base import BaseTool, ToolResult
+
+
+class SummarizationTool(BaseTool):
+    """Summarize text using an LLM.
+
+    Usage::
+
+        tool = SummarizationTool(llm=llm)
+        result = await tool.run(text="Long article text here...")
+    """
+
+    name = "summarize"
+    description = (
+        "Summarize a piece of text. "
+        "Input: the text to summarize, and optionally a max_sentences count. "
+        "Returns: a concise summary of the text."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "text": {
+                "type": "string",
+                "description": "The text to summarize",
+            },
+            "max_sentences": {
+                "type": "integer",
+                "description": "Maximum number of sentences in the summary (default: 3)",
+                "default": 3,
+            },
+            "style": {
+                "type": "string",
+                "description": "Summary style: 'concise', 'bullet_points', or 'detailed' (default: 'concise')",
+                "default": "concise",
+            },
+        },
+        "required": ["text"],
+    }
+
+    def __init__(self, llm: Any) -> None:
+        self._llm = llm
+
+    async def run(
+        self, text: str = "", max_sentences: int = 3, style: str = "concise", **kwargs: Any
+    ) -> ToolResult:
+        input_text = text or kwargs.get("input", "")
+        if not input_text:
+            return ToolResult(output="", error="No text provided to summarize.")
+
+        if style == "bullet_points":
+            prompt = (
+                f"Summarize the following text as {max_sentences} bullet points. "
+                f"Return only the bullet points, one per line starting with '- '.\n\n"
+                f"Text:\n{input_text}"
+            )
+        elif style == "detailed":
+            prompt = (
+                f"Provide a detailed summary of the following text in {max_sentences} sentences. "
+                f"Capture all key points and nuances.\n\n"
+                f"Text:\n{input_text}"
+            )
+        else:
+            prompt = (
+                f"Summarize the following text in {max_sentences} sentences or fewer. "
+                f"Be concise and capture the main points.\n\n"
+                f"Text:\n{input_text}"
+            )
+
+        try:
+            result: str = await self._llm.generate(prompt)
+            return ToolResult(output=result.strip())
+        except Exception as e:
+            return ToolResult(output="", error=f"Summarization failed: {e}")

synapsekit-0.6.3/src/synapsekit/agents/tools/translation.py

@@ -0,0 +1,77 @@
+"""Translation Tool: translate text using an LLM."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..base import BaseTool, ToolResult
+
+
+class TranslationTool(BaseTool):
+    """Translate text between languages using an LLM.
+
+    Usage::
+
+        tool = TranslationTool(llm=llm)
+        result = await tool.run(text="Hello world!", target_language="Spanish")
+    """
+
+    name = "translate"
+    description = (
+        "Translate text from one language to another. "
+        "Input: the text and the target language. "
+        "Returns: the translated text."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "text": {
+                "type": "string",
+                "description": "The text to translate",
+            },
+            "target_language": {
+                "type": "string",
+                "description": "The language to translate to (e.g., 'Spanish', 'French', 'Japanese')",
+            },
+            "source_language": {
+                "type": "string",
+                "description": "The source language (optional, auto-detected if omitted)",
+            },
+        },
+        "required": ["text", "target_language"],
+    }
+
+    def __init__(self, llm: Any) -> None:
+        self._llm = llm
+
+    async def run(
+        self,
+        text: str = "",
+        target_language: str = "",
+        source_language: str = "",
+        **kwargs: Any,
+    ) -> ToolResult:
+        input_text = text or kwargs.get("input", "")
+        if not input_text:
+            return ToolResult(output="", error="No text provided to translate.")
+        if not target_language:
+            return ToolResult(output="", error="No target language specified.")
+
+        if source_language:
+            prompt = (
+                f"Translate the following text from {source_language} to {target_language}. "
+                f"Return only the translated text, nothing else.\n\n"
+                f"Text:\n{input_text}"
+            )
+        else:
+            prompt = (
+                f"Translate the following text to {target_language}. "
+                f"Return only the translated text, nothing else.\n\n"
+                f"Text:\n{input_text}"
+            )
+
+        try:
+            result: str = await self._llm.generate(prompt)
+            return ToolResult(output=result.strip())
+        except Exception as e:
+            return ToolResult(output="", error=f"Translation failed: {e}")

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/graph/__init__.py

@@ -2,10 +2,12 @@ from .checkpointers import BaseCheckpointer, InMemoryCheckpointer, SQLiteCheckpo
 from .compiled import CompiledGraph
 from .edge import ConditionalEdge, ConditionFn, Edge
 from .errors import GraphConfigError, GraphRuntimeError
+from .fan_out import fan_out_node
 from .graph import StateGraph
 from .interrupt import GraphInterrupt, InterruptState
 from .node import Node, NodeFn, agent_node, llm_node, rag_node
-from .state import END, GraphState
+from .state import END, GraphState, StateField, TypedState
+from .streaming import EventHooks, GraphEvent, sse_stream
 from .subgraph import subgraph_node
 
 __all__ = [
@@ -15,7 +17,9 @@ __all__ = [
     "ConditionFn",
     "ConditionalEdge",
     "Edge",
+    "EventHooks",
     "GraphConfigError",
+    "GraphEvent",
     "GraphInterrupt",
     "GraphRuntimeError",
     "GraphState",
@@ -24,9 +28,13 @@ __all__ = [
     "Node",
     "NodeFn",
     "SQLiteCheckpointer",
+    "StateField",
     "StateGraph",
+    "TypedState",
     "agent_node",
+    "fan_out_node",
     "llm_node",
     "rag_node",
+    "sse_stream",
     "subgraph_node",
 ]

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/graph/compiled.py

@@ -10,6 +10,7 @@ from .errors import GraphRuntimeError
 from .interrupt import GraphInterrupt
 from .mermaid import get_mermaid
 from .state import END
+from .streaming import EventHooks, GraphEvent
 
 if TYPE_CHECKING:
     from .checkpointers.base import BaseCheckpointer
@@ -42,15 +43,24 @@ class CompiledGraph:
     # Public API
     # ------------------------------------------------------------------ #
 
+    def _merge_state(self, state: dict[str, Any], partial: dict[str, Any]) -> None:
+        """Merge partial state into current state, using reducers if available."""
+        schema = self._graph._state_schema
+        if schema is not None:
+            schema.merge(state, partial)
+        else:
+            state.update(partial)
+
     async def run(
         self,
         state: dict[str, Any],
         checkpointer: BaseCheckpointer | None = None,
         graph_id: str | None = None,
+        hooks: EventHooks | None = None,
     ) -> dict[str, Any]:
         """Run the graph to completion and return the final state."""
         state = dict(state)
-        async for _ in self._execute(state, checkpointer=checkpointer, graph_id=graph_id):
+        async for _ in self._execute(state, checkpointer=checkpointer, graph_id=graph_id, hooks=hooks):
             pass
         return state
 
@@ -59,13 +69,14 @@ class CompiledGraph:
         state: dict[str, Any],
         checkpointer: BaseCheckpointer | None = None,
         graph_id: str | None = None,
+        hooks: EventHooks | None = None,
     ) -> AsyncGenerator[dict[str, Any]]:
         """
         Yield ``{"node": name, "state": snapshot}`` for each completed node.
         The caller receives incremental state updates as nodes finish.
         """
         state = dict(state)
-        async for event in self._execute(state, checkpointer=checkpointer, graph_id=graph_id):
+        async for event in self._execute(state, checkpointer=checkpointer, graph_id=graph_id, hooks=hooks):
             yield event
 
     async def resume(
@@ -95,11 +106,12 @@ class CompiledGraph:
         state: dict[str, Any],
         checkpointer: BaseCheckpointer | None = None,
         graph_id: str | None = None,
+        hooks: EventHooks | None = None,
     ) -> dict[str, Any]:
         """Synchronous wrapper — works inside and outside a running event loop."""
         from .._compat import run_sync
 
-        return run_sync(self.run(state, checkpointer=checkpointer, graph_id=graph_id))
+        return run_sync(self.run(state, checkpointer=checkpointer, graph_id=graph_id, hooks=hooks))
 
     async def stream_tokens(
         self,
@@ -152,7 +164,7 @@ class CompiledGraph:
                     if "__stream_key__" in result:
                         result[result.pop("__stream_key__")] = "".join(collected)
 
-                state.update(result)
+                self._merge_state(state, result)
                 yield {"type": "node_complete", "node": name, "state": dict(state)}
 
             current_wave = await self._next_wave(current_wave, state)
@@ -169,6 +181,7 @@ class CompiledGraph:
         state: dict[str, Any],
         checkpointer: BaseCheckpointer | None = None,
         graph_id: str | None = None,
+        hooks: EventHooks | None = None,
     ) -> AsyncGenerator[dict[str, Any]]:
         graph = self._graph
         current_wave: list[str] = [graph._entry_point]  # type: ignore[list-item]
@@ -182,6 +195,18 @@ class CompiledGraph:
                 )
             steps += 1
 
+            # Emit wave_start event
+            if hooks is not None:
+                await hooks.emit(GraphEvent(
+                    event_type="wave_start",
+                    data={"wave": current_wave, "step": steps},
+                ))
+
+            # Emit node_start events
+            if hooks is not None:
+                for name in current_wave:
+                    await hooks.emit(GraphEvent(event_type="node_start", node=name))
+
             # Run all nodes in this wave concurrently
             try:
                 results = await asyncio.gather(
@@ -195,9 +220,25 @@ class CompiledGraph:
 
             # Merge partial results into state and yield events
             for name, partial in zip(current_wave, results, strict=False):
-                state.update(partial)
+                self._merge_state(state, partial)
                 yield {"node": name, "state": dict(state)}
 
+                # Emit node_complete event
+                if hooks is not None:
+                    await hooks.emit(GraphEvent(
+                        event_type="node_complete",
+                        node=name,
+                        state=dict(state),
+                    ))
+
+            # Emit wave_complete event
+            if hooks is not None:
+                await hooks.emit(GraphEvent(
+                    event_type="wave_complete",
+                    data={"wave": current_wave, "step": steps},
+                    state=dict(state),
+                ))
+
             # Save checkpoint after wave completion
             if checkpointer is not None and graph_id is not None:
                 checkpointer.save(graph_id, steps, dict(state))

synapsekit-0.6.3/src/synapsekit/graph/fan_out.py

@@ -0,0 +1,72 @@
+"""Parallel subgraph execution — fan-out/fan-in pattern."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .node import NodeFn
+
+
+def fan_out_node(
+    subgraphs: list[Any],
+    input_mappings: list[dict[str, str]] | None = None,
+    output_key: str = "fan_out_results",
+    merge_fn: Any | None = None,
+) -> NodeFn:
+    """Run multiple subgraphs in parallel and collect their results.
+
+    Args:
+        subgraphs: List of ``CompiledGraph`` instances to run concurrently.
+        input_mappings: Optional per-subgraph input key mappings.
+            Each dict maps ``{parent_key: sub_key}``.
+            If ``None``, each subgraph receives the full parent state.
+        output_key: State key to store the list of results.
+        merge_fn: Optional function ``(list[dict]) -> dict`` to merge results
+            into a single dict. If ``None``, results are stored as a list.
+
+    Usage::
+
+        fan = fan_out_node(
+            subgraphs=[compiled_a, compiled_b, compiled_c],
+            input_mappings=[
+                {"query": "input"},
+                {"query": "input"},
+                {"query": "input"},
+            ],
+            output_key="results",
+        )
+        graph.add_node("parallel", fan)
+
+    With a merge function::
+
+        def merge(results):
+            return {"combined": " | ".join(r.get("output", "") for r in results)}
+
+        fan = fan_out_node(
+            subgraphs=[sub_a, sub_b],
+            merge_fn=merge,
+        )
+    """
+    mappings = input_mappings or [None] * len(subgraphs)  # type: ignore[list-item]
+
+    if len(mappings) != len(subgraphs):
+        raise ValueError("input_mappings must have the same length as subgraphs.")
+
+    async def _fn(state: dict[str, Any]) -> dict[str, Any]:
+        tasks = []
+        for sg, mapping in zip(subgraphs, mappings, strict=True):
+            if mapping:
+                sub_state = {sub_key: state[parent_key] for parent_key, sub_key in mapping.items()}
+            else:
+                sub_state = dict(state)
+            tasks.append(sg.run(sub_state))
+
+        results = await asyncio.gather(*tasks)
+
+        if merge_fn is not None:
+            merged: dict[str, Any] = merge_fn(list(results))
+            return merged
+        return {output_key: list(results)}
+
+    return _fn

{synapsekit-0.6.2 → synapsekit-0.6.3}/src/synapsekit/graph/graph.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from .edge import ConditionalEdge, ConditionFn, Edge
 from .errors import GraphConfigError
 from .node import Node, NodeFn
-from .state import END
+from .state import END, TypedState
 
 
 class StateGraph:
@@ -18,12 +18,22 @@ class StateGraph:
         graph.set_entry_point("a").set_finish_point("b")
         compiled = graph.compile()
         result = await compiled.run({"input": "hello"})
+
+    With typed state and reducers::
+
+        from synapsekit.graph.state import StateField, TypedState
+
+        schema = TypedState(fields={
+            "messages": StateField(default=list, reducer=lambda cur, new: cur + new),
+        })
+        graph = StateGraph(state_schema=schema)
     """
 
-    def __init__(self) -> None:
+    def __init__(self, state_schema: TypedState | None = None) -> None:
         self._nodes: dict[str, Node] = {}
         self._edges: list[Edge | ConditionalEdge] = []
         self._entry_point: str | None = None
+        self._state_schema = state_schema
 
     def __repr__(self) -> str:
         return f"StateGraph(nodes={len(self._nodes)}, edges={len(self._edges)})"