agentsdk-py 0.1.0__tar.gz

agentsdk_py-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: agentsdk-py
+Version: 0.1.0
+Summary: A lightweight Python SDK for building AI agents with tools, memory, and multi-agent pipelines — powered by Groq
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vishwa0198/agentsdk
+Project-URL: Documentation, https://vishwa0198.github.io/agentsdk
+Project-URL: Repository, https://github.com/vishwa0198/agentsdk
+Project-URL: Changelog, https://github.com/vishwa0198/agentsdk/blob/main/CHANGELOG.md
+Keywords: ai,agents,llm,groq,sdk,multi-agent,react-agent,tool-use
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: groq>=0.9
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.24; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+
+# agentsdk
+
+A lightweight Python SDK for building AI agents with tool use, multi-agent graphs, persistence, and tracing.
+
+## Install
+
+```bash
+pip install agentsdk          # core
+pip install agentsdk[otel]    # + OpenTelemetry tracing
+pip install agentsdk[dev]     # + pytest / dotenv
+```
+
+## Quickstart
+
+```python
+import asyncio, os
+from agentsdk import Agent, AgentConfig, GroqProvider
+
+agent = Agent(
+    config=AgentConfig(
+        name="MyAgent",
+        system_prompt="You are a helpful assistant.",
+    ),
+    llm=GroqProvider(api_key=os.environ["GROQ_API_KEY"]),
+)
+
+async def main():
+    result = await agent.run("What is the capital of France?")
+    print(result.output)
+
+asyncio.run(main())
+```
+
+## Tools
+
+```python
+from agentsdk import tool, ToolRegistry, Agent, AgentConfig, GroqProvider
+
+@tool
+async def add(a: int, b: int) -> str:
+    """Add two integers."""
+    return str(a + b)
+
+registry = ToolRegistry()
+registry.register(add)
+
+agent = Agent(config=AgentConfig(name="Calc", system_prompt="Use tools."),
+              llm=GroqProvider(...), registry=registry)
+```
+
+## Multi-agent Graph
+
+```python
+from agentsdk import AgentNode, Edge, AgentGraph, GraphRunner
+
+graph = AgentGraph()
+graph.add_node(AgentNode("researcher", researcher_agent))
+graph.add_node(AgentNode("writer", writer_agent))
+graph.add_edge(Edge("researcher", "writer", data_map={"output": "input"}))
+graph.set_entry("researcher"); graph.set_exit("writer")
+result = await GraphRunner(graph).run({"input": "Explain black holes"})
+```
+
+## Persistence
+
+```python
+from agentsdk import FileCheckpointStore, SessionManager, Agent
+
+store = FileCheckpointStore(base_dir=".agentsdk/checkpoints")
+session_mgr = SessionManager(store=store, agent_name="MyAgent")
+agent = Agent(config=..., llm=..., session_manager=session_mgr)
+
+# History is saved and reloaded automatically across runs:
+await agent.run("My favourite language is Python.", session_id="user-001")
+await agent.run("What language did I mention?",     session_id="user-001")
+
+# Fork a session to branch an agent run:
+forked = await session_mgr.fork("user-001", "user-001-branch")
+```
+
+## Tracing (requires `agentsdk[otel]`)
+
+```python
+from agentsdk.observability import SDKTracer, TracedLLMProvider, TracedAgent, print_trace
+
+tracer     = SDKTracer(service_name="myapp")
+traced_llm = TracedLLMProvider(provider=GroqProvider(...), tracer=tracer)
+agent      = TracedAgent(config=..., llm=traced_llm, tracer=tracer)
+
+result, ctx = await agent.run("Summarise the last quarter earnings.")
+print_trace(ctx)
+# ╔══ Trace: MyAgent ══════════════════════
+# ║  Session     : (none)
+# ║  Trace ID    : 6744d6eca33853c5bba0...
+# ║  Duration    : 3680ms
+# ║  LLM calls   : 2
+# ║  Tool calls  : 1
+# ║  Tokens      : 1292 in / 36 out
+# ╚═════════════════════════════════════════
+```
+
+## CLI
+
+```bash
+# Scaffold a new agent project
+scaffold-agent new myproject
+
+# Interactive REPL against any agent file
+scaffold-agent run myproject/agents/main.py
+
+# Inspect a saved checkpoint
+scaffold-agent trace .agentsdk/checkpoints/MyAgent/user-001.json
+
+# List all sessions for an agent
+scaffold-agent list-sessions MyAgent
+```

agentsdk_py-0.1.0/README.md

@@ -0,0 +1,116 @@
+# agentsdk
+
+A lightweight Python SDK for building AI agents with tool use, multi-agent graphs, persistence, and tracing.
+
+## Install
+
+```bash
+pip install agentsdk          # core
+pip install agentsdk[otel]    # + OpenTelemetry tracing
+pip install agentsdk[dev]     # + pytest / dotenv
+```
+
+## Quickstart
+
+```python
+import asyncio, os
+from agentsdk import Agent, AgentConfig, GroqProvider
+
+agent = Agent(
+    config=AgentConfig(
+        name="MyAgent",
+        system_prompt="You are a helpful assistant.",
+    ),
+    llm=GroqProvider(api_key=os.environ["GROQ_API_KEY"]),
+)
+
+async def main():
+    result = await agent.run("What is the capital of France?")
+    print(result.output)
+
+asyncio.run(main())
+```
+
+## Tools
+
+```python
+from agentsdk import tool, ToolRegistry, Agent, AgentConfig, GroqProvider
+
+@tool
+async def add(a: int, b: int) -> str:
+    """Add two integers."""
+    return str(a + b)
+
+registry = ToolRegistry()
+registry.register(add)
+
+agent = Agent(config=AgentConfig(name="Calc", system_prompt="Use tools."),
+              llm=GroqProvider(...), registry=registry)
+```
+
+## Multi-agent Graph
+
+```python
+from agentsdk import AgentNode, Edge, AgentGraph, GraphRunner
+
+graph = AgentGraph()
+graph.add_node(AgentNode("researcher", researcher_agent))
+graph.add_node(AgentNode("writer", writer_agent))
+graph.add_edge(Edge("researcher", "writer", data_map={"output": "input"}))
+graph.set_entry("researcher"); graph.set_exit("writer")
+result = await GraphRunner(graph).run({"input": "Explain black holes"})
+```
+
+## Persistence
+
+```python
+from agentsdk import FileCheckpointStore, SessionManager, Agent
+
+store = FileCheckpointStore(base_dir=".agentsdk/checkpoints")
+session_mgr = SessionManager(store=store, agent_name="MyAgent")
+agent = Agent(config=..., llm=..., session_manager=session_mgr)
+
+# History is saved and reloaded automatically across runs:
+await agent.run("My favourite language is Python.", session_id="user-001")
+await agent.run("What language did I mention?",     session_id="user-001")
+
+# Fork a session to branch an agent run:
+forked = await session_mgr.fork("user-001", "user-001-branch")
+```
+
+## Tracing (requires `agentsdk[otel]`)
+
+```python
+from agentsdk.observability import SDKTracer, TracedLLMProvider, TracedAgent, print_trace
+
+tracer     = SDKTracer(service_name="myapp")
+traced_llm = TracedLLMProvider(provider=GroqProvider(...), tracer=tracer)
+agent      = TracedAgent(config=..., llm=traced_llm, tracer=tracer)
+
+result, ctx = await agent.run("Summarise the last quarter earnings.")
+print_trace(ctx)
+# ╔══ Trace: MyAgent ══════════════════════
+# ║  Session     : (none)
+# ║  Trace ID    : 6744d6eca33853c5bba0...
+# ║  Duration    : 3680ms
+# ║  LLM calls   : 2
+# ║  Tool calls  : 1
+# ║  Tokens      : 1292 in / 36 out
+# ╚═════════════════════════════════════════
+```
+
+## CLI
+
+```bash
+# Scaffold a new agent project
+scaffold-agent new myproject
+
+# Interactive REPL against any agent file
+scaffold-agent run myproject/agents/main.py
+
+# Inspect a saved checkpoint
+scaffold-agent trace .agentsdk/checkpoints/MyAgent/user-001.json
+
+# List all sessions for an agent
+scaffold-agent list-sessions MyAgent
+```

