agentspan 0.0.3__py3-none-any.whl

agentspan/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+

agentspan/agents/__init__.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+
+"""Conductor Agents SDK — durable, scalable, observable AI agents.
+
+This is the public API surface.  Import everything you need from here::
+
+    from agentspan.agents import Agent, AgentRuntime, tool
+
+Quick start::
+
+    from agentspan.agents import Agent, AgentRuntime, tool
+
+    @tool
+    def get_weather(city: str) -> str:
+        \"\"\"Get current weather for a city.\"\"\"
+        return f"72F and sunny in {city}"
+
+    agent = Agent(name="weatherbot", model="openai/gpt-4o", tools=[get_weather])
+
+    with AgentRuntime() as runtime:
+        result = runtime.run(agent, "What's the weather in NYC?")
+        print(result.output)
+"""
+
+# Core primitive
+from agentspan.agents.agent import Agent, AgentDef, PromptTemplate, Strategy, agent
+
+# Tool decorator and constructors
+from agentspan.agents.tool import (
+    ToolContext,
+    ToolDef,
+    agent_tool,
+    audio_tool,
+    http_tool,
+    image_tool,
+    mcp_tool,
+    pdf_tool,
+    tool,
+    video_tool,
+)
+
+# MCP discovery utilities
+from agentspan.agents.runtime.mcp_discovery import clear_discovery_cache
+
+# Execution API
+from agentspan.agents.run import (
+    plan,
+    run,
+    run_async,
+    shutdown,
+    start,
+    start_async,
+    stream,
+    stream_async,
+)
+
+# Runtime (for context manager and advanced usage)
+from agentspan.agents.runtime.config import AgentConfig
+from agentspan.agents.runtime.runtime import AgentRuntime
+
+# Result types
+from agentspan.agents.result import (
+    AgentEvent,
+    AgentHandle,
+    AgentResult,
+    AgentStatus,
+    AgentStream,
+    AsyncAgentStream,
+    EventType,
+    TokenUsage,
+)
+
+# Guardrails
+from agentspan.agents.guardrail import (
+    Guardrail,
+    GuardrailDef,
+    GuardrailResult,
+    LLMGuardrail,
+    OnFail,
+    Position,
+    RegexGuardrail,
+    guardrail,
+)
+
+# Termination conditions
+from agentspan.agents.termination import (
+    MaxMessageTermination,
+    StopMessageTermination,
+    TerminationCondition,
+    TerminationResult,
+    TextMentionTermination,
+    TokenUsageTermination,
+)
+
+# Memory
+from agentspan.agents.memory import ConversationMemory
+from agentspan.agents.semantic_memory import MemoryEntry, MemoryStore, SemanticMemory
+
+# Code execution
+from agentspan.agents.code_execution_config import CodeExecutionConfig
+from agentspan.agents.code_executor import (
+    CodeExecutor,
+    DockerCodeExecutor,
+    ExecutionResult,
+    JupyterCodeExecutor,
+    LocalCodeExecutor,
+    ServerlessCodeExecutor,
+)
+
+# Handoff conditions (for swarm strategy)
+from agentspan.agents.handoff import HandoffCondition, OnCondition, OnTextMention, OnToolResult
+
+# Extended agent types
+from agentspan.agents.ext import GPTAssistantAgent, UserProxyAgent
+
+# Tracing (optional — only activates if opentelemetry is installed)
+from agentspan.agents.tracing import is_tracing_enabled
+
+__all__ = [
+    # Core
+    "Agent",
+    "AgentDef",
+    "PromptTemplate",
+    "Strategy",
+    "agent",
+    "AgentRuntime",
+    "AgentConfig",
+    # Extended agent types
+    "UserProxyAgent",
+    "GPTAssistantAgent",
+    # Tools
+    "tool",
+    "ToolDef",
+    "ToolContext",
+    "agent_tool",
+    "http_tool",
+    "mcp_tool",
+    "image_tool",
+    "audio_tool",
+    "video_tool",
+    "pdf_tool",
+    "clear_discovery_cache",
+    # Convenience execution (uses a singleton AgentRuntime)
+    "plan",
+    "run",
+    "run_async",
+    "shutdown",
+    "start",
+    "start_async",
+    "stream",
+    "stream_async",
+    # Results
+    "AgentResult",
+    "AgentHandle",
+    "AgentStatus",
+    "AgentStream",
+    "AsyncAgentStream",
+    "AgentEvent",
+    "EventType",
+    "TokenUsage",
+    # Guardrails
+    "guardrail",
+    "Guardrail",
+    "GuardrailDef",
+    "GuardrailResult",
+    "OnFail",
+    "Position",
+    "RegexGuardrail",
+    "LLMGuardrail",
+    # Termination conditions
+    "TerminationCondition",
+    "TerminationResult",
+    "TextMentionTermination",
+    "StopMessageTermination",
+    "MaxMessageTermination",
+    "TokenUsageTermination",
+    # Memory
+    "ConversationMemory",
+    "SemanticMemory",
+    "MemoryStore",
+    "MemoryEntry",
+    # Code execution
+    "CodeExecutionConfig",
+    "CodeExecutor",
+    "LocalCodeExecutor",
+    "DockerCodeExecutor",
+    "JupyterCodeExecutor",
+    "ServerlessCodeExecutor",
+    "ExecutionResult",
+    # Handoff conditions
+    "HandoffCondition",
+    "OnToolResult",
+    "OnTextMention",
+    "OnCondition",
+    # Tracing
+    "is_tracing_enabled",
+]

agentspan/agents/_internal/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+
+# Private utilities — not part of the public API.

agentspan/agents/_internal/model_parser.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+
+"""Parse ``"provider/model"`` strings into (provider, model) tuples.
+
+Conductor's :class:`LlmChatComplete` requires separate ``llm_provider`` and
+``model`` arguments.  This module handles the unified format used by the
+agents SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+# Known Conductor LLM provider names.
+KNOWN_PROVIDERS = frozenset({
+    "openai",
+    "azure_openai",
+    "anthropic",
+    "google_gemini",
+    "google_vertex_ai",
+    "aws_bedrock",
+    "cohere",
+    "mistral",
+    "groq",
+    "perplexity",
+    "hugging_face",
+    "deepseek",
+})
+
+
+@dataclass(frozen=True)
+class ParsedModel:
+    """Result of parsing a ``"provider/model"`` string.
+
+    Attributes:
+        provider: The Conductor integration name (e.g. ``"openai"``).
+        model: The model identifier (e.g. ``"gpt-4o"``).
+    """
+
+    provider: str
+    model: str
+
+
+def parse_model(model_string: str) -> ParsedModel:
+    """Parse a ``"provider/model"`` string.
+
+    Args:
+        model_string: A string in ``"provider/model"`` format, e.g.
+            ``"openai/gpt-4o"`` or ``"anthropic/claude-sonnet-4-20250514"``.
+
+    Returns:
+        A :class:`ParsedModel` with separate ``provider`` and ``model`` fields.
+
+    Raises:
+        ValueError: If the string is not in the expected format.
+
+    Examples::
+
+        >>> parse_model("openai/gpt-4o")
+        ParsedModel(provider='openai', model='gpt-4o')
+
+        >>> parse_model("anthropic/claude-sonnet-4-20250514")
+        ParsedModel(provider='anthropic', model='claude-sonnet-4-20250514')
+
+        >>> parse_model("azure_openai/gpt-4o")
+        ParsedModel(provider='azure_openai', model='gpt-4o')
+    """
+    if "/" not in model_string:
+        raise ValueError(
+            f"Invalid model format {model_string!r}. "
+            "Expected 'provider/model' (e.g. 'openai/gpt-4o')"
+        )
+
+    parts = model_string.split("/", 1)
+    provider = parts[0].strip()
+    model = parts[1].strip()
+
+    if not provider:
+        raise ValueError(f"Empty provider in model string {model_string!r}")
+    if not model:
+        raise ValueError(f"Empty model name in model string {model_string!r}")
+
+    return ParsedModel(provider=provider, model=model)

agentspan/agents/_internal/provider_registry.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+
+"""Provider registry — metadata for auto-registering LLM integrations.
+
+Maps known LLM provider names (as used in ``"provider/model"`` strings) to the
+configuration required to create integrations on the Conductor server.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    """Metadata for an LLM provider integration.
+
+    Attributes:
+        name: SDK provider name (matches :data:`model_parser.KNOWN_PROVIDERS`).
+        integration_type: Conductor server ``type`` field for the integration.
+        display_name: Human-readable provider name.
+        api_key_env: Environment variable that holds the provider's API key.
+    """
+
+    name: str
+    integration_type: str
+    display_name: str
+    api_key_env: str
+
+
+PROVIDER_REGISTRY: Dict[str, ProviderSpec] = {
+    "openai": ProviderSpec(
+        name="openai",
+        integration_type="openai",
+        display_name="OpenAI",
+        api_key_env="OPENAI_API_KEY",
+    ),
+    "anthropic": ProviderSpec(
+        name="anthropic",
+        integration_type="anthropic",
+        display_name="Anthropic",
+        api_key_env="ANTHROPIC_API_KEY",
+    ),
+    "google_gemini": ProviderSpec(
+        name="google_gemini",
+        integration_type="google_gemini",
+        display_name="Google Gemini",
+        api_key_env="GOOGLE_GEMINI_API_KEY",
+    ),
+}
+
+
+def get_provider_spec(provider_name: str) -> Optional[ProviderSpec]:
+    """Look up a provider spec by name.
+
+    Returns ``None`` if the provider is not in the registry.
+    """
+    return PROVIDER_REGISTRY.get(provider_name)

agentspan/agents/_internal/schema_utils.py

@@ -0,0 +1,141 @@
+# Copyright (c) 2025 AgentSpan
+# Licensed under the MIT License. See LICENSE file in the project root for details.
+
+"""JSON Schema generation from Python type hints, Pydantic models, and dataclasses.
+
+Wraps ``conductor.client.automator.json_schema_generator`` and adds support
+for Pydantic ``BaseModel`` classes.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Dict, Optional, get_type_hints
+
+
+# ── Type-hint → JSON Schema mapping ────────────────────────────────────
+
+_PYTHON_TYPE_TO_JSON = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+    list: {"type": "array"},
+    dict: {"type": "object"},
+    type(None): {"type": "null"},
+}
+
+
+def _type_to_json_schema(annotation: Any) -> Dict[str, Any]:
+    """Convert a Python type annotation to a JSON Schema fragment."""
+    if annotation is inspect.Parameter.empty or annotation is Any:
+        return {}
+
+    # Direct mapping
+    if annotation in _PYTHON_TYPE_TO_JSON:
+        return dict(_PYTHON_TYPE_TO_JSON[annotation])
+
+    # Handle Optional[X] (Union[X, None])
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", ())
+
+    if origin is type(None):
+        return {"type": "null"}
+
+    # Union types (including Optional)
+    import typing
+    if origin is getattr(typing, "Union", None):
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _type_to_json_schema(non_none[0])
+        return {}
+
+    # List[X]
+    if origin is list:
+        schema: Dict[str, Any] = {"type": "array"}
+        if args:
+            schema["items"] = _type_to_json_schema(args[0])
+        return schema
+
+    # Dict[str, X]
+    if origin is dict:
+        schema = {"type": "object"}
+        if len(args) >= 2:
+            schema["additionalProperties"] = _type_to_json_schema(args[1])
+        return schema
+
+    return {}
+
+
+# ── Function → JSON Schema ─────────────────────────────────────────────
+
+def schema_from_function(func: Callable[..., Any]) -> Dict[str, Any]:
+    """Generate input/output JSON Schemas from a Python function's signature.
+
+    Uses type hints and docstring to produce schemas compatible with
+    Conductor's ``ToolSpec.input_schema``.
+
+    Args:
+        func: The function to analyse.
+
+    Returns:
+        A dict with ``"input"`` and ``"output"`` keys, each containing a
+        JSON Schema dict.
+    """
+    sig = inspect.signature(func)
+    try:
+        hints = get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    # Build input schema
+    properties: Dict[str, Any] = {}
+    required: list[str] = []
+
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls", "context"):
+            continue
+
+        prop = _type_to_json_schema(hints.get(name, param.annotation))
+        if not prop:
+            prop = {}
+
+        # Use docstring for parameter descriptions (simple extraction)
+        properties[name] = prop
+
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+
+    input_schema: Dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        input_schema["required"] = required
+
+    # Build output schema
+    return_type = hints.get("return", sig.return_annotation)
+    output_schema = _type_to_json_schema(return_type) if return_type is not inspect.Parameter.empty else {}
+
+    return {"input": input_schema, "output": output_schema}
+
+
+def schema_from_pydantic(model_class: type) -> Dict[str, Any]:
+    """Generate a JSON Schema from a Pydantic ``BaseModel`` class.
+
+    Args:
+        model_class: A Pydantic ``BaseModel`` subclass.
+
+    Returns:
+        The JSON Schema dict produced by Pydantic's ``model_json_schema()``.
+
+    Raises:
+        TypeError: If *model_class* is not a Pydantic ``BaseModel``.
+    """
+    if hasattr(model_class, "model_json_schema"):
+        # Pydantic v2
+        return model_class.model_json_schema()
+    elif hasattr(model_class, "schema"):
+        # Pydantic v1
+        return model_class.schema()
+    raise TypeError(f"{model_class} is not a Pydantic BaseModel")