agentscope-sdk 0.1.0__tar.gz

agentscope_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: agentscope-sdk
+Version: 0.1.0
+Summary: AgentScope Python SDK
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# AgentScope Python SDK
+
+Python client SDK for AgentScope telemetry and instrumentation.

agentscope_sdk-0.1.0/README.md

@@ -0,0 +1,3 @@
+# AgentScope Python SDK
+
+Python client SDK for AgentScope telemetry and instrumentation.

agentscope_sdk-0.1.0/agentscope/__init__.py

@@ -0,0 +1,15 @@
+from .coding_agent import coding_agent_run, instrument_coding_agent, read_file, run_command, write_file
+from .instrumentation import auto_instrument
+from .run import observe_run
+from .span import observe_span
+
+__all__ = [
+    "observe_run",
+    "observe_span",
+    "auto_instrument",
+    "coding_agent_run",
+    "instrument_coding_agent",
+    "read_file",
+    "write_file",
+    "run_command",
+]

agentscope_sdk-0.1.0/agentscope/client.py

@@ -0,0 +1,44 @@
+import os
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict
+
+
+class AgentScopeClient:
+    def __init__(self, base_url: str | None = None, api_key: str | None = None, timeout: float = 5.0) -> None:
+        self.base_url = (base_url or os.getenv("AGENTSCOPE_API_BASE", "http://localhost:8080")).rstrip("/")
+        self.api_key = api_key or os.getenv("AGENTSCOPE_API_KEY", "")
+        self.timeout = timeout
+
+    def ingest(self, payload: Dict[str, Any]) -> None:
+        if not self.api_key:
+            raise RuntimeError("AgentScope ingest requires an API key. Set AGENTSCOPE_API_KEY or pass api_key.")
+
+        try:
+            import requests
+        except ImportError:
+            body = json.dumps(payload).encode("utf-8")
+            request = urllib.request.Request(
+                f"{self.base_url}/v1/ingest",
+                data=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "X-AgentScope-API-Key": self.api_key,
+                },
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout):
+                    return
+            except urllib.error.HTTPError as exc:
+                raise RuntimeError(f"AgentScope ingest failed with status {exc.code}") from exc
+            return
+
+        response = requests.post(
+            f"{self.base_url}/v1/ingest",
+            json=payload,
+            headers={"X-AgentScope-API-Key": self.api_key},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()

agentscope_sdk-0.1.0/agentscope/coding_agent.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import difflib
+import subprocess
+import uuid
+from dataclasses import dataclass
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+
+from .instrumentation import auto_instrument
+from .run import _current_run_state, observe_run
+from .span import observe_span
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass
+class CommandResult:
+    command: str
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+def _append_artifact(*, span: dict[str, Any], kind: str, payload: dict[str, Any]) -> None:
+    run_state = _current_run_state()
+    if run_state is None:
+        return
+
+    run_state.artifacts.append(
+        {
+            "id": str(uuid.uuid4()),
+            "run_id": span["run_id"],
+            "span_id": span["id"],
+            "kind": kind,
+            "payload": payload,
+        }
+    )
+
+
+def _as_path(file_path: str | Path) -> Path:
+    return file_path if isinstance(file_path, Path) else Path(file_path)
+
+
+class coding_agent_run:
+    def __init__(self, agent_name: str = "coding_agent") -> None:
+        self.agent_name = agent_name
+        self._run = observe_run("coding_agent", agent_name=agent_name)
+
+    def __enter__(self) -> dict[str, Any]:
+        auto_instrument()
+        return self._run.__enter__()
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        return self._run.__exit__(exc_type, exc, tb)
+
+
+def instrument_coding_agent(fn: F) -> F:
+    @wraps(fn)
+    def _wrapped(*args: Any, **kwargs: Any) -> Any:
+        with coding_agent_run(agent_name=fn.__name__):
+            return fn(*args, **kwargs)
+
+    return _wrapped  # type: ignore[return-value]
+
+
+def read_file(file_path: str | Path, *, encoding: str = "utf-8") -> str:
+    path = _as_path(file_path)
+    with observe_span("file_read") as span:
+        span["metadata"] = {"file_path": str(path)}
+        return path.read_text(encoding=encoding)
+
+
+def write_file(file_path: str | Path, content: str, *, encoding: str = "utf-8") -> None:
+    path = _as_path(file_path)
+    previous = path.read_text(encoding=encoding) if path.exists() else ""
+
+    with observe_span("file_write") as span:
+        span["metadata"] = {"file_path": str(path)}
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding=encoding)
+
+        diff = "".join(
+            difflib.unified_diff(
+                previous.splitlines(keepends=True),
+                content.splitlines(keepends=True),
+                fromfile=f"a/{path}",
+                tofile=f"b/{path}",
+            )
+        )
+        _append_artifact(
+            span=span,
+            kind="file.diff",
+            payload={"file_path": str(path), "diff": diff},
+        )
+        _append_artifact(
+            span=span,
+            kind="file.content",
+            payload={"file_path": str(path), "content": content},
+        )
+
+
+def run_command(
+    command: str | list[str],
+    *,
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+    check: bool = False,
+    shell: bool | None = None,
+) -> CommandResult:
+    resolved_shell = shell if shell is not None else isinstance(command, str)
+
+    with observe_span("command_exec") as span:
+        command_text = command if isinstance(command, str) else " ".join(command)
+        completed = subprocess.run(
+            command,
+            cwd=str(cwd) if cwd is not None else None,
+            env=env,
+            check=False,
+            capture_output=True,
+            text=True,
+            shell=resolved_shell,
+        )
+        span["metadata"] = {
+            "command": command_text,
+            "exit_code": completed.returncode,
+            "stdout": completed.stdout,
+            "stderr": completed.stderr,
+        }
+
+        if check and completed.returncode != 0:
+            raise subprocess.CalledProcessError(
+                completed.returncode,
+                command,
+                output=completed.stdout,
+                stderr=completed.stderr,
+            )
+
+        return CommandResult(
+            command=command_text,
+            exit_code=completed.returncode,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+        )

