synkt 0.1.0__tar.gz

synkt-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: synkt
+Version: 0.1.0
+Summary: Testing framework for multi-agent LLM systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"

synkt-0.1.0/README.md

@@ -0,0 +1,104 @@
+# synkt
+
+A small testing framework for multi-agent systems.
+
+```python
+from synkt import assert_handoff, assert_no_loop
+from synkt.interceptors.langgraph import LangGraphInterceptor
+
+from examples.customer_service.system import build_customer_service_graph
+
+
+def test_refund_flow():
+    graph = build_customer_service_graph()
+    test_graph = LangGraphInterceptor(graph)
+
+    result = test_graph.invoke({"input": "refund for order #12345"})
+
+    assert_handoff("triage", "refunds")
+    assert_no_loop(max_iterations=5)
+    assert "12345" in result["resolution"]
+```
+
+## Why synkt?
+
+Most eval tools check final output quality. That is useful, but multi-agent bugs usually happen in the middle:
+
+- Agent A hands off to the wrong agent
+- A tool gets called with the wrong payload
+- A flow starts looping and burns tokens
+- Parallel steps stop being parallel after a refactor
+
+`synkt` is for testing those coordination paths directly.
+
+## Installation
+
+```bash
+pip install synkt
+```
+
+For local development in this repo:
+
+```bash
+pip install -e .
+pip install -e ".[dev,langgraph]"
+```
+
+## Quick Start
+
+1. Build your agent graph/system as normal.
+2. Wrap it with an interceptor (for now: LangGraph).
+3. Run it in a test.
+4. Assert on handoffs, loops, tools, and cost.
+
+```python
+from synkt import assert_handoff, assert_no_loop
+from synkt.interceptors.langgraph import LangGraphInterceptor
+
+
+def test_my_flow():
+    graph = build_graph()
+    tested = LangGraphInterceptor(graph)
+
+    tested.invoke({"input": "help me with my refund"})
+
+    assert_handoff("triage", "refunds")
+    assert_no_loop(max_iterations=5)
+```
+
+## Examples
+
+See real working examples:
+- [Customer Service](examples/customer_service/) - Sequential agent flow
+- [Research Crew](examples/research_crew/) - Parallel agent execution
+
+## Documentation
+
+- Design doc: [docs/DESIGN.md](docs/DESIGN.md)
+
+## Features
+
+- Test agent handoffs
+- Prevent infinite loops
+- Validate tool calls
+- Mock agents for isolation
+- Works with LangGraph today, with CrewAI and AutoGen adapters planned
+
+## Contributing
+
+PRs are welcome. A good starting point:
+
+1. Add or update tests first.
+2. Keep error messages specific and useful.
+3. Keep APIs typed and easy to read.
+
+Run locally before opening a PR:
+
+```bash
+pytest -q
+```
+
+## License
+
+MIT
+