agentsdk_py-0.1.0/agentsdk/__init__.py

@@ -0,0 +1,41 @@
+"""agentsdk — A lightweight Python SDK for building AI agents."""
+
+from agentsdk.agent import Agent, AgentConfig, AgentResult
+from agentsdk.messages import (
+    MessageHistory,
+    HumanMessage,
+    AIMessage,
+    SystemMessage,
+    ToolResultMessage,
+)
+from agentsdk.llm import GroqProvider, LLMResponse
+from agentsdk.tools.base import tool, BaseTool
+from agentsdk.tools.registry import ToolRegistry
+from agentsdk.tools.builtin import DEFAULT_TOOLS
+from agentsdk.graph.node import AgentNode, Edge
+from agentsdk.graph.graph import AgentGraph
+from agentsdk.graph.runner import GraphRunner
+from agentsdk.graph.bus import MessageBus, BusAwareAgent, BusRunner
+from agentsdk.persistence.file_store import FileCheckpointStore
+from agentsdk.persistence.session import SessionManager
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core agent
+    "Agent", "AgentConfig", "AgentResult",
+    # Messages
+    "MessageHistory", "HumanMessage", "AIMessage", "SystemMessage", "ToolResultMessage",
+    # LLM
+    "GroqProvider", "LLMResponse",
+    # Tools
+    "tool", "BaseTool", "ToolRegistry", "DEFAULT_TOOLS",
+    # Graph
+    "AgentNode", "Edge", "AgentGraph", "GraphRunner",
+    # Bus
+    "MessageBus", "BusAwareAgent", "BusRunner",
+    # Persistence
+    "FileCheckpointStore", "SessionManager",
+    # Meta
+    "__version__",
+]

