synapsekit 1.2.0__tar.gz → 1.3.0__tar.gz

{synapsekit-1.2.0 → synapsekit-1.3.0}/.gitignore

@@ -70,3 +70,4 @@ docs/
 # Saved vectorstores
 *.npz
 typescript
+.synapsekit_evals/

{synapsekit-1.2.0 → synapsekit-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapsekit
-Version: 1.2.0
+Version: 1.3.0
 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
@@ -32,6 +32,7 @@ Requires-Dist: faiss-cpu>=1.7; extra == 'all'
 Requires-Dist: fastapi>=0.110; extra == 'all'
 Requires-Dist: google-cloud-aiplatform>=1.38; extra == 'all'
 Requires-Dist: google-generativeai>=0.7; extra == 'all'
+Requires-Dist: groq>=0.9; extra == 'all'
 Requires-Dist: httpx>=0.27; extra == 'all'
 Requires-Dist: lxml>=5.0; extra == 'all'
 Requires-Dist: mcp>=1.0; extra == 'all'
@@ -49,6 +50,8 @@ Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
 Requires-Dist: youtube-search-python>=1.6; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: audio
+Requires-Dist: openai>=1.0; extra == 'audio'
 Provides-Extra: bedrock
 Requires-Dist: boto3>=1.34; extra == 'bedrock'
 Provides-Extra: chroma
@@ -101,6 +104,8 @@ Provides-Extra: tavily
 Requires-Dist: tavily-python>=0.3; extra == 'tavily'
 Provides-Extra: vertex
 Requires-Dist: google-cloud-aiplatform>=1.38; extra == 'vertex'
+Provides-Extra: video
+Requires-Dist: openai>=1.0; extra == 'video'
 Provides-Extra: web
 Requires-Dist: beautifulsoup4>=4.12; extra == 'web'
 Requires-Dist: httpx>=0.27; extra == 'web'

{synapsekit-1.2.0 → synapsekit-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synapsekit"
-version = "1.2.0"
+version = "1.3.0"
 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 = "Apache-2.0" }
@@ -53,6 +53,8 @@ mistral = ["mistralai>=1.0"]
 gemini = ["google-generativeai>=0.7"]
 bedrock = ["boto3>=1.34"]
 groq = ["groq>=0.9"]
+audio = ["openai>=1.0"]
+video = ["openai>=1.0"]
 excel = ["openpyxl>=3.1"]
 pptx = ["python-pptx>=0.6"]
 docx = ["python-docx>=1.0"]
@@ -91,6 +93,7 @@ all = [
     "fastapi>=0.110",
     "uvicorn[standard]>=0.29",
     "psycopg[binary]>=3.1",
+    "groq>=0.9",
 ]
 
 [dependency-groups]
@@ -197,6 +200,6 @@ youtube-search-python = "youtubesearchpython"
 google-cloud-aiplatform = "vertexai"
 
 [tool.deptry.per_rule_ignores]
-DEP001 = ["sqlalchemy", "pydantic", "aiohttp", "opentelemetry"]
+DEP001 = ["sqlalchemy", "pydantic", "aiohttp", "opentelemetry", "whisper"]
 DEP002 = ["numpy", "rank-bm25", "beautifulsoup4", "lxml", "faiss-cpu", "google-generativeai", "tavily-python", "youtube-search-python", "psycopg"]
 DEP004 = ["pydantic"]

{synapsekit-1.2.0 → synapsekit-1.3.0}/src/synapsekit/__init__.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 from ._api import deprecated, experimental, public_api
 from .a2a import A2AClient, A2AMessage, A2AServer, A2ATask, AgentCard, TaskState
 from .agents import (
+    ActionEvent,
     AgentConfig,
     AgentExecutor,
     AgentMemory,
@@ -32,9 +33,11 @@ from .agents import (
     DateTimeTool,
     DuckDuckGoSearchTool,
     EmailTool,
+    ErrorEvent,
     FileListTool,
     FileReadTool,
     FileWriteTool,
+    FinalAnswerEvent,
     FunctionCallingAgent,
     GitHubAPITool,
     GraphQLTool,
@@ -47,21 +50,27 @@ from .agents import (
     HumanInputTool,
     JiraTool,
     JSONQueryTool,
+    ObservationEvent,
     PDFReaderTool,
     PIIDetector,
+    PIIRedactor,
     PubMedSearchTool,
     PythonREPLTool,
     ReActAgent,
+    RedactionResult,
     RegexTool,
     SentimentAnalysisTool,
     ShellTool,
     SlackTool,
     SQLQueryTool,
     SQLSchemaInspectionTool,
+    StepEvent,
     SummarizationTool,
     SupervisorAgent,
     Task,
     TavilySearchTool,
+    ThoughtEvent,
+    TokenEvent,
     ToolRegistry,
     ToolResult,
     TopicRestrictor,
@@ -77,11 +86,15 @@ from .agents import (
 from .embeddings.backend import SynapsekitEmbeddings
 from .evaluation import (
     EvalCaseMeta,
+    EvalRegression,
+    EvalSnapshot,
     EvaluationPipeline,
     EvaluationResult,
     FaithfulnessMetric,
     GroundednessMetric,
+    MetricDelta,
     MetricResult,
+    RegressionReport,
     RelevancyMetric,
     eval_case,
 )
@@ -122,6 +135,8 @@ from .graph import (
     ws_stream,
 )
 from .llm.base import BaseLLM, LLMConfig
+from .llm.cost_router import QUALITY_TABLE, CostRouter, CostRouterConfig, RouterModelSpec
+from .llm.fallback_chain import FallbackChain, FallbackChainConfig
 from .llm.multimodal import AudioContent, ImageContent, MultimodalMessage
 from .llm.structured import generate_structured
 from .loaders.base import Document
@@ -144,6 +159,8 @@ from .memory.sqlite import SQLiteConversationMemory
 from .memory.summary_buffer import SummaryBufferMemory
 from .memory.token_buffer import TokenBufferMemory
 from .observability import (
+    AuditEntry,
+    AuditLog,
     BudgetExceededError,
     BudgetGuard,
     BudgetLimit,
@@ -197,7 +214,7 @@ from .text_splitters import (
     TokenAwareSplitter,
 )
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 __all__ = [
     # Facade
     "RAG",
@@ -207,6 +224,12 @@ __all__ = [
     # LLM
     "BaseLLM",
     "LLMConfig",
+    "CostRouter",
+    "CostRouterConfig",
+    "RouterModelSpec",
+    "QUALITY_TABLE",
+    "FallbackChain",
+    "FallbackChainConfig",
     "AzureOpenAILLM",
     "CerebrasLLM",
     "DeepSeekLLM",
@@ -395,14 +418,20 @@ __all__ = [
     "generate_structured",
     # Evaluation
     "EvalCaseMeta",
+    "EvalRegression",
+    "EvalSnapshot",
     "EvaluationPipeline",
     "EvaluationResult",
     "FaithfulnessMetric",
     "GroundednessMetric",
+    "MetricDelta",
     "MetricResult",
+    "RegressionReport",
     "RelevancyMetric",
     "eval_case",
     # Observability
+    "AuditEntry",
+    "AuditLog",
     "DistributedTracer",
     "OTelExporter",
     "Span",
@@ -421,11 +450,23 @@ __all__ = [
     "Guardrails",
     "GuardrailResult",
     "PIIDetector",
+    "PIIRedactor",
+    "RedactionResult",
     "TopicRestrictor",
+    # Step events
+    "ActionEvent",
+    "ErrorEvent",
+    "FinalAnswerEvent",
+    "ObservationEvent",
+    "StepEvent",
+    "ThoughtEvent",
+    "TokenEvent",
     # Multimodal
     "AudioContent",
     "ImageContent",
     "MultimodalMessage",
+    "AudioLoader",
+    "VideoLoader",
     "ImageLoader",
     # Plugins
     "PluginRegistry",
@@ -456,6 +497,8 @@ _LAZY_IMPORTS = {
     "RedisCheckpointer": "graph.checkpointers.redis",
     "PostgresCheckpointer": "graph.checkpointers.postgres",
     # Loaders
+    "AudioLoader": "loaders.audio",
+    "VideoLoader": "loaders.video",
     "DocxLoader": "loaders.docx",
     "ExcelLoader": "loaders.excel",
     "PowerPointLoader": "loaders.pptx",

{synapsekit-1.2.0 → synapsekit-1.3.0}/src/synapsekit/agents/__init__.py

@@ -20,8 +20,18 @@ from .multi import (
     Task,
     WorkerAgent,
 )
+from .pii_redactor import PIIRedactor, RedactionResult
 from .react import ReActAgent
 from .registry import ToolRegistry
+from .step_events import (
+    ActionEvent,
+    ErrorEvent,
+    FinalAnswerEvent,
+    ObservationEvent,
+    StepEvent,
+    ThoughtEvent,
+    TokenEvent,
+)
 from .tool_decorator import tool
 from .tools import (
     ArxivSearchTool,
@@ -111,6 +121,17 @@ __all__ = [
     "WebSearchTool",
     "WikipediaTool",
     "YouTubeSearchTool",
+    # PIIRedactor
+    "PIIRedactor",
+    "RedactionResult",
+    # Step events
+    "ActionEvent",
+    "ErrorEvent",
+    "FinalAnswerEvent",
+    "ObservationEvent",
+    "StepEvent",
+    "ThoughtEvent",
+    "TokenEvent",
     # Multi-agent
     "Crew",
     "CrewAgent",

{synapsekit-1.2.0 → synapsekit-1.3.0}/src/synapsekit/agents/function_calling.py

@@ -125,6 +125,97 @@ class FunctionCallingAgent:
         for word in answer.split(" "):
             yield word + " "
 
+    async def stream_steps(self, query: str) -> AsyncGenerator:
+        """Stream step-by-step events for function-calling agent.
+
+        Yields ``StepEvent`` instances (``ActionEvent``, ``ObservationEvent``,
+        ``TokenEvent``, ``FinalAnswerEvent``, ``ErrorEvent``).
+        """
+        from .step_events import (
+            ActionEvent,
+            ErrorEvent,
+            FinalAnswerEvent,
+            ObservationEvent,
+            TokenEvent,
+        )
+
+        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:
+                answer = content or ""
+                for token in answer.split(" "):
+                    yield TokenEvent(token=token + " ")
+                yield FinalAnswerEvent(answer=answer)
+                return
+
+            # 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
+            for tc in tool_calls:
+                yield ActionEvent(tool=tc["name"], tool_input=tc["arguments"])
+
+                try:
+                    tool = self._registry.get(tc["name"])
+                    tool_result = await tool.run(**tc["arguments"])
+                    observation = str(tool_result)
+                except Exception as e:
+                    observation = f"Error: {e}"
+                    yield ErrorEvent(error=str(e))
+
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc["id"],
+                        "content": observation,
+                    }
+                )
+                yield ObservationEvent(observation=observation, tool=tc["name"])
+
+                self._memory.add_step(
+                    AgentStep(
+                        thought="",
+                        action=tc["name"],
+                        action_input=json.dumps(tc["arguments"]),
+                        observation=observation,
+                    )
+                )
+
+        yield FinalAnswerEvent(
+            answer="I was unable to complete the task within the allowed number of steps."
+        )
+
     @property
     def memory(self) -> AgentMemory:
         return self._memory

synapsekit-1.3.0/src/synapsekit/agents/pii_redactor.py

@@ -0,0 +1,103 @@
+"""PIIRedactor — redact and optionally restore PII in text."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from ..llm.base import BaseLLM
+from .guardrails import PIIDetector
+
+
+@dataclass
+class RedactionResult:
+    """Result of a PII redaction operation."""
+
+    redacted_text: str
+    mapping: dict[str, str] = field(default_factory=dict)
+    pii_types_found: list[str] = field(default_factory=list)
+
+
+class PIIRedactor:
+    """Redact PII from text using the existing ``PIIDetector`` patterns.
+
+    Supports two modes:
+
+    - ``"mask"`` (default) — reversible; replaces PII with placeholders like
+      ``[EMAIL_1]`` and stores a mapping so originals can be restored.
+    - ``"redact"`` — irreversible; same placeholders but no restore.
+
+    Same-value deduplication: identical PII values always receive the same
+    placeholder within a single ``redact()`` call.
+
+    Example::
+
+        redactor = PIIRedactor(pii_types=["email", "phone"])
+        result = redactor.redact("Email me at a@b.com or a@b.com, call 555-123-4567")
+        # result.redacted_text -> "Email me at [EMAIL_1] or [EMAIL_1], call [PHONE_1]"
+        original = redactor.restore(result.redacted_text, result.mapping)
+    """
+
+    def __init__(
+        self,
+        pii_types: list[str] | None = None,
+        mode: str = "mask",
+    ) -> None:
+        if mode not in ("mask", "redact"):
+            raise ValueError(f"mode must be 'mask' or 'redact', got {mode!r}")
+        self._mode = mode
+        self._pii_types = pii_types or list(PIIDetector._PATTERNS.keys())
+        self._compiled: dict[str, re.Pattern[str]] = {
+            name: re.compile(pattern)
+            for name, pattern in PIIDetector._PATTERNS.items()
+            if name in self._pii_types
+        }
+
+    def redact(self, text: str) -> RedactionResult:
+        """Replace PII with numbered placeholders."""
+        mapping: dict[str, str] = {}  # placeholder -> original
+        value_to_placeholder: dict[str, str] = {}  # original -> placeholder
+        counters: dict[str, int] = {}
+        pii_types_found: set[str] = set()
+        redacted = text
+
+        for pii_type, pattern in self._compiled.items():
+            matches = pattern.findall(redacted)
+            if not matches:
+                continue
+            pii_types_found.add(pii_type)
+            for match in matches:
+                if match in value_to_placeholder:
+                    continue
+                tag = pii_type.upper()
+                counters.setdefault(pii_type, 0)
+                counters[pii_type] += 1
+                placeholder = f"[{tag}_{counters[pii_type]}]"
+                value_to_placeholder[match] = placeholder
+                mapping[placeholder] = match
+
+        # Apply replacements (longest values first to avoid partial matches)
+        for value in sorted(value_to_placeholder, key=len, reverse=True):
+            redacted = redacted.replace(value, value_to_placeholder[value])
+
+        return RedactionResult(
+            redacted_text=redacted,
+            mapping=mapping if self._mode == "mask" else {},
+            pii_types_found=sorted(pii_types_found),
+        )
+
+    def restore(self, text: str, mapping: dict[str, str]) -> str:
+        """Re-inject original PII values. No-op in ``'redact'`` mode."""
+        if self._mode == "redact" or not mapping:
+            return text
+        result = text
+        for placeholder, original in mapping.items():
+            result = result.replace(placeholder, original)
+        return result
+
+    async def wrap_generate(self, llm: BaseLLM, prompt: str) -> tuple[str, RedactionResult]:
+        """Convenience: redact prompt, generate, restore response."""
+        redaction = self.redact(prompt)
+        response = await llm.generate(redaction.redacted_text)
+        restored = self.restore(response, redaction.mapping)
+        return restored, redaction

{synapsekit-1.2.0 → synapsekit-1.3.0}/src/synapsekit/agents/react.py

@@ -149,6 +149,75 @@ class ReActAgent:
         for word in answer.split(" "):
             yield word + " "
 
+    async def stream_steps(self, query: str) -> AsyncGenerator:
+        """Stream step-by-step events including thoughts, actions, and tokens.
+
+        Yields ``StepEvent`` instances (``ThoughtEvent``, ``ActionEvent``,
+        ``ObservationEvent``, ``TokenEvent``, ``FinalAnswerEvent``, ``ErrorEvent``).
+        """
+        from .step_events import (
+            ActionEvent,
+            ErrorEvent,
+            FinalAnswerEvent,
+            ObservationEvent,
+            ThoughtEvent,
+            TokenEvent,
+        )
+
+        self._memory.clear()
+
+        for _ in range(self._max_iterations):
+            messages = self._build_messages(query)
+
+            # Stream tokens live
+            full_response = ""
+            async for token in self._llm.stream_with_messages(messages):
+                yield TokenEvent(token=token)
+                full_response += token
+
+            # Check for final answer
+            final = _parse_final_answer(full_response)
+            if final is not None:
+                yield FinalAnswerEvent(answer=final)
+                return
+
+            # Parse action
+            action_name, action_input = _parse_action(full_response)
+            thought = _parse_thought(full_response)
+
+            if thought:
+                yield ThoughtEvent(thought=thought)
+
+            if not action_name:
+                yield FinalAnswerEvent(answer=full_response.strip())
+                return
+
+            yield ActionEvent(tool=action_name, tool_input=action_input)
+
+            # Execute tool
+            try:
+                tool = self._registry.get(action_name)
+                result = await tool.run(input=action_input)
+                observation = str(result)
+            except Exception as e:
+                observation = f"Error: {e}"
+                yield ErrorEvent(error=str(e))
+
+            yield ObservationEvent(observation=observation, tool=action_name)
+
+            self._memory.add_step(
+                AgentStep(
+                    thought=thought,
+                    action=action_name,
+                    action_input=action_input,
+                    observation=observation,
+                )
+            )
+
+        yield FinalAnswerEvent(
+            answer="I was unable to find the answer within the allowed number of steps."
+        )
+
     @property
     def memory(self) -> AgentMemory:
         return self._memory

synapsekit-1.3.0/src/synapsekit/agents/step_events.py

@@ -0,0 +1,61 @@
+"""Step event types for streaming agent reasoning."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ThoughtEvent:
+    """Agent's internal reasoning step."""
+
+    thought: str
+    type: str = "thought"
+
+
+@dataclass
+class ActionEvent:
+    """Agent decided to call a tool."""
+
+    tool: str
+    tool_input: str | dict[str, Any] = ""
+    type: str = "action"
+
+
+@dataclass
+class ObservationEvent:
+    """Result from a tool execution."""
+
+    observation: str
+    tool: str = ""
+    type: str = "observation"
+
+
+@dataclass
+class TokenEvent:
+    """A single streamed token from the LLM."""
+
+    token: str
+    type: str = "token"
+
+
+@dataclass
+class FinalAnswerEvent:
+    """The agent's final answer."""
+
+    answer: str
+    type: str = "final_answer"
+
+
+@dataclass
+class ErrorEvent:
+    """An error occurred during agent execution."""
+
+    error: str
+    type: str = "error"
+
+
+StepEvent = (
+    ThoughtEvent | ActionEvent | ObservationEvent | TokenEvent | FinalAnswerEvent | ErrorEvent
+)

{synapsekit-1.2.0 → synapsekit-1.3.0}/src/synapsekit/cli/main.py

@@ -27,6 +27,29 @@ def _add_test_parser(subparsers: argparse._SubParsersAction) -> None:  # type: i
         default="table",
         help="Output format (default: table)",
     )
+    p.add_argument(
+        "--save",
+        dest="save_snapshot",
+        metavar="NAME",
+        help="Save results as a named snapshot",
+    )
+    p.add_argument(
+        "--compare",
+        dest="compare_baseline",
+        metavar="BASELINE",
+        help="Compare results against a saved baseline snapshot",
+    )
+    p.add_argument(
+        "--fail-on-regression",
+        action="store_true",
+        default=False,
+        help="Exit with code 1 if regressions are detected",
+    )
+    p.add_argument(
+        "--snapshot-dir",
+        default=".synapsekit_evals",
+        help="Snapshot storage directory (default: .synapsekit_evals)",
+    )
 
 
 def main(argv: list[str] | None = None) -> None: