ai-agent-scope 0.2.0__tar.gz

ai_agent_scope-0.2.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: ai-agent-scope
+Version: 0.2.0
+Summary: Agent debugging and observability platform - SDK
+Home-page: https://github.com/shenchengtsi/agent-scope
+Author: AgentScope Team
+Author-email: agentscope@example.com
+Project-URL: Bug Reports, https://github.com/shenchengtsi/agent-scope/issues
+Project-URL: Source, https://github.com/shenchengtsi/agent-scope
+Project-URL: Documentation, https://github.com/shenchengtsi/agent-scope/blob/main/docs/
+Keywords: agent,debugging,observability,monitoring,llm,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# AgentScope SDK
+
+Python SDK for AgentScope - Agent debugging and observability platform.
+
+## Installation
+
+```bash
+pip install agentscope
+```
+
+## Quick Start
+
+```python
+from agentscope import trace, init_monitor
+
+# Initialize monitoring
+init_monitor("http://localhost:8000")
+
+@trace(name="my_agent")
+def my_agent(query: str):
+    # Your agent logic here
+    return f"Result for: {query}"
+
+# Run your agent
+result = my_agent("What is AI?")
+```
+
+## Features
+
+- **Zero-intrusion**: Just add `@trace` decorator
+- **Real-time monitoring**: WebSocket-based live updates
+- **Execution tracing**: Full chain of thought visualization
+- **Tool call tracking**: Debug function calling issues
+- **Token & latency metrics**: Performance monitoring

ai_agent_scope-0.2.0/README.md

@@ -0,0 +1,34 @@
+# AgentScope SDK
+
+Python SDK for AgentScope - Agent debugging and observability platform.
+
+## Installation
+
+```bash
+pip install agentscope
+```
+
+## Quick Start
+
+```python
+from agentscope import trace, init_monitor
+
+# Initialize monitoring
+init_monitor("http://localhost:8000")
+
+@trace(name="my_agent")
+def my_agent(query: str):
+    # Your agent logic here
+    return f"Result for: {query}"
+
+# Run your agent
+result = my_agent("What is AI?")
+```
+
+## Features
+
+- **Zero-intrusion**: Just add `@trace` decorator
+- **Real-time monitoring**: WebSocket-based live updates
+- **Execution tracing**: Full chain of thought visualization
+- **Tool call tracking**: Debug function calling issues
+- **Token & latency metrics**: Performance monitoring

ai_agent_scope-0.2.0/agentscope/__init__.py

@@ -0,0 +1,43 @@
+"""AgentScope - Agent debugging and observability platform."""
+
+from .monitor import (
+    init_monitor,
+    trace,
+    trace_scope,
+    instrument_llm,
+    instrument_openai,
+    instrumented_tool,
+    get_current_trace,
+    add_step,
+    add_llm_call,
+    add_tool_call,
+    add_thinking,
+    add_memory,
+)
+from .models import TraceEvent, ExecutionStep, ToolCall, StepType, Status
+
+__version__ = "0.2.0"
+__all__ = [
+    # Core initialization
+    "init_monitor",
+    # Tracing APIs
+    "trace",
+    "trace_scope",
+    # Auto-instrumentation
+    "instrument_llm",
+    "instrument_openai",
+    "instrumented_tool",
+    # Utilities
+    "get_current_trace",
+    "add_step",
+    "add_llm_call",
+    "add_tool_call",
+    "add_thinking",
+    "add_memory",
+    # Models
+    "TraceEvent",
+    "ExecutionStep",
+    "ToolCall",
+    "StepType",
+    "Status",
+]

ai_agent_scope-0.2.0/agentscope/models.py

@@ -0,0 +1,126 @@
+"""Data models for AgentScope."""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional, List, Dict
+from datetime import datetime
+from enum import Enum
+import uuid
+import json
+
+
+class StepType(str, Enum):
+    """Types of execution steps."""
+    INPUT = "input"
+    LLM_CALL = "llm_call"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    OUTPUT = "output"
+    ERROR = "error"
+    THINKING = "thinking"
+
+
+class Status(str, Enum):
+    """Execution status."""
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    ERROR = "error"
+
+
+@dataclass
+class ToolCall:
+    """Represents a tool/function call."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    name: str = ""
+    arguments: Dict[str, Any] = field(default_factory=dict)
+    result: Any = None
+    error: Optional[str] = None
+    latency_ms: float = 0.0
+
+    def to_dict(self) -> Dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "arguments": self.arguments,
+            "result": self.result,
+            "error": self.error,
+            "latency_ms": self.latency_ms,
+        }
+
+
+@dataclass
+class ExecutionStep:
+    """A single step in the execution chain."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    type: StepType = StepType.INPUT
+    content: str = ""
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    tokens_input: int = 0
+    tokens_output: int = 0
+    latency_ms: float = 0.0
+    tool_call: Optional[ToolCall] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    status: Status = Status.PENDING
+
+    def to_dict(self) -> Dict:
+        return {
+            "id": self.id,
+            "type": self.type.value,
+            "content": self.content,
+            "timestamp": self.timestamp.isoformat(),
+            "tokens_input": self.tokens_input,
+            "tokens_output": self.tokens_output,
+            "latency_ms": self.latency_ms,
+            "tool_call": self.tool_call.to_dict() if self.tool_call else None,
+            "metadata": self.metadata,
+            "status": self.status.value,
+        }
+
+
+@dataclass
+class TraceEvent:
+    """A complete trace of an Agent execution."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    name: str = ""
+    tags: List[str] = field(default_factory=list)
+    start_time: datetime = field(default_factory=datetime.utcnow)
+    end_time: Optional[datetime] = None
+    steps: List[ExecutionStep] = field(default_factory=list)
+    status: Status = Status.PENDING
+    total_tokens: int = 0
+    total_latency_ms: float = 0.0
+    input_query: str = ""
+    output_result: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def add_step(self, step: ExecutionStep):
+        """Add a step to the trace."""
+        self.steps.append(step)
+        self.total_tokens += step.tokens_input + step.tokens_output
+
+    def finish(self, status: Status = Status.SUCCESS):
+        """Mark the trace as finished."""
+        self.end_time = datetime.utcnow()
+        self.status = status
+        if self.start_time:
+            self.total_latency_ms = (self.end_time - self.start_time).total_seconds() * 1000
+
+    def to_dict(self) -> Dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "tags": self.tags,
+            "start_time": self.start_time.isoformat() if self.start_time else None,
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "steps": [s.to_dict() for s in self.steps],
+            "status": self.status.value,
+            "total_tokens": self.total_tokens,
+            "total_latency_ms": self.total_latency_ms,
+            "input_query": self.input_query,
+            "output_result": self.output_result,
+            "metadata": self.metadata,
+        }
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), ensure_ascii=False)

ai_agent_scope-0.2.0/agentscope/monitor.py

@@ -0,0 +1,537 @@
+"""Core monitoring functionality for AgentScope - Scheme 3 Implementation.
+
+This module provides deep monitoring with low intrusion using:
+1. Context Manager pattern (trace_scope)
+2. ContextVars for context propagation
+3. Auto-instrumentation for LLM clients and tools
+"""
+
+import functools
+import requests
+import threading
+import logging
+import time
+import json
+from typing import Optional, List, Callable, Any, Dict
+from contextvars import ContextVar
+from contextlib import contextmanager
+from datetime import datetime
+
+from .models import TraceEvent, ExecutionStep, ToolCall, StepType, Status
+
+# Global configuration
+_monitor_url: Optional[str] = None
+_current_trace: ContextVar[Optional[TraceEvent]] = ContextVar('current_trace', default=None)
+
+logger = logging.getLogger(__name__)
+
+# Track which clients have been instrumented (to avoid double wrapping)
+_instrumented_clients: set = set()
+_original_openai_create: Optional[Callable] = None
+
+
+def init_monitor(url: str = "http://localhost:8000"):
+    """Initialize the AgentScope monitor.
+    
+    Args:
+        url: The URL of the AgentScope backend server
+    """
+    global _monitor_url
+    _monitor_url = url.rstrip('/')
+    logger.info(f"AgentScope monitor initialized: {_monitor_url}")
+
+
+def get_current_trace() -> Optional[TraceEvent]:
+    """Get the current trace in context."""
+    return _current_trace.get()
+
+
+def set_current_trace(trace: Optional[TraceEvent]):
+    """Set the current trace in context."""
+    _current_trace.set(trace)
+
+
+def _send_trace(trace: TraceEvent):
+    """Send trace to the backend server."""
+    global _monitor_url
+    if not _monitor_url:
+        return
+    
+    try:
+        response = requests.post(
+            f"{_monitor_url}/api/traces",
+            json=trace.to_dict(),
+            timeout=5
+        )
+        if response.status_code != 200:
+            logger.warning(f"Failed to send trace: {response.status_code}")
+            try:
+                error_detail = response.json()
+                logger.warning(f"Error detail: {error_detail}")
+            except:
+                logger.warning(f"Response text: {response.text[:200]}")
+    except Exception as e:
+        logger.warning(f"Failed to send trace: {e}")
+
+
+# =============================================================================
+# Scheme 3: Context Manager Pattern (trace_scope)
+# =============================================================================
+
+@contextmanager
+def trace_scope(
+    name: str,
+    input_query: str = "",
+    tags: Optional[List[str]] = None,
+    metadata: Optional[Dict[str, Any]] = None
+):
+    """Context manager for tracing Agent execution.
+    
+    This is the core of Scheme 3 - creating a "tracing bubble" where all
+    LLM calls, tool executions, and memory operations are automatically recorded.
+    
+    Args:
+        name: Name of the trace
+        input_query: The input query/prompt
+        tags: List of tags for categorization
+        metadata: Additional metadata
+        
+    Example:
+        with trace_scope("my_agent", input_query="Hello"):
+            result = llm.chat("Hello")  # Auto-recorded
+            tool_result = search("query")  # Auto-recorded
+            return result
+    """
+    trace_event = TraceEvent(
+        name=name,
+        tags=tags or [],
+        input_query=input_query,
+    )
+    
+    if metadata:
+        trace_event.metadata = metadata
+    
+    # Set as current trace in context
+    token = _current_trace.set(trace_event)
+    
+    # Add input step
+    if input_query:
+        input_step = ExecutionStep(
+            type=StepType.INPUT,
+            content=input_query[:1000],
+            status=Status.SUCCESS,
+        )
+        trace_event.add_step(input_step)
+    
+    logger.debug(f"AgentScope: Started trace {trace_event.id} for {name}")
+    
+    try:
+        yield trace_event
+        trace_event.finish(Status.SUCCESS)
+        logger.debug(f"AgentScope: Trace {trace_event.id} finished successfully")
+    except Exception as e:
+        # Add error step
+        error_step = ExecutionStep(
+            type=StepType.ERROR,
+            content=str(e)[:500],
+            status=Status.ERROR,
+        )
+        trace_event.add_step(error_step)
+        trace_event.finish(Status.ERROR)
+        logger.debug(f"AgentScope: Trace {trace_event.id} finished with error: {e}")
+        raise
+    finally:
+        # Send trace to backend
+        _send_trace(trace_event)
+        # Clear context
+        _current_trace.reset(token)
+
+
+# =============================================================================
+# Auto-Instrumentation: LLM Clients
+# =============================================================================
+
+def _wrap_openai_chat_completion(original_create):
+    """Wrap OpenAI's chat.completions.create method to auto-trace LLM calls."""
+    
+    @functools.wraps(original_create)
+    def wrapped_create(self, *args, **kwargs):
+        trace = get_current_trace()
+        if not trace:
+            # No active trace, just call original
+            return original_create(self, *args, **kwargs)
+        
+        # Extract information for tracing
+        model = kwargs.get('model', 'unknown')
+        messages = kwargs.get('messages', [])
+        
+        # Build prompt preview
+        prompt_preview = ""
+        if messages:
+            last_msg = messages[-1] if isinstance(messages, list) else messages
+            if isinstance(last_msg, dict):
+                prompt_preview = last_msg.get('content', '')[:200]
+            else:
+                prompt_preview = str(last_msg)[:200]
+        
+        start_time = time.time()
+        tokens_input = 0
+        tokens_output = 0
+        
+        try:
+            # Call original method
+            result = original_create(self, *args, **kwargs)
+            
+            # Calculate latency
+            latency_ms = (time.time() - start_time) * 1000
+            
+            # Extract token usage if available
+            if hasattr(result, 'usage') and result.usage:
+                tokens_input = getattr(result.usage, 'prompt_tokens', 0)
+                tokens_output = getattr(result.usage, 'completion_tokens', 0)
+            
+            # Extract completion content
+            completion_preview = ""
+            if hasattr(result, 'choices') and result.choices:
+                choice = result.choices[0]
+                if hasattr(choice, 'message') and choice.message:
+                    completion_preview = getattr(choice.message, 'content', '')[:200]
+                elif hasattr(choice, 'text'):
+                    completion_preview = choice.text[:200]
+            
+            # Add LLM call step to trace
+            step = ExecutionStep(
+                type=StepType.LLM_CALL,
+                content=f"Model: {model}\nPrompt: {prompt_preview}...\nCompletion: {completion_preview}...",
+                tokens_input=tokens_input,
+                tokens_output=tokens_output,
+                latency_ms=latency_ms,
+                metadata={
+                    'model': model,
+                    'messages_count': len(messages) if isinstance(messages, list) else 1,
+                    'prompt_preview': prompt_preview,
+                    'completion_preview': completion_preview,
+                },
+                status=Status.SUCCESS,
+            )
+            trace.add_step(step)
+            logger.debug(f"AgentScope: Recorded LLM call to {model} ({latency_ms:.1f}ms)")
+            
+            return result
+            
+        except Exception as e:
+            # Record error
+            latency_ms = (time.time() - start_time) * 1000
+            step = ExecutionStep(
+                type=StepType.LLM_CALL,
+                content=f"Model: {model}\nError: {str(e)}",
+                latency_ms=latency_ms,
+                metadata={'model': model, 'error': str(e)},
+                status=Status.ERROR,
+            )
+            trace.add_step(step)
+            raise
+    
+    return wrapped_create
+
+
+def instrument_llm(client: Any) -> Any:
+    """Instrument an LLM client to auto-trace all calls.
+    
+    Currently supports:
+    - OpenAI client (openai.OpenAI)
+    - OpenAI Async client (openai.AsyncOpenAI)
+    
+    Args:
+        client: The LLM client instance
+        
+    Returns:
+        The instrumented client (same instance, methods wrapped)
+        
+    Example:
+        import openai
+        client = instrument_llm(openai.OpenAI())
+        
+        with trace_scope("my_agent"):
+            # This call will be automatically traced
+            response = client.chat.completions.create(...)
+    """
+    global _instrumented_clients, _original_openai_create
+    
+    # Check if already instrumented
+    client_id = id(client)
+    if client_id in _instrumented_clients:
+        return client
+    
+    # Try to detect client type and instrument
+    client_class = client.__class__.__name__
+    module_name = getattr(client.__class__, '__module__', '')
+    
+    try:
+        if 'openai' in module_name.lower():
+            # OpenAI client
+            if hasattr(client, 'chat') and hasattr(client.chat, 'completions'):
+                orig_create = client.chat.completions.create
+                if not hasattr(orig_create, '_agentscope_wrapped'):
+                    client.chat.completions.create = _wrap_openai_chat_completion(orig_create)
+                    client.chat.completions.create._agentscope_wrapped = True
+                    _original_openai_create = orig_create
+                    logger.info(f"AgentScope: Instrumented {client_class}")
+        
+        _instrumented_clients.add(client_id)
+        
+    except Exception as e:
+        logger.warning(f"AgentScope: Failed to instrument client: {e}")
+    
+    return client
+
+
+def instrument_openai():
+    """Globally instrument the OpenAI module.
+    
+    This patches the OpenAI class so all new instances are automatically
+    instrumented.
+    
+    Example:
+        instrument_openai()
+        
+        # All OpenAI clients created after this will be auto-traced
+        client = openai.OpenAI()
+    """
+    try:
+        import openai
+        
+        original_init = openai.OpenAI.__init__
+        
+        @functools.wraps(original_init)
+        def patched_init(self, *args, **kwargs):
+            original_init(self, *args, **kwargs)
+            # Auto-instrument this instance
+            instrument_llm(self)
+        
+        openai.OpenAI.__init__ = patched_init
+        logger.info("AgentScope: OpenAI module instrumented globally")
+        
+    except ImportError:
+        logger.warning("AgentScope: OpenAI not installed, skipping global instrumentation")
+    except Exception as e:
+        logger.warning(f"AgentScope: Failed to instrument OpenAI: {e}")
+
+
+# =============================================================================
+# Auto-Instrumentation: Tools
+# =============================================================================
+
+def instrumented_tool(func: Optional[Callable] = None, *, name: Optional[str] = None):
+    """Decorator to auto-trace tool function calls.
+    
+    Args:
+        func: The function to decorate (when used without parentheses)
+        name: Optional custom name for the tool (defaults to function name)
+        
+    Returns:
+        Decorated function that auto-traces its execution
+        
+    Example:
+        @instrumented_tool
+        def search(query: str) -> str:
+            return requests.get(f"https://api.com?q={query}").text
+        
+        @instrumented_tool(name="weather_api")
+        def get_weather(city: str) -> dict:
+            return {"temp": 25, "weather": "sunny"}
+            
+        with trace_scope("agent"):
+            result = search("python")  # Auto-traced
+    """
+    def decorator(f: Callable) -> Callable:
+        tool_name = name or f.__name__
+        
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            trace = get_current_trace()
+            if not trace:
+                # No active trace, just call original
+                return f(*args, **kwargs)
+            
+            # Build arguments dict
+            arguments = {}
+            if args:
+                arguments['args'] = [str(a)[:100] for a in args]
+            if kwargs:
+                arguments['kwargs'] = {k: str(v)[:100] for k, v in kwargs.items()}
+            
+            start_time = time.time()
+            error_msg = None
+            result = None
+            success = False
+            
+            try:
+                result = f(*args, **kwargs)
+                success = True
+                return result
+            except Exception as e:
+                error_msg = str(e)
+                raise
+            finally:
+                latency_ms = (time.time() - start_time) * 1000
+                
+                # Format result for recording (handle None as valid return value)
+                result_str = None
+                if success:
+                    try:
+                        result_str = json.dumps(result, ensure_ascii=False)[:500] if result is not None else "null"
+                    except (TypeError, ValueError):
+                        result_str = str(result)[:500]
+                
+                # Add tool call step
+                tool_call = ToolCall(
+                    name=tool_name,
+                    arguments=arguments,
+                    result=result_str,
+                    error=error_msg,
+                    latency_ms=latency_ms,
+                )
+                
+                step = ExecutionStep(
+                    type=StepType.TOOL_CALL,
+                    content=f"Tool: {tool_name}\nArgs: {json.dumps(arguments, ensure_ascii=False)[:200]}",
+                    tool_call=tool_call,
+                    latency_ms=latency_ms,
+                    status=Status.ERROR if error_msg else Status.SUCCESS,
+                )
+                trace.add_step(step)
+                logger.debug(f"AgentScope: Recorded tool call {tool_name} ({latency_ms:.1f}ms)")
+        
+        return wrapper
+    
+    if func is not None:
+        # Used without parentheses: @instrumented_tool
+        return decorator(func)
+    else:
+        # Used with parentheses: @instrumented_tool(name="...")
+        return decorator
+
+
+# =============================================================================
+# Legacy Decorator (for backward compatibility)
+# =============================================================================
+
+def trace(name: Optional[str] = None, tags: Optional[List[str]] = None):
+    """Decorator to trace an Agent function (legacy API).
+    
+    This is kept for backward compatibility. New code should use trace_scope().
+    
+    Args:
+        name: Name of the trace (defaults to function name)
+        tags: List of tags for categorization
+    
+    Example:
+        @trace(name="my_agent", tags=["production"])
+        def my_agent(query: str):
+            return llm.complete(query)
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            input_content = str(args[0]) if args else str(kwargs)
+            
+            with trace_scope(
+                name=name or func.__name__,
+                input_query=input_content,
+                tags=tags
+            ):
+                return func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+# =============================================================================
+# Utility functions for manual tracing
+# =============================================================================
+
+def add_step(
+    step_type: StepType,
+    content: str,
+    tokens_input: int = 0,
+    tokens_output: int = 0,
+    latency_ms: float = 0.0,
+    metadata: Optional[Dict[str, Any]] = None,
+):
+    """Add a step to the current trace."""
+    trace = get_current_trace()
+    if not trace:
+        return
+    
+    step = ExecutionStep(
+        type=step_type,
+        content=content,
+        tokens_input=tokens_input,
+        tokens_output=tokens_output,
+        latency_ms=latency_ms,
+        metadata=metadata or {},
+        status=Status.SUCCESS,
+    )
+    trace.add_step(step)
+
+
+def add_llm_call(
+    prompt: str,
+    completion: str,
+    tokens_input: int = 0,
+    tokens_output: int = 0,
+    latency_ms: float = 0.0,
+):
+    """Manually record an LLM call step."""
+    add_step(
+        step_type=StepType.LLM_CALL,
+        content=f"Prompt: {prompt[:200]}...\nCompletion: {completion[:200]}...",
+        tokens_input=tokens_input,
+        tokens_output=tokens_output,
+        latency_ms=latency_ms,
+        metadata={"prompt": prompt, "completion": completion},
+    )
+
+
+def add_tool_call(
+    tool_name: str,
+    arguments: dict,
+    result: Any,
+    error: Optional[str] = None,
+    latency_ms: float = 0.0,
+):
+    """Manually record a tool call step."""
+    trace = get_current_trace()
+    if not trace:
+        return
+    
+    tool_call = ToolCall(
+        name=tool_name,
+        arguments=arguments,
+        result=result,
+        error=error,
+        latency_ms=latency_ms,
+    )
+    
+    step = ExecutionStep(
+        type=StepType.TOOL_CALL,
+        content=f"Tool: {tool_name}",
+        tool_call=tool_call,
+        latency_ms=latency_ms,
+        status=Status.ERROR if error else Status.SUCCESS,
+    )
+    trace.add_step(step)
+
+
+def add_thinking(content: str):
+    """Record a thinking/reasoning step."""
+    add_step(StepType.THINKING, content)
+
+
+def add_memory(action: str, details: str):
+    """Record a memory operation step."""
+    add_step(
+        step_type=StepType.THINKING,
+        content=f"Memory {action}: {details}",
+    )

ai_agent_scope-0.2.0/ai_agent_scope.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: ai-agent-scope
+Version: 0.2.0
+Summary: Agent debugging and observability platform - SDK
+Home-page: https://github.com/shenchengtsi/agent-scope
+Author: AgentScope Team
+Author-email: agentscope@example.com
+Project-URL: Bug Reports, https://github.com/shenchengtsi/agent-scope/issues
+Project-URL: Source, https://github.com/shenchengtsi/agent-scope
+Project-URL: Documentation, https://github.com/shenchengtsi/agent-scope/blob/main/docs/
+Keywords: agent,debugging,observability,monitoring,llm,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# AgentScope SDK
+
+Python SDK for AgentScope - Agent debugging and observability platform.
+
+## Installation
+
+```bash
+pip install agentscope
+```
+
+## Quick Start
+
+```python
+from agentscope import trace, init_monitor
+
+# Initialize monitoring
+init_monitor("http://localhost:8000")
+
+@trace(name="my_agent")
+def my_agent(query: str):
+    # Your agent logic here
+    return f"Result for: {query}"
+
+# Run your agent
+result = my_agent("What is AI?")
+```
+
+## Features
+
+- **Zero-intrusion**: Just add `@trace` decorator
+- **Real-time monitoring**: WebSocket-based live updates
+- **Execution tracing**: Full chain of thought visualization
+- **Tool call tracking**: Debug function calling issues
+- **Token & latency metrics**: Performance monitoring

ai_agent_scope-0.2.0/ai_agent_scope.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+setup.py
+agentscope/__init__.py
+agentscope/models.py
+agentscope/monitor.py
+ai_agent_scope.egg-info/PKG-INFO
+ai_agent_scope.egg-info/SOURCES.txt
+ai_agent_scope.egg-info/dependency_links.txt
+ai_agent_scope.egg-info/requires.txt
+ai_agent_scope.egg-info/top_level.txt
+tests/__init__.py
+tests/test_models.py
+tests/test_monitor.py

ai_agent_scope-0.2.0/ai_agent_scope.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ai_agent_scope-0.2.0/ai_agent_scope.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.28.0
+pydantic>=2.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+black>=23.0.0
+flake8>=6.0.0
+isort>=5.12.0

ai_agent_scope-0.2.0/ai_agent_scope.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+agentscope
+tests

ai_agent_scope-0.2.0/setup.cfg

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

ai_agent_scope-0.2.0/setup.py

@@ -0,0 +1,50 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="ai-agent-scope",
+    version="0.2.0",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.28.0",
+        "pydantic>=2.0.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.0.0",
+            "pytest-cov>=4.0.0",
+            "black>=23.0.0",
+            "flake8>=6.0.0",
+            "isort>=5.12.0",
+        ],
+    },
+    python_requires=">=3.8",
+    author="AgentScope Team",
+    author_email="agentscope@example.com",
+    description="Agent debugging and observability platform - SDK",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/shenchengtsi/agent-scope",
+    project_urls={
+        "Bug Reports": "https://github.com/shenchengtsi/agent-scope/issues",
+        "Source": "https://github.com/shenchengtsi/agent-scope",
+        "Documentation": "https://github.com/shenchengtsi/agent-scope/blob/main/docs/",
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Debuggers",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+    ],
+    keywords="agent, debugging, observability, monitoring, llm, ai",
+)

ai_agent_scope-0.2.0/tests/__init__.py

@@ -0,0 +1 @@
+# AgentScope SDK Tests

ai_agent_scope-0.2.0/tests/test_models.py

@@ -0,0 +1,158 @@
+"""Tests for AgentScope data models."""
+
+import pytest
+from datetime import datetime
+
+from agentscope.models import (
+    ToolCall,
+    ExecutionStep,
+    TraceEvent,
+    StepType,
+    Status,
+)
+
+
+class TestToolCall:
+    """Test ToolCall model."""
+    
+    def test_tool_call_creation(self):
+        """Test creating a ToolCall."""
+        tool_call = ToolCall(
+            name="search",
+            arguments={"query": "python"},
+            result="Python is great",
+            latency_ms=100.0,
+        )
+        
+        assert tool_call.name == "search"
+        assert tool_call.arguments == {"query": "python"}
+        assert tool_call.result == "Python is great"
+        assert tool_call.latency_ms == 100.0
+        assert tool_call.id is not None
+    
+    def test_tool_call_to_dict(self):
+        """Test ToolCall serialization."""
+        tool_call = ToolCall(
+            name="search",
+            arguments={"query": "python"},
+            result="result",
+            error=None,
+            latency_ms=100.0,
+        )
+        
+        d = tool_call.to_dict()
+        assert d["name"] == "search"
+        assert d["arguments"] == {"query": "python"}
+        assert d["result"] == "result"
+        assert d["error"] is None
+
+
+class TestExecutionStep:
+    """Test ExecutionStep model."""
+    
+    def test_step_creation(self):
+        """Test creating an ExecutionStep."""
+        step = ExecutionStep(
+            type=StepType.LLM_CALL,
+            content="Test content",
+            tokens_input=100,
+            tokens_output=50,
+            latency_ms=500.0,
+            status=Status.SUCCESS,
+        )
+        
+        assert step.type == StepType.LLM_CALL
+        assert step.content == "Test content"
+        assert step.tokens_input == 100
+        assert step.tokens_output == 50
+        assert step.latency_ms == 500.0
+        assert step.status == Status.SUCCESS
+    
+    def test_step_to_dict(self):
+        """Test ExecutionStep serialization."""
+        step = ExecutionStep(
+            type=StepType.TOOL_CALL,
+            content="Tool execution",
+            status=Status.SUCCESS,
+        )
+        
+        d = step.to_dict()
+        assert d["type"] == "tool_call"
+        assert d["content"] == "Tool execution"
+        assert d["status"] == "success"
+        assert "timestamp" in d
+
+
+class TestTraceEvent:
+    """Test TraceEvent model."""
+    
+    def test_trace_creation(self):
+        """Test creating a TraceEvent."""
+        trace = TraceEvent(
+            name="test_trace",
+            tags=["test", "debug"],
+            input_query="test query",
+        )
+        
+        assert trace.name == "test_trace"
+        assert trace.tags == ["test", "debug"]
+        assert trace.input_query == "test query"
+        assert trace.status == Status.PENDING
+        assert trace.total_tokens == 0
+    
+    def test_add_step(self):
+        """Test adding steps to trace."""
+        trace = TraceEvent(name="test")
+        step = ExecutionStep(type=StepType.INPUT, content="Input")
+        
+        trace.add_step(step)
+        
+        assert len(trace.steps) == 1
+        assert trace.total_tokens == step.tokens_input + step.tokens_output
+    
+    def test_finish_success(self):
+        """Test finishing trace with success."""
+        trace = TraceEvent(name="test")
+        trace.add_step(ExecutionStep(
+            type=StepType.INPUT,
+            content="Input",
+            tokens_input=10,
+            tokens_output=5,
+        ))
+        
+        trace.finish(Status.SUCCESS)
+        
+        assert trace.status == Status.SUCCESS
+        assert trace.end_time is not None
+        assert trace.total_latency_ms > 0
+    
+    def test_finish_error(self):
+        """Test finishing trace with error."""
+        trace = TraceEvent(name="test")
+        trace.finish(Status.ERROR)
+        
+        assert trace.status == Status.ERROR
+        assert trace.end_time is not None
+    
+    def test_to_dict(self):
+        """Test TraceEvent serialization."""
+        trace = TraceEvent(
+            name="test",
+            tags=["debug"],
+            input_query="query",
+            metadata={"key": "value"},
+        )
+        trace.add_step(ExecutionStep(type=StepType.INPUT, content="Input"))
+        trace.finish(Status.SUCCESS)
+        
+        d = trace.to_dict()
+        assert d["name"] == "test"
+        assert d["tags"] == ["debug"]
+        assert d["input_query"] == "query"
+        assert d["metadata"] == {"key": "value"}
+        assert d["status"] == "success"
+        assert len(d["steps"]) == 1
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

ai_agent_scope-0.2.0/tests/test_monitor.py

@@ -0,0 +1,140 @@
+"""Tests for AgentScope monitoring functionality."""
+
+import pytest
+import time
+from unittest.mock import Mock, patch
+
+from agentscope import (
+    trace_scope,
+    get_current_trace,
+    add_thinking,
+    add_llm_call,
+    add_tool_call,
+    init_monitor,
+)
+from agentscope.models import StepType, Status
+
+
+class TestTraceScope:
+    """Test trace_scope context manager."""
+    
+    def test_trace_scope_creates_trace(self):
+        """Test that trace_scope creates a trace event."""
+        with trace_scope("test_trace", input_query="test input") as trace:
+            assert trace is not None
+            assert trace.name == "test_trace"
+            assert trace.input_query == "test input"
+    
+    def test_trace_scope_adds_input_step(self):
+        """Test that trace_scope adds an input step."""
+        with trace_scope("test_trace", input_query="test input") as trace:
+            pass
+        
+        # After exiting, trace should have input step
+        assert len(trace.steps) >= 1
+        assert trace.steps[0].type == StepType.INPUT
+    
+    def test_trace_scope_handles_exception(self):
+        """Test that trace_scope handles exceptions properly."""
+        trace = None
+        try:
+            with trace_scope("test_trace", input_query="test") as t:
+                trace = t
+                raise ValueError("Test error")
+        except ValueError:
+            pass
+        
+        # Trace should have error step
+        assert trace is not None
+        assert trace.status == Status.ERROR
+        error_steps = [s for s in trace.steps if s.type == StepType.ERROR]
+        assert len(error_steps) == 1
+    
+    def test_nested_trace_scopes(self):
+        """Test that nested trace scopes create separate traces."""
+        outer_trace = None
+        inner_trace = None
+        
+        with trace_scope("outer") as outer:
+            outer_trace = outer
+            with trace_scope("inner") as inner:
+                inner_trace = inner
+        
+        assert outer_trace.name == "outer"
+        assert inner_trace.name == "inner"
+        assert outer_trace.id != inner_trace.id
+
+
+class TestAddSteps:
+    """Test adding steps to trace."""
+    
+    def test_add_thinking(self):
+        """Test adding thinking step."""
+        with trace_scope("test") as trace:
+            add_thinking("Test thinking")
+        
+        thinking_steps = [s for s in trace.steps if s.type == StepType.THINKING]
+        assert len(thinking_steps) == 1
+        assert "Test thinking" in thinking_steps[0].content
+    
+    def test_add_llm_call(self):
+        """Test adding LLM call step."""
+        with trace_scope("test") as trace:
+            add_llm_call(
+                prompt="Hello",
+                completion="World",
+                tokens_input=10,
+                tokens_output=5,
+                latency_ms=100.0,
+            )
+        
+        llm_steps = [s for s in trace.steps if s.type == StepType.LLM_CALL]
+        assert len(llm_steps) == 1
+        assert llm_steps[0].tokens_input == 10
+        assert llm_steps[0].tokens_output == 5
+        assert llm_steps[0].latency_ms == 100.0
+    
+    def test_add_tool_call(self):
+        """Test adding tool call step."""
+        with trace_scope("test") as trace:
+            add_tool_call(
+                tool_name="search",
+                arguments={"query": "python"},
+                result="Python is a programming language",
+                latency_ms=50.0,
+            )
+        
+        tool_steps = [s for s in trace.steps if s.type == StepType.TOOL_CALL]
+        assert len(tool_steps) == 1
+        assert tool_steps[0].tool_call.name == "search"
+        assert tool_steps[0].tool_call.arguments == {"query": "python"}
+
+
+class TestGetCurrentTrace:
+    """Test get_current_trace function."""
+    
+    def test_get_current_trace_outside_scope(self):
+        """Test getting trace outside scope returns None."""
+        trace = get_current_trace()
+        assert trace is None
+    
+    def test_get_current_trace_inside_scope(self):
+        """Test getting trace inside scope returns trace."""
+        with trace_scope("test") as expected_trace:
+            current = get_current_trace()
+            assert current is expected_trace
+
+
+class TestInitMonitor:
+    """Test init_monitor function."""
+    
+    @patch('agentscope.monitor.requests.post')
+    def test_init_monitor_sets_url(self, mock_post):
+        """Test that init_monitor sets the monitor URL."""
+        init_monitor("http://test-server:8000")
+        # Just verify no exception is raised
+        assert True
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])