synkt-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synkt"
+version = "0.1.0"
+description = "Testing framework for multi-agent LLM systems"
+readme = "docs/DESIGN.md"
+requires-python = ">=3.10"
+dependencies = [
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+  "black>=24.0",
+]
+langgraph = [
+  "langgraph>=0.2",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests", "examples"]
+

synkt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synkt-0.1.0/synkt/__init__.py

@@ -0,0 +1,28 @@
+"""synkt - Testing framework for multi-agent LLM systems."""
+
+__version__ = "0.1.0"
+
+from synkt.assertions.coordination import assert_handoff, assert_parallel_execution
+from synkt.assertions.system import assert_cost_under, assert_no_loop
+from synkt.assertions.tools import assert_no_tool_called, assert_tool_called
+from synkt.interceptors.langgraph import LangGraphInterceptor
+from synkt.trace.models import AgentMessage, AgentTrace, ToolCall
+from synkt.trace.pretty import format_trace, print_trace
+from synkt.trace.storage import get_current_trace
+
+__all__ = [
+	"assert_handoff",
+	"assert_parallel_execution",
+	"assert_tool_called",
+	"assert_no_tool_called",
+	"assert_no_loop",
+	"assert_cost_under",
+	"LangGraphInterceptor",
+	"AgentTrace",
+	"AgentMessage",
+	"ToolCall",
+	"get_current_trace",
+	"format_trace",
+	"print_trace",
+]
+

synkt-0.1.0/synkt/assertions/__init__.py

@@ -0,0 +1,15 @@
+"""Assertion helpers for agent coordination tests."""
+
+from synkt.assertions.coordination import assert_handoff, assert_parallel_execution
+from synkt.assertions.system import assert_cost_under, assert_no_loop
+from synkt.assertions.tools import assert_no_tool_called, assert_tool_called
+
+__all__ = [
+    "assert_handoff",
+    "assert_parallel_execution",
+    "assert_tool_called",
+    "assert_no_tool_called",
+    "assert_no_loop",
+    "assert_cost_under",
+]
+

synkt-0.1.0/synkt/assertions/coordination.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Type
+
+from pydantic import BaseModel
+
+from synkt.trace.storage import get_current_trace
+
+
+def assert_handoff(
+    from_agent: str,
+    to_agent: str,
+    message_schema: Optional[Type[BaseModel]] = None,
+    **kwargs: str,
+) -> None:
+    """
+    Assert that one agent handed off to another.
+
+    Args:
+        from_agent: Name of the agent that initiated handoff
+        to_agent: Name of the agent that received handoff
+        message_schema: Optional Pydantic model to validate message content
+
+    Raises:
+        AssertionError: If handoff didn't occur or schema doesn't match
+
+    Examples:
+        >>> assert_handoff("triage", "refunds")
+    """
+    # Backward compatibility with docs/examples using from_node/to_node.
+    from_agent = kwargs.get("from_node", from_agent)
+    to_agent = kwargs.get("to_node", to_agent)
+
+    trace = get_current_trace()
+    handoffs = [
+        msg
+        for msg in trace.messages
+        if msg.from_agent == from_agent and msg.to_agent == to_agent
+    ]
+
+    if not handoffs:
+        raise AssertionError(
+            f"No handoff from '{from_agent}' to '{to_agent}'. "
+            f"Found {len(trace.messages)} total messages: "
+            f"{[(m.from_agent, m.to_agent) for m in trace.messages]}"
+        )
+
+    if message_schema:
+        handoff = handoffs[0]
+        try:
+            message_schema(**handoff.content)
+        except Exception as exc:  # pragma: no cover - exact pydantic error varies
+            raise AssertionError(
+                f"Handoff message doesn't match schema {message_schema.__name__}: {exc}"
+            ) from exc
+
+
+def assert_parallel_execution(agents: list[str], max_time_delta_ms: float = 50.0) -> None:
+    """
+    Assert that multiple agents executed in near-parallel based on timestamps.
+
+    Args:
+        agents: Agent names expected to run in parallel
+        max_time_delta_ms: Maximum allowed span between earliest and latest event
+
+    Raises:
+        AssertionError: If insufficient events are present or timing is too far apart
+    """
+    trace = get_current_trace()
+    timestamps: list[datetime] = []
+
+    for message in trace.messages:
+        if message.from_agent in agents or message.to_agent in agents:
+            timestamps.append(message.timestamp)
+
+    if len(timestamps) < len(agents):
+        raise AssertionError(
+            f"Expected events for {len(agents)} agents, found {len(timestamps)} relevant messages"
+        )
+
+    span_ms = (max(timestamps) - min(timestamps)).total_seconds() * 1000
+    if span_ms > max_time_delta_ms:
+        raise AssertionError(
+            f"Expected parallel execution within {max_time_delta_ms}ms, observed {span_ms:.2f}ms"
+        )
+

synkt-0.1.0/synkt/assertions/system.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections import Counter
+
+from synkt.trace.storage import get_current_trace
+
+
+def assert_no_loop(max_iterations: int = 10) -> None:
+    """
+    Assert that no agent was called excessively (loop detection).
+
+    Args:
+        max_iterations: Max times any single agent can appear in trace
+    """
+    trace = get_current_trace()
+    agent_counts = Counter()
+
+    for msg in trace.messages:
+        agent_counts[msg.from_agent] += 1
+        agent_counts[msg.to_agent] += 1
+
+    for agent, count in agent_counts.items():
+        if count > max_iterations:
+            raise AssertionError(
+                f"Agent '{agent}' appears {count} times (max: {max_iterations}). "
+                "Possible infinite loop detected."
+            )
+
+
+def assert_cost_under(threshold: float) -> None:
+    """
+    Assert that total cost is under threshold.
+
+    Args:
+        threshold: Maximum allowed cost in dollars
+    """
+    trace = get_current_trace()
+
+    if trace.total_cost > threshold:
+        raise AssertionError(
+            f"Test cost ${trace.total_cost:.2f} exceeds threshold ${threshold:.2f}"
+        )
+

synkt-0.1.0/synkt/assertions/tools.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from synkt.trace.storage import get_current_trace
+
+
+def assert_tool_called(
+    tool_name: str,
+    args: Optional[dict[str, Any]] = None,
+    times: int = 1,
+    by_agent: Optional[str] = None,
+) -> None:
+    """
+    Assert that a tool was called.
+
+    Args:
+        tool_name: Name of the tool
+        args: Optional dict of expected arguments
+        times: Expected number of calls (default 1)
+        by_agent: Optional agent name filter
+    """
+    trace = get_current_trace()
+    calls = [tc for tc in trace.tool_calls if tc.tool_name == tool_name]
+
+    if by_agent:
+        calls = [tc for tc in calls if tc.agent == by_agent]
+
+    if len(calls) != times:
+        raise AssertionError(f"Expected {times} calls to '{tool_name}', got {len(calls)}")
+
+    if args:
+        for call in calls:
+            for key, expected_value in args.items():
+                actual_value = call.args.get(key)
+                if actual_value != expected_value:
+                    raise AssertionError(
+                        f"Tool '{tool_name}' called with {key}={actual_value}, "
+                        f"expected {expected_value}"
+                    )
+
+
+def assert_no_tool_called(tool_name: str, by_agent: Optional[str] = None) -> None:
+    """Assert that a tool was never called."""
+    trace = get_current_trace()
+    calls = [tc for tc in trace.tool_calls if tc.tool_name == tool_name]
+
+    if by_agent:
+        calls = [tc for tc in calls if tc.agent == by_agent]
+
+    if calls:
+        raise AssertionError(
+            f"Expected no calls to '{tool_name}', but found {len(calls)} calls"
+        )
+

synkt-0.1.0/synkt/interceptors/__init__.py

@@ -0,0 +1,6 @@
+"""Framework interceptors for trace collection."""
+
+from synkt.interceptors.langgraph import LangGraphInterceptor
+
+__all__ = ["LangGraphInterceptor"]
+

synkt-0.1.0/synkt/interceptors/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseInterceptor(ABC):
+    """Base interface for framework interceptors."""
+
+    @abstractmethod
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the wrapped multi-agent system."""
+        raise NotImplementedError

synkt-0.1.0/synkt/interceptors/crewai.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from synkt.interceptors.base import BaseInterceptor
+
+
+class CrewAIInterceptor(BaseInterceptor):
+    """Placeholder interceptor for future CrewAI integration."""
+
+    def __init__(self, crew: Any):
+        self.crew = crew
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError("CrewAIInterceptor is not implemented in this MVP")
+

synkt-0.1.0/synkt/interceptors/langgraph.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from synkt.interceptors.base import BaseInterceptor
+from synkt.trace.storage import get_current_trace
+
+
+class LangGraphInterceptor(BaseInterceptor):
+    """
+    Wrapper for LangGraph StateGraph that captures node transitions.
+
+    The wrapped object is expected to expose:
+    - graph.nodes: mapping of node_name -> callable
+    - graph.compile().invoke(...): invocation API
+    """
+
+    def __init__(self, graph: Any):
+        self.graph = graph
+        self._original_nodes: dict[str, Callable[..., Any]] = {}
+        self._previous_node_name = "start"
+        self._wrap_nodes()
+
+    def _wrap_nodes(self) -> None:
+        """Wrap each node runnable/function to capture transitions."""
+        for node_name, node_obj in self.graph.nodes.items():
+            # LangGraph StateGraph stores a StateNodeSpec with a `.runnable` attribute.
+            if hasattr(node_obj, "runnable"):
+                original = node_obj.runnable
+                self._original_nodes[node_name] = original
+                node_obj.runnable = self._create_wrapper(node_name, original)
+            else:
+                # Fallback for simpler graph doubles used in local tests.
+                self._original_nodes[node_name] = node_obj
+                self.graph.nodes[node_name] = self._create_wrapper(node_name, node_obj)
+
+    def _create_wrapper(self, node_name: str, original_func: Callable[..., Any]) -> Callable[..., Any]:
+        """Create a wrapper that logs node handoffs to trace."""
+
+        def wrapper(state: Any) -> Any:
+            trace = get_current_trace()
+            prev_node = self._previous_node_name
+
+            trace.add_message(
+                from_agent=prev_node,
+                to_agent=node_name,
+                content={"state": state},
+            )
+
+            if callable(original_func):
+                result = original_func(state)
+            elif hasattr(original_func, "invoke"):
+                result = original_func.invoke(state)
+            else:
+                raise TypeError(
+                    f"Unsupported node runnable type for '{node_name}': {type(original_func)!r}"
+                )
+
+            self._previous_node_name = node_name
+
+            return result
+
+        return wrapper
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the graph (same API as StateGraph.invoke)."""
+        self._previous_node_name = "start"
+        return self.graph.compile().invoke(*args, **kwargs)
+

synkt-0.1.0/synkt/mocking/__init__.py

@@ -0,0 +1,6 @@
+"""Mocking utilities for agent stubs."""
+
+from synkt.mocking.mock_agent import mock_agent
+
+__all__ = ["mock_agent"]
+

synkt-0.1.0/synkt/mocking/mock_agent.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def mock_agent(response: Any = None, side_effect: Exception | None = None) -> Callable[[F], F]:
+    """
+    Decorator that replaces an agent function with deterministic behavior.
+
+    Args:
+        response: Static return value to use instead of running the wrapped function
+        side_effect: Optional exception to raise when the function is called
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if side_effect is not None:
+                raise side_effect
+            if response is not None:
+                return response
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

synkt-0.1.0/synkt/pytest_plugin.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import pytest
+
+from synkt.trace.models import AgentTrace
+from synkt.trace.storage import clear_current_trace, set_current_trace
+
+
+@pytest.fixture(autouse=True)
+def synkt_trace() -> AgentTrace:
+    """Automatically create and clean up trace for each test."""
+    trace = AgentTrace()
+    set_current_trace(trace)
+    yield trace
+    clear_current_trace()
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register synkt markers."""
+    config.addinivalue_line(
+        "markers",
+        "synkt: mark test as an agent coordination test",
+    )
+

synkt-0.1.0/synkt/trace/__init__.py

@@ -0,0 +1,17 @@
+"""Trace models and storage utilities."""
+
+from synkt.trace.models import AgentMessage, AgentTrace, ToolCall
+from synkt.trace.pretty import format_trace, print_trace
+from synkt.trace.storage import clear_current_trace, get_current_trace, set_current_trace
+
+__all__ = [
+    "AgentMessage",
+    "AgentTrace",
+    "ToolCall",
+    "format_trace",
+    "print_trace",
+    "get_current_trace",
+    "set_current_trace",
+    "clear_current_trace",
+]
+

synkt-0.1.0/synkt/trace/models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class AgentMessage(BaseModel):
+    """A message sent from one agent to another."""
+
+    from_agent: str
+    to_agent: str
+    content: dict[str, Any]
+    timestamp: datetime
+
+
+class ToolCall(BaseModel):
+    """A tool called by an agent."""
+
+    agent: str
+    tool_name: str
+    args: dict[str, Any]
+    result: Optional[Any] = None
+    timestamp: datetime
+    duration_ms: float
+
+
+class AgentTrace(BaseModel):
+    """Complete trace of multi-agent execution."""
+
+    messages: list[AgentMessage] = Field(default_factory=list)
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    total_cost: float = 0.0
+    duration_ms: float = 0.0
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def add_message(self, from_agent: str, to_agent: str, content: dict[str, Any]) -> None:
+        """Add a message to the trace."""
+        self.messages.append(
+            AgentMessage(
+                from_agent=from_agent,
+                to_agent=to_agent,
+                content=content,
+                timestamp=datetime.now(),
+            )
+        )
+
+    def add_tool_call(
+        self,
+        agent: str,
+        tool_name: str,
+        args: dict[str, Any],
+        result: Any = None,
+        duration_ms: float = 0.0,
+    ) -> None:
+        """Add a tool call to the trace."""
+        self.tool_calls.append(
+            ToolCall(
+                agent=agent,
+                tool_name=tool_name,
+                args=args,
+                result=result,
+                timestamp=datetime.now(),
+                duration_ms=duration_ms,
+            )
+        )

synkt-0.1.0/synkt/trace/pretty.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+from synkt.trace.models import AgentTrace
+from synkt.trace.storage import get_current_trace
+
+
+def _shorten(value: Any, max_len: int = 120) -> str:
+    text = repr(value)
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+def format_trace(
+    trace: AgentTrace | None = None,
+    *,
+    include_content: bool = False,
+    include_tools: bool = True,
+    include_summary: bool = True,
+) -> str:
+    """Return a human-readable timeline for an AgentTrace.
+
+    Args:
+        trace: Explicit trace. If omitted, uses the active trace from context.
+        include_content: Include message payload snippets.
+        include_tools: Include tool-call timeline entries.
+        include_summary: Include final summary counts and cost.
+    """
+    active_trace = trace or get_current_trace()
+    lines: list[str] = []
+
+    lines.append("Agent Trace Timeline")
+    lines.append("--------------------")
+
+    if not active_trace.messages and (not include_tools or not active_trace.tool_calls):
+        lines.append("(no events captured)")
+    else:
+        for idx, msg in enumerate(active_trace.messages, start=1):
+            ts = msg.timestamp.strftime("%H:%M:%S.%f")[:-3]
+            base = f"{idx:02d}. [{ts}] {msg.from_agent} -> {msg.to_agent}"
+            if include_content:
+                base += f" | content={_shorten(msg.content)}"
+            lines.append(base)
+
+        if include_tools and active_trace.tool_calls:
+            start_idx = len(active_trace.messages) + 1
+            for offset, tool in enumerate(active_trace.tool_calls):
+                idx = start_idx + offset
+                ts = tool.timestamp.strftime("%H:%M:%S.%f")[:-3]
+                result_label = "ok" if tool.result is not None else "no-result"
+                lines.append(
+                    f"{idx:02d}. [{ts}] {tool.agent} => tool:{tool.tool_name} "
+                    f"args={_shorten(tool.args, max_len=80)} "
+                    f"duration={tool.duration_ms:.2f}ms {result_label}"
+                )
+
+    if include_summary:
+        lines.append("")
+        lines.append("Summary")
+        lines.append("-------")
+        lines.append(f"messages: {len(active_trace.messages)}")
+        lines.append(f"tool_calls: {len(active_trace.tool_calls)}")
+        lines.append(f"duration_ms: {active_trace.duration_ms:.2f}")
+        lines.append(f"total_cost: ${active_trace.total_cost:.4f}")
+
+    return "\n".join(lines)
+
+
+def print_trace(
+    trace: AgentTrace | None = None,
+    *,
+    include_content: bool = False,
+    include_tools: bool = True,
+    include_summary: bool = True,
+) -> None:
+    """Print a formatted trace timeline to stdout."""
+    print(
+        format_trace(
+            trace,
+            include_content=include_content,
+            include_tools=include_tools,
+            include_summary=include_summary,
+        )
+    )
+

synkt-0.1.0/synkt/trace/storage.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+from synkt.trace.models import AgentTrace
+
+
+_current_trace: ContextVar[Optional[AgentTrace]] = ContextVar("_current_trace", default=None)
+
+
+def get_current_trace() -> AgentTrace:
+    """Get the trace for the current test."""
+    trace = _current_trace.get()
+    if trace is None:
+        raise RuntimeError("No active trace. Are you inside a test?")
+    return trace
+
+
+def set_current_trace(trace: AgentTrace) -> None:
+    """Set the trace for the current test."""
+    _current_trace.set(trace)
+
+
+def clear_current_trace() -> None:
+    """Clear the trace (called after test)."""
+    _current_trace.set(None)
+

synkt-0.1.0/synkt.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: synkt
+Version: 0.1.0
+Summary: Testing framework for multi-agent LLM systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"

synkt-0.1.0/synkt.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+synkt/__init__.py
+synkt/pytest_plugin.py
+synkt.egg-info/PKG-INFO
+synkt.egg-info/SOURCES.txt
+synkt.egg-info/dependency_links.txt
+synkt.egg-info/requires.txt
+synkt.egg-info/top_level.txt
+synkt/assertions/__init__.py
+synkt/assertions/coordination.py
+synkt/assertions/system.py
+synkt/assertions/tools.py
+synkt/interceptors/__init__.py
+synkt/interceptors/base.py
+synkt/interceptors/crewai.py
+synkt/interceptors/langgraph.py
+synkt/mocking/__init__.py
+synkt/mocking/mock_agent.py
+synkt/trace/__init__.py
+synkt/trace/models.py
+synkt/trace/pretty.py
+synkt/trace/storage.py
+tests/test_assertions.py
+tests/test_langgraph_interceptor.py
+tests/test_trace_models.py
+tests/test_trace_pretty.py

synkt-0.1.0/synkt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

synkt-0.1.0/synkt.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pydantic>=2.0
+
+[dev]
+pytest>=8.0
+ruff>=0.6
+black>=24.0
+
+[langgraph]
+langgraph>=0.2

synkt-0.1.0/synkt.egg-info/top_level.txt

@@ -0,0 +1 @@
+synkt

synkt-0.1.0/tests/test_assertions.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from synkt.assertions.coordination import assert_handoff, assert_parallel_execution
+from synkt.assertions.system import assert_cost_under, assert_no_loop
+from synkt.assertions.tools import assert_no_tool_called, assert_tool_called
+from synkt.trace.models import AgentTrace
+from synkt.trace.storage import set_current_trace
+
+
+class RefundRequest(BaseModel):
+    order_id: str
+
+
+def test_assert_handoff_success() -> None:
+    trace = AgentTrace()
+    trace.add_message("triage", "refunds", {"order_id": "12345"})
+    set_current_trace(trace)
+
+    assert_handoff("triage", "refunds")
+
+
+def test_assert_handoff_missing() -> None:
+    trace = AgentTrace()
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="No handoff"):
+        assert_handoff("triage", "refunds")
+
+
+def test_assert_handoff_schema_validation() -> None:
+    trace = AgentTrace()
+    trace.add_message("triage", "refunds", {"order_id": "12345"})
+    set_current_trace(trace)
+
+    assert_handoff("triage", "refunds", message_schema=RefundRequest)
+
+
+def test_assert_handoff_schema_validation_failure() -> None:
+    trace = AgentTrace()
+    trace.add_message("triage", "refunds", {"wrong": "field"})
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="doesn't match schema"):
+        assert_handoff("triage", "refunds", message_schema=RefundRequest)
+
+
+def test_assert_tool_called_success() -> None:
+    trace = AgentTrace()
+    trace.add_tool_call("refunds", "process_refund", {"order_id": "12345"})
+    set_current_trace(trace)
+
+    assert_tool_called("process_refund", args={"order_id": "12345"})
+
+
+def test_assert_tool_called_wrong_count() -> None:
+    trace = AgentTrace()
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="Expected 1 calls"):
+        assert_tool_called("process_refund")
+
+
+def test_assert_no_tool_called_success() -> None:
+    trace = AgentTrace()
+    set_current_trace(trace)
+
+    assert_no_tool_called("send_email")
+
+
+def test_assert_no_tool_called_failure() -> None:
+    trace = AgentTrace()
+    trace.add_tool_call("notifications", "send_email", {"to": "a@example.com"})
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="Expected no calls"):
+        assert_no_tool_called("send_email")
+
+
+def test_assert_no_loop_success() -> None:
+    trace = AgentTrace()
+    trace.add_message("start", "triage", {})
+    trace.add_message("triage", "refunds", {})
+    set_current_trace(trace)
+
+    assert_no_loop(max_iterations=3)
+
+
+def test_assert_no_loop_failure() -> None:
+    trace = AgentTrace()
+    for _ in range(6):
+        trace.add_message("triage", "triage", {})
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="Possible infinite loop"):
+        assert_no_loop(max_iterations=10)
+
+
+def test_assert_cost_under_success() -> None:
+    trace = AgentTrace(total_cost=0.25)
+    set_current_trace(trace)
+
+    assert_cost_under(1.00)
+
+
+def test_assert_cost_under_failure() -> None:
+    trace = AgentTrace(total_cost=1.50)
+    set_current_trace(trace)
+
+    with pytest.raises(AssertionError, match="exceeds threshold"):
+        assert_cost_under(1.00)
+
+
+def test_assert_parallel_execution_success() -> None:
+    trace = AgentTrace()
+    trace.add_message("router", "agent_a", {})
+    trace.add_message("router", "agent_b", {})
+    set_current_trace(trace)
+
+    assert_parallel_execution(["agent_a", "agent_b"], max_time_delta_ms=1000)
+

synkt-0.1.0/tests/test_langgraph_interceptor.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from synkt.interceptors.langgraph import LangGraphInterceptor
+from synkt.trace.storage import get_current_trace
+
+
+class FakeCompiledGraph:
+    def __init__(self, graph: "FakeGraph"):
+        self.graph = graph
+
+    def invoke(self, state: dict[str, Any]) -> dict[str, Any]:
+        current_state = state
+        for node_name in ["triage", "refunds"]:
+            current_state = self.graph.nodes[node_name](current_state)
+        return current_state
+
+
+class FakeGraph:
+    def __init__(self) -> None:
+        self.nodes = {
+            "triage": self._triage,
+            "refunds": self._refunds,
+        }
+
+    def _triage(self, state: dict[str, Any]) -> dict[str, Any]:
+        state["order_id"] = "12345"
+        return state
+
+    def _refunds(self, state: dict[str, Any]) -> dict[str, Any]:
+        state["resolution"] = f"Refund processed for order {state['order_id']}"
+        return state
+
+    def compile(self) -> FakeCompiledGraph:
+        return FakeCompiledGraph(self)
+
+
+def test_langgraph_interceptor_records_transitions() -> None:
+    graph = FakeGraph()
+    intercepted = LangGraphInterceptor(graph)
+
+    result = intercepted.invoke({"input": "refund please"})
+
+    assert "resolution" in result
+    trace = get_current_trace()
+    assert len(trace.messages) == 2
+    assert trace.messages[0].from_agent == "start"
+    assert trace.messages[0].to_agent == "triage"
+    assert trace.messages[1].from_agent == "triage"
+    assert trace.messages[1].to_agent == "refunds"
+

synkt-0.1.0/tests/test_trace_models.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from synkt.trace.models import AgentTrace
+
+
+def test_add_message_records_message() -> None:
+    trace = AgentTrace()
+
+    trace.add_message("triage", "refunds", {"order_id": "123"})
+
+    assert len(trace.messages) == 1
+    assert trace.messages[0].from_agent == "triage"
+    assert trace.messages[0].to_agent == "refunds"
+    assert trace.messages[0].content["order_id"] == "123"
+
+
+def test_add_tool_call_records_call() -> None:
+    trace = AgentTrace()
+
+    trace.add_tool_call(
+        agent="refunds",
+        tool_name="process_refund",
+        args={"order_id": "123"},
+        result={"ok": True},
+        duration_ms=12.5,
+    )
+
+    assert len(trace.tool_calls) == 1
+    call = trace.tool_calls[0]
+    assert call.agent == "refunds"
+    assert call.tool_name == "process_refund"
+    assert call.args["order_id"] == "123"
+    assert call.result == {"ok": True}
+    assert call.duration_ms == 12.5
+

synkt-0.1.0/tests/test_trace_pretty.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from synkt.trace.models import AgentTrace
+from synkt.trace.pretty import format_trace, print_trace
+from synkt.trace.storage import set_current_trace
+
+
+def test_format_trace_includes_messages_and_summary() -> None:
+    trace = AgentTrace(total_cost=0.1234, duration_ms=42.0)
+    trace.add_message("planner", "research", {"topic": "pricing"})
+    trace.add_tool_call(
+        agent="research",
+        tool_name="web_search",
+        args={"query": "pricing strategy"},
+        result={"hits": 3},
+        duration_ms=12.5,
+    )
+
+    output = format_trace(trace, include_content=True)
+
+    assert "Agent Trace Timeline" in output
+    assert "planner -> research" in output
+    assert "tool:web_search" in output
+    assert "messages: 1" in output
+    assert "tool_calls: 1" in output
+    assert "total_cost: $0.1234" in output
+
+
+def test_format_trace_uses_current_trace_when_not_passed() -> None:
+    trace = AgentTrace()
+    trace.add_message("start", "triage", {"input": "refund"})
+    set_current_trace(trace)
+
+    output = format_trace()
+
+    assert "start -> triage" in output
+
+
+def test_print_trace_writes_timeline(capsys) -> None:
+    trace = AgentTrace()
+    trace.add_message("a", "b", {})
+
+    print_trace(trace)
+
+    captured = capsys.readouterr()
+    assert "a -> b" in captured.out
+