agentscope_sdk-0.1.0/agentscope/exporter.py

@@ -0,0 +1,16 @@
+from typing import Any, Dict, List
+
+from .client import AgentScopeClient
+
+
+class TelemetryExporter:
+    def __init__(self, client: AgentScopeClient | None = None) -> None:
+        self.client = client or AgentScopeClient()
+
+    def export(self, run: Dict[str, Any], spans: List[Dict[str, Any]], artifacts: List[Dict[str, Any]]) -> None:
+        payload = {
+            "run": run,
+            "spans": spans,
+            "artifacts": artifacts,
+        }
+        self.client.ingest(payload)

agentscope_sdk-0.1.0/agentscope/instrumentation/__init__.py

@@ -0,0 +1,3 @@
+from .tracer import auto_instrument
+
+__all__ = ["auto_instrument"]

agentscope_sdk-0.1.0/agentscope/instrumentation/anthropic_adapter.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+from .registry import ProviderAdapter, TargetSpec
+from .token_usage import normalize_usage
+
+
+def _safe_getattr(value: Any, name: str, default: Any = None) -> Any:
+    try:
+        return getattr(value, name, default)
+    except Exception:
+        return default
+
+
+def _safe_get(value: Any, key: str, default: Any = None) -> Any:
+    if isinstance(value, dict):
+        return value.get(key, default)
+    return _safe_getattr(value, key, default)
+
+
+def _extract_call_data(
+    original: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    try:
+        bound = inspect.signature(original).bind_partial(*args, **kwargs)
+        data = dict(bound.arguments)
+        extra_kwargs = data.pop("kwargs", None)
+        if isinstance(extra_kwargs, dict):
+            data.update(extra_kwargs)
+        return data
+    except Exception:
+        return dict(kwargs)
+
+
+def _extract_text(response: Any) -> str | None:
+    if isinstance(response, dict):
+        content = response.get("content")
+        if isinstance(content, list):
+            parts = [item.get("text") for item in content if isinstance(item, dict)]
+            parts = [part for part in parts if isinstance(part, str)]
+            return "".join(parts) if parts else None
+        return None
+
+    content = _safe_getattr(response, "content")
+    if isinstance(content, list):
+        parts = [_safe_getattr(item, "text") for item in content]
+        parts = [part for part in parts if isinstance(part, str)]
+        return "".join(parts) if parts else None
+    return None
+
+
+def _request_extractor(
+    original: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    data = _extract_call_data(original, args, kwargs)
+    return {
+        "model": data.get("model"),
+        "messages": data.get("messages"),
+        "prompt": data.get("system"),
+    }
+
+
+def _response_extractor(response: Any) -> dict[str, Any]:
+    usage = _safe_get(response, "usage")
+    input_tokens, output_tokens, total_tokens = normalize_usage(
+        _safe_get(usage, "input_tokens"),
+        _safe_get(usage, "output_tokens"),
+    )
+    return {
+        "response_text": _extract_text(response),
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_tokens": total_tokens,
+    }
+
+
+def get_adapter() -> ProviderAdapter:
+    return ProviderAdapter(
+        name="anthropic",
+        targets=(
+            TargetSpec(
+                key="anthropic.messages.create",
+                provider="anthropic",
+                module="anthropic.resources.messages.messages",
+                path=("Messages", "create"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+            TargetSpec(
+                key="anthropic.messages.async_create",
+                provider="anthropic",
+                module="anthropic.resources.messages.messages",
+                path=("AsyncMessages", "create"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+        ),
+    )

agentscope_sdk-0.1.0/agentscope/instrumentation/http_interceptor.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..run import _current_run_state, observe_run
+from .llm_tracer import trace_http_llm_call
+from .provider_detection import detect_provider
+
+_REQUESTS_PATCHED = False
+_ORIGINAL_REQUEST: Any = None
+
+
+def instrument_requests() -> None:
+    global _REQUESTS_PATCHED
+    global _ORIGINAL_REQUEST
+
+    if _REQUESTS_PATCHED:
+        return
+
+    try:
+        import requests
+    except Exception:
+        return
+
+    current = requests.Session.request
+    if getattr(current, "__agentscope_wrapped__", False):
+        _REQUESTS_PATCHED = True
+        return
+
+    _ORIGINAL_REQUEST = current
+
+    def wrapped_request(self: Any, method: str, url: str, *args: Any, **kwargs: Any) -> Any:
+        provider = detect_provider(url)
+        if provider is None:
+            return _ORIGINAL_REQUEST(self, method, url, *args, **kwargs)
+
+        payload = kwargs.get("json")
+        if payload is None:
+            payload = {}
+
+        def request_fn() -> Any:
+            return _ORIGINAL_REQUEST(self, method, url, *args, **kwargs)
+
+        if _current_run_state() is None:
+            with observe_run(f"{provider}_http_auto_instrumentation", agent_name=provider):
+                return trace_http_llm_call(provider, url, payload, request_fn)
+        return trace_http_llm_call(provider, url, payload, request_fn)
+
+    wrapped_request.__agentscope_wrapped__ = True  # type: ignore[attr-defined]
+    requests.Session.request = wrapped_request
+    _REQUESTS_PATCHED = True

agentscope_sdk-0.1.0/agentscope/instrumentation/langchain_adapter.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+from .registry import ProviderAdapter, TargetSpec
+
+
+def _safe_getattr(value: Any, name: str, default: Any = None) -> Any:
+    try:
+        return getattr(value, name, default)
+    except Exception:
+        return default
+
+
+def _extract_call_data(
+    original: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    try:
+        bound = inspect.signature(original).bind_partial(*args, **kwargs)
+        data = dict(bound.arguments)
+        extra_kwargs = data.pop("kwargs", None)
+        if isinstance(extra_kwargs, dict):
+            data.update(extra_kwargs)
+        return data
+    except Exception:
+        return dict(kwargs)
+
+
+def _extract_text(response: Any) -> str | None:
+    if isinstance(response, str):
+        return response
+    if isinstance(response, dict):
+        content = response.get("content")
+        if isinstance(content, str):
+            return content
+        text = response.get("text")
+        if isinstance(text, str):
+            return text
+        return None
+    content = _safe_getattr(response, "content")
+    if isinstance(content, str):
+        return content
+    text = _safe_getattr(response, "text")
+    if isinstance(text, str):
+        return text
+    return None
+
+
+def _request_extractor(
+    original: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    data = _extract_call_data(original, args, kwargs)
+    llm_obj = data.get("self")
+    model = _safe_getattr(llm_obj, "model_name") or _safe_getattr(llm_obj, "model")
+    input_data = data.get("input") or data.get("messages") or data.get("prompt")
+    return {
+        "model": model,
+        "messages": input_data if isinstance(input_data, list) else None,
+        "prompt": input_data if isinstance(input_data, (str, dict)) else None,
+    }
+
+
+def _response_extractor(response: Any) -> dict[str, Any]:
+    return {
+        "response_text": _extract_text(response),
+        "input_tokens": None,
+        "output_tokens": None,
+    }
+
+
+def get_adapter() -> ProviderAdapter:
+    return ProviderAdapter(
+        name="langchain",
+        targets=(
+            TargetSpec(
+                key="langchain.chat.invoke",
+                provider="langchain",
+                module="langchain_core.language_models.chat_models",
+                path=("BaseChatModel", "invoke"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+            TargetSpec(
+                key="langchain.chat.ainvoke",
+                provider="langchain",
+                module="langchain_core.language_models.chat_models",
+                path=("BaseChatModel", "ainvoke"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+            TargetSpec(
+                key="langchain.llm.invoke",
+                provider="langchain",
+                module="langchain_core.language_models.llms",
+                path=("BaseLLM", "invoke"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+            TargetSpec(
+                key="langchain.llm.ainvoke",
+                provider="langchain",
+                module="langchain_core.language_models.llms",
+                path=("BaseLLM", "ainvoke"),
+                request_extractor=_request_extractor,
+                response_extractor=_response_extractor,
+            ),
+        ),
+    )

agentscope_sdk-0.1.0/agentscope/instrumentation/llm_tracer.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Callable
+
+from ..run import _current_run_state
+from ..span import observe_span
+from .token_usage import normalize_usage
+
+
+def _extract_response_text(body: Any) -> str | None:
+    if not isinstance(body, dict):
+        return None
+
+    choices = body.get("choices")
+    if isinstance(choices, list) and choices:
+        message = choices[0].get("message")
+        if isinstance(message, dict):
+            content = message.get("content")
+            if isinstance(content, str):
+                return content
+            if isinstance(content, list):
+                parts = [part.get("text") for part in content if isinstance(part, dict)]
+                text_parts = [part for part in parts if isinstance(part, str)]
+                if text_parts:
+                    return "".join(text_parts)
+
+        text = choices[0].get("text")
+        if isinstance(text, str):
+            return text
+
+    content = body.get("content")
+    if isinstance(content, list) and content:
+        first = content[0]
+        if isinstance(first, dict):
+            text = first.get("text")
+            if isinstance(text, str):
+                return text
+
+    response = body.get("response")
+    if isinstance(response, str):
+        return response
+
+    output = body.get("output")
+    if isinstance(output, str):
+        return output
+
+    return None
+
+
+def _extract_usage(body: Any) -> tuple[int | None, int | None, int | None]:
+    if not isinstance(body, dict):
+        return None, None, None
+
+    usage = body.get("usage")
+    if not isinstance(usage, dict):
+        return None, None, None
+
+    input_tokens = usage.get("prompt_tokens")
+    if input_tokens is None:
+        input_tokens = usage.get("input_tokens")
+
+    output_tokens = usage.get("completion_tokens")
+    if output_tokens is None:
+        output_tokens = usage.get("output_tokens")
+
+    return normalize_usage(input_tokens, output_tokens)
+
+
+def _append_artifact(*, span: dict[str, Any], kind: str, payload: dict[str, Any]) -> None:
+    run_state = _current_run_state()
+    if run_state is None:
+        return
+
+    run_state.artifacts.append(
+        {
+            "id": str(uuid.uuid4()),
+            "run_id": span["run_id"],
+            "span_id": span["id"],
+            "kind": kind,
+            "payload": payload,
+        }
+    )
+
+
+def _extract_prompt_fields(payload: Any) -> tuple[Any, Any, Any]:
+    if not isinstance(payload, dict):
+        return None, None, None
+
+    messages = payload.get("messages")
+    prompt = payload.get("prompt")
+    if prompt is None:
+        prompt = payload.get("input")
+    return messages, prompt, payload.get("input")
+
+
+def trace_http_llm_call(
+    provider: str,
+    url: str,
+    payload: Any,
+    request_fn: Callable[[], Any],
+) -> Any:
+    started = time.perf_counter()
+    with observe_span("llm_call", span_type="llm_call") as span:
+        span["provider"] = provider
+        span["endpoint_url"] = url
+        span["model"] = payload.get("model") if isinstance(payload, dict) else None
+        messages, prompt, input_value = _extract_prompt_fields(payload)
+
+        _append_artifact(
+            span=span,
+            kind="llm.prompt",
+            payload={
+                "provider": provider,
+                "endpoint_url": url,
+                "model": span.get("model"),
+                "messages": messages,
+                "prompt": prompt,
+                "input": input_value,
+                "payload": payload,
+            },
+        )
+
+        response = request_fn()
+        latency_ms = int((time.perf_counter() - started) * 1000)
+
+        response_body: Any = None
+        try:
+            response_body = response.json()
+        except Exception:
+            response_body = None
+
+        response_text = _extract_response_text(response_body)
+        input_tokens, output_tokens, total_tokens = _extract_usage(response_body)
+        http_status = getattr(response, "status_code", None)
+
+        span["latency_ms"] = latency_ms
+        span["input_tokens"] = input_tokens
+        span["output_tokens"] = output_tokens
+        span["total_tokens"] = total_tokens
+
+        _append_artifact(
+            span=span,
+            kind="llm.response",
+            payload={
+                "provider": provider,
+                "endpoint_url": url,
+                "model": span.get("model"),
+                "response": response_body,
+                "response_text": response_text,
+                "http_status": http_status,
+                "latency_ms": latency_ms,
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "total_tokens": total_tokens,
+            },
+        )
+
+        return response