agentsdk_py-0.1.0/agentsdk/agent.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+from pydantic import BaseModel, ConfigDict
+from agentsdk.llm import LLMProvider, ToolSchema
+from agentsdk.messages import AIMessage, Memory, MessageHistory, ToolCall
+from agentsdk.tools.base import BaseTool
+from agentsdk.tools.registry import ToolRegistry
+
+if TYPE_CHECKING:
+    from agentsdk.persistence.session import SessionManager
+
+
+# ---------------------------------------------------------------------------
+# AgentConfig
+# ---------------------------------------------------------------------------
+
+
+class AgentConfig(BaseModel):
+    """Immutable configuration for an Agent instance.
+
+    Attributes:
+        name: Human-readable agent name used in verbose output and tracing.
+        system_prompt: Injected as the first SystemMessage for every new session.
+        max_iterations: Hard stop preventing infinite tool-call loops. Default 10.
+        max_tokens: Forwarded to LLMProvider.complete() on every call. Default 1024.
+        tools_enabled: When False, tool schemas are withheld even if registered.
+        verbose: Print each iteration's thought and tool calls to stdout.
+
+    Example::
+
+        config = AgentConfig(
+            name="MyAgent",
+            system_prompt="You are a helpful assistant.",
+            max_iterations=5,
+            verbose=True,
+        )
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    """Human-readable agent name (used in verbose output and tracing)."""
+
+    system_prompt: str
+    """Injected as the first SystemMessage for every new session."""
+
+    max_iterations: int = 10
+    """Hard stop — prevents infinite tool-call loops."""
+
+    max_tokens: int = 1024
+    """Forwarded to LLMProvider.complete() on every call."""
+
+    tools_enabled: bool = True
+    """When False, tool schemas are withheld from the LLM even if tools are registered."""
+
+    verbose: bool = False
+    """Print each iteration's thought and tool calls to stdout (dev convenience)."""
+
+
+# ---------------------------------------------------------------------------
+# StepResult
+# ---------------------------------------------------------------------------
+
+
+class StepResult(BaseModel):
+    """Snapshot of one ReAct iteration."""
+
+    model_config = ConfigDict(frozen=True)
+
+    iteration: int
+    thought: str
+    """Raw content of the AIMessage produced this step."""
+
+    tool_calls: list[ToolCall]
+    """Tool calls the model requested this step (empty if none)."""
+
+    stop_reason: str
+    """Forwarded from LLMResponse.stop_reason."""
+
+    is_final: bool
+    """True when this step caused the loop to terminate cleanly."""
+
+
+# ---------------------------------------------------------------------------
+# AgentResult
+# ---------------------------------------------------------------------------
+
+
+class AgentResult(BaseModel):
+    """Full output of a single Agent.run() invocation."""
+
+    model_config = ConfigDict(frozen=True)
+
+    output: str
+    """Final assistant message content."""
+
+    steps: list[StepResult]
+    """Ordered trace of every ReAct iteration."""
+
+    total_input_tokens: int
+    total_output_tokens: int
+
+    stopped_by: str
+    """Why the loop ended: ``end_turn`` | ``max_iterations`` | ``error``."""
+
+
+# ---------------------------------------------------------------------------
+# Agent
+# ---------------------------------------------------------------------------
+
+
+class Agent:
+    """Runs a ReAct agent loop using an LLM provider and optional tools.
+
+    Args:
+        config: AgentConfig with name, system prompt, and settings.
+        llm: Any LLMProvider implementation — use GroqProvider.
+        tools: Optional flat list of BaseTool instances.
+        memory: Optional Memory backend (legacy; prefer session_manager).
+        registry: Optional ToolRegistry — merged with tools if both provided.
+        session_manager: Optional SessionManager for persistent sessions.
+
+    Example::
+
+        llm = GroqProvider(api_key="...")
+        config = AgentConfig(name="MyAgent", system_prompt="You are helpful.")
+        agent = Agent(config=config, llm=llm)
+        result = await agent.run("What is 2 + 2?")
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        llm: LLMProvider,
+        tools: list[BaseTool] | None = None,
+        memory: Memory | None = None,
+        registry: ToolRegistry | None = None,
+        session_manager: SessionManager | None = None,
+    ) -> None:
+        self.config = config
+        self._llm = llm
+        self._memory = memory
+        self._session_manager = session_manager
+        self._tools: list[BaseTool] = list(tools or [])
+        if registry is not None:
+            self._tools.extend(registry.all())
+        # O(1) lookup by tool name during dispatch
+        self._tool_map: dict[str, BaseTool] = {t.schema.name: t for t in self._tools}
+
+    # ------------------------------------------------------------------
+    # Core run loop
+    # ------------------------------------------------------------------
+
+    async def run(
+        self,
+        user_input: str,
+        session_id: str | None = None,
+    ) -> AgentResult:
+        """Execute the ReAct loop for *user_input* and return a full trace.
+
+        Parameters
+        ----------
+        user_input:
+            The human message that starts this turn.
+        session_id:
+            When provided alongside a ``Memory`` backend, the conversation
+            is loaded before running and persisted afterwards.
+        """
+        # ── 1. Load or create history ──────────────────────────────────────
+        if self._session_manager and session_id:
+            history = await self._session_manager.load_history(session_id)
+        elif self._memory and session_id:
+            history = await self._memory.load(session_id)
+        else:
+            history = MessageHistory()
+
+        # Inject system prompt only for brand-new sessions.
+        if len(history) == 0:
+            history.add_system(self.config.system_prompt)
+
+        # Extension point: subclasses (e.g. BusAwareAgent) inject context here.
+        await self._pre_run_hook(history)
+
+        history.add_human(user_input)
+
+        # ── 2. Prepare tool schemas ────────────────────────────────────────
+        tool_schemas: list[ToolSchema] | None = None
+        if self.config.tools_enabled and self._tools:
+            tool_schemas = [t.schema for t in self._tools]
+
+        # ── 3. ReAct loop ──────────────────────────────────────────────────
+        steps: list[StepResult] = []
+        total_input = 0
+        total_output = 0
+        stopped_by = "max_iterations"
+        output = ""
+
+        try:
+            for iteration in range(1, self.config.max_iterations + 1):
+                response = await self._llm.complete(
+                    history,
+                    tools=tool_schemas,
+                    max_tokens=self.config.max_tokens,
+                )
+
+                total_input += response.input_tokens
+                total_output += response.output_tokens
+
+                ai_message: AIMessage = response.message
+                history.add(ai_message)
+
+                has_tool_calls = bool(ai_message.tool_calls)
+                is_final = response.stop_reason == "end_turn" and not has_tool_calls
+
+                step = StepResult(
+                    iteration=iteration,
+                    thought=ai_message.content,
+                    tool_calls=list(ai_message.tool_calls),
+                    stop_reason=response.stop_reason,
+                    is_final=is_final,
+                )
+                steps.append(step)
+
+                if self.config.verbose:
+                    snippet = ai_message.content[:120].replace("\n", " ")
+                    print(
+                        f"[{self.config.name}] iter={iteration}"
+                        f" stop={response.stop_reason}"
+                        f" thought={snippet!r}"
+                    )
+                    for tc in ai_message.tool_calls:
+                        print(f"  → tool_call: {tc.name}({tc.arguments})")
+
+                # ── clean exit ─────────────────────────────────────────────
+                if is_final:
+                    output = ai_message.content
+                    stopped_by = "end_turn"
+                    break
+
+                # ── tool dispatch ──────────────────────────────────────────
+                if has_tool_calls:
+                    for tc in ai_message.tool_calls:
+                        result_content, is_error = await self._dispatch_tool(tc)
+
+                        if self.config.verbose:
+                            status = "ERROR" if is_error else "OK"
+                            print(f"  ← tool_result [{status}]: {result_content[:120]!r}")
+
+                        history.add_tool_result(
+                            tool_call_id=tc.id,
+                            content=result_content,
+                            is_error=is_error,
+                        )
+
+                # If stop_reason is "max_tokens" or another non-final reason
+                # with no tool calls, the loop continues to let the model
+                # recover in the next iteration.
+
+        except Exception as exc:
+            stopped_by = "error"
+            output = str(exc)
+            if self.config.verbose:
+                print(f"[{self.config.name}] ERROR: {exc}")
+
+        # Grab the last thought as output when the loop was exhausted.
+        if stopped_by == "max_iterations" and steps:
+            output = steps[-1].thought
+
+        # ── 4. Persist history ─────────────────────────────────────────────
+        if self._session_manager and session_id:
+            await self._session_manager.save_history(
+                session_id,
+                history,
+                iteration=len(steps),
+                metadata={"stopped_by": stopped_by},
+            )
+        elif self._memory and session_id:
+            await self._memory.save(session_id, history)
+
+        return AgentResult(
+            output=output,
+            steps=steps,
+            total_input_tokens=total_input,
+            total_output_tokens=total_output,
+            stopped_by=stopped_by,
+        )
+
+    # ------------------------------------------------------------------
+    # Convenience wrapper
+    # ------------------------------------------------------------------
+
+    async def chat(self, user_input: str, session_id: str = "default") -> str:
+        """Single-call interface — returns just the final response string."""
+        result = await self.run(user_input, session_id)
+        return result.output
+
+    # ------------------------------------------------------------------
+    # Extension hooks
+    # ------------------------------------------------------------------
+
+    async def _pre_run_hook(self, history: MessageHistory) -> None:
+        """Called after system-prompt injection, before the user message is added.
+
+        Override in subclasses to inject additional context into *history*
+        before the ReAct loop starts.  The base implementation is a no-op.
+        """
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _dispatch_tool(self, tc: ToolCall) -> tuple[str, bool]:
+        """Execute one tool call and return (result_content, is_error)."""
+        tool = self._tool_map.get(tc.name)
+        if tool is None:
+            return f"Tool not found: {tc.name}", True
+        try:
+            content = await tool.execute(**tc.arguments)
+            return content, False
+        except Exception as exc:  # noqa: BLE001
+            return str(exc), True