hud-python 0.4.45__py3-none-any.whl → 0.5.1__py3-none-any.whl

hud/misc/claude_plays_pokemon.py

@@ -1,292 +0,0 @@
-# pyright: reportGeneralTypeIssues=false
-from __future__ import annotations
-
-import json
-import logging
-from typing import TYPE_CHECKING, Any, cast
-
-from anthropic import AsyncAnthropic
-
-from hud.adapters import Adapter
-from hud.adapters.common.types import CLA
-
-# Update import to current API; if this script is legacy, keep it optional
-try:
-    from hud.agents import MCPAgent as Agent  # type: ignore[assignment]
-except Exception:  # pragma: no cover - optional example script
-    from hud.agents import MCPAgent as Agent  # fallback
-from hud.settings import settings
-
-if TYPE_CHECKING:
-    from anthropic.types.beta import (
-        BetaImageBlockParam,
-        BetaMessageParam,
-        BetaTextBlockParam,
-    )
-
-    from hud.env.environment import Observation
-
-logger = logging.getLogger(__name__)
-
-# Constants
-DEFAULT_MODEL = "claude-3-7-sonnet-20250219"
-DEFAULT_MAX_TOKENS = 4096
-DEFAULT_MAX_ITERATIONS = 10
-DEFAULT_TEMPERATURE = 0.7
-DEFAULT_MAX_MESSAGE_MEMORY = 20
-
-
-def generate_system_prompt(game_name: str) -> str:
-    """Generate the system prompt for the AI agent.
-
-    Args:
-        game_name: Name of the game being played
-
-    Returns:
-        str: The system prompt for the AI agent
-    """
-    return """You are a specialized AI assistant designed to play Pokémon games via screenshot analysis and text instructions. Your task is to understand the current game state from visual input, determine appropriate actions, and respond with structured outputs that control the game.
-
-For each turn, you will receive:
-1. A screenshot of the current game state
-2. Contextual information about the game progress, recent events, and objectives
-
-Based on this information, you must analyze the situation, determine the best course of action, and provide a structured JSON response.
-
-## Response Format
-Your response MUST follow this exact JSON format with no additional markers, tags, or block delimiters:
-
-{
-  "analysis": "Brief analysis of the current game situation, visible UI elements, and important context (1-3 sentences)",
-  "current_objective": "The immediate goal based on the game state (single sentence)",
-  "reasoning": "Step-by-step logic explaining your chosen action sequence (2-4 sentences)",
-  "progress_assessment": "Evaluation of whether previous action(s) achieved their intended goal and why/why not (1-2 sentences)",
-  "actions": [
-    {
-      "type": "press",
-      "keys": ["up"|"down"|"left"|"right"|"a"|"b"|"start"|"select"|"pause"]
-    },
-    {
-      "type": "wait",
-      "time": milliseconds_to_wait
-    }
-  ]
-}
-
-IMPORTANT: Do not include any conversation markers like <<ASSISTANT_CONVERSATION_START>> or <<ASSISTANT_CONVERSATION_END>> around your response. Provide only the clean JSON object.
-
-## Action Types
-- Button presses: {"type": "press", "keys": ["button_name"]} - Valid buttons are: up, down, left, right, a, b, start, select, pause
-- Wait for processing: {"type": "wait", "time": milliseconds}
-
-## Important Rules
-1. Never use "wait" commands while the game is paused. The game state will not change while paused, so waiting is ineffective.
-2. If you detect the game is paused, your next action should be to unpause by using {"type": "press", "keys": ["pause"]} before attempting other actions.
-3. Maintain awareness of whether the game is in a paused state based on visual cues in the screenshot.
-
-## Game Play Guidelines
-1. **Navigation**: Use directional buttons to move the character or navigate menus
-2. **Interaction**: Use 'a' to confirm selections and interact with objects/NPCs, 'b' to cancel or exit menus
-3. **Menu Access**: Use 'start' to access the game menu
-4. **Battle Strategy**: Analyze Pokémon types, moves, and stats to make optimal battle decisions
-5. **Progressive Play**: Work toward completing the current objective while being mindful of longer-term goals like leveling Pokémon, collecting badges, and advancing the story
-6. **Resource Management**: Monitor and manage HP, PP, items, and Pokéballs effectively
-7. **Memory**: Maintain awareness of the game history and your previous actions to avoid repetitive behaviors
-
-Always provide thoughtful analysis and clear reasoning for your decisions. If you're uncertain about the best course of action, prioritize safe moves that gather more information.
-"""  # noqa: E501
-
-
-def extract_action_from_response_block(block: dict[str, Any]) -> list[dict[str, Any]]:
-    """Extract actions from a response block.
-
-    Args:
-        block: The response block containing actions
-
-    Returns:
-        list[dict[str, Any]]: List of actions extracted from the block
-    """
-    if "actions" in block:
-        actions = block["actions"]
-        if isinstance(actions, list):
-            return actions
-    return []
-
-
-def extract_json_from_response(response: str) -> str:
-    """Extract JSON from a response string.
-
-    Args:
-        response: The response string containing JSON
-
-    Returns:
-        str: The extracted JSON string
-    """
-    # Try to find JSON block with markdown code block markers
-    start = response.find("```json")
-    end = response.rfind("```")
-    if start != -1 and end != -1:
-        start += len("```json")
-        return response[start:end].strip()
-
-    # Try to find JSON object directly
-    start = response.find("{")
-    end = response.rfind("}")
-    if start != -1 and end != -1:
-        return response[start : end + 1].strip()
-
-    return response.strip()
-
-
-class ClaudePlaysPokemon(Agent[AsyncAnthropic, CLA]):
-    """AI agent that plays Pokémon games using Claude."""
-
-    def __init__(
-        self,
-        client: AsyncAnthropic | None = None,
-        adapter: Adapter | None = None,
-        model: str = DEFAULT_MODEL,
-        max_tokens: int = DEFAULT_MAX_TOKENS,
-        max_iterations: int = DEFAULT_MAX_ITERATIONS,
-        temperature: float = DEFAULT_TEMPERATURE,
-        max_message_memory: int = DEFAULT_MAX_MESSAGE_MEMORY,
-    ) -> None:
-        """Initialize the Claude Plays Pokémon agent.
-
-        Args:
-            client: Anthropic API client
-            adapter: Game adapter
-            model: Claude model to use
-            max_tokens: Maximum tokens for response
-            max_iterations: Maximum number of iterations
-            temperature: Response temperature
-            max_message_memory: Maximum number of messages to remember
-
-        Raises:
-            ValueError: If API key is not provided
-        """
-        if client is None:
-            api_key = settings.anthropic_api_key
-            if not api_key:
-                raise ValueError("Anthropic API key is required")
-            client = AsyncAnthropic(api_key=api_key)
-
-        if adapter is None:
-            adapter = Adapter()
-
-        super().__init__(
-            client=client,
-            adapter=adapter,
-        )
-
-        self.model = model
-        self.max_tokens = max_tokens
-        self.max_iterations = max_iterations
-        self.temperature = temperature
-        self.max_message_memory = max_message_memory
-
-        self.system_prompts: list[BetaMessageParam] = [
-            {
-                "role": "assistant",
-                "content": generate_system_prompt("Pokemon Red"),
-            }
-        ]
-
-        self.messages: list[BetaMessageParam] = []
-
-    async def fetch_response(self, observation: Observation) -> tuple[list[dict[str, Any]], bool]:
-        """Fetch a response from Claude based on the current observation.
-
-        Args:
-            observation: The current game observation
-
-        Returns:
-            tuple[list[dict[str, Any]], bool, list[LogType] | None]: List of actions, whether the game is done, and a list of strings or dictionaries of logs.
-
-        Raises:
-            ValueError: If client is not initialized
-        """  # noqa: E501
-        if not self.client:
-            raise ValueError("Client is not initialized")
-
-        user_content: list[BetaTextBlockParam | BetaImageBlockParam] = []
-
-        if observation.text:
-            user_content.append(
-                {
-                    "type": "text",
-                    "text": observation.text,
-                }
-            )
-
-        if observation.screenshot:
-            logger.debug("Processing screenshot data")
-            user_content.append(
-                {
-                    "type": "image",
-                    "source": {
-                        "type": "base64",
-                        "media_type": "image/png",
-                        "data": observation.screenshot,
-                    },
-                }
-            )
-
-        self.messages.append(
-            {
-                "role": "user",
-                "content": user_content,
-            }
-        )
-
-        logger.debug(
-            "Sending messages to Claude", extra={"messages": self.system_prompts + self.messages}
-        )
-
-        response = await self.client.beta.messages.create(
-            model=self.model,
-            messages=self.system_prompts + self.messages,
-            temperature=self.temperature,
-            max_tokens=self.max_tokens,
-        )
-
-        response_content = response.content
-        self.messages.append(
-            cast(
-                "BetaMessageParam",
-                {
-                    "role": "user",
-                    "content": response_content,
-                },
-            )
-        )
-
-        # Maintain message memory limit
-        while len(self.messages) > self.max_message_memory:
-            self.messages.pop(0)
-
-        action_list: list[dict[str, Any]] = []
-
-        # Parse response content to extract actions
-        for block in response_content:
-            if block.type == "text":
-                text_json = extract_json_from_response(block.text)
-                try:
-                    text = json.loads(text_json)
-                    if not isinstance(text, dict):
-                        logger.error("Invalid response format", extra={"text": text})
-                        raise ValueError("Response is not a dictionary")
-
-                    action_list.extend(extract_action_from_response_block(text))
-
-                except json.JSONDecodeError as e:
-                    logger.error(
-                        "Failed to parse response", extra={"error": str(e), "text": text_json}
-                    )
-
-            else:
-                logger.error("Unexpected block type", extra={"type": type(block)})
-
-        logger.debug("Extracted actions", extra={"actions": action_list})
-
-        return action_list, False

hud/otel/__init__.py

@@ -1,35 +0,0 @@
-"""HUD OpenTelemetry integration.
-
-This package provides the internal OpenTelemetry implementation for HUD telemetry.
-Users should interact with the telemetry APIs through hud.telemetry instead.
-
-Internal Components:
-- config: OpenTelemetry configuration and setup
-- context: Trace context management and utilities
-- processors: Span enrichment with HUD context
-- exporters: Sending spans to HUD backend
-- collector: In-memory span collection for replay
-- instrumentation: Auto-instrumentation for agents and MCP
-"""
-
-from __future__ import annotations
-
-from .collector import enable_trace_collection
-from .config import configure_telemetry, is_telemetry_configured, shutdown_telemetry
-from .context import (
-    get_current_task_run_id,
-    is_root_trace,
-    span_context,
-    trace,
-)
-
-__all__ = [
-    "configure_telemetry",
-    "enable_trace_collection",
-    "get_current_task_run_id",
-    "is_root_trace",
-    "is_telemetry_configured",
-    "shutdown_telemetry",
-    "span_context",
-    "trace",
-]

hud/otel/collector.py

@@ -1,142 +0,0 @@
-"""Global span collector for building in-memory traces.
-
-This module provides a way to collect spans during execution
-and retrieve them as a Trace object, enabling replay functionality
-without modifying agent code.
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from contextvars import ContextVar
-from typing import TYPE_CHECKING
-
-from opentelemetry import trace
-from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
-
-from hud.types import Trace
-
-if TYPE_CHECKING:
-    from opentelemetry.sdk.trace import ReadableSpan
-
-logger = logging.getLogger(__name__)
-
-# Global storage for collected spans by task_run_id
-_TRACE_STORAGE: dict[str, TraceCollector] = {}
-_LOCK = threading.Lock()
-
-# Context variable to track if collection is enabled
-_collecting_enabled: ContextVar[bool] = ContextVar("collecting_enabled", default=False)
-
-
-class TraceCollector:
-    """Collects spans for a single task run."""
-
-    def __init__(self, task_run_id: str) -> None:
-        self.task_run_id = task_run_id
-        self.spans: list[ReadableSpan] = []
-        self._lock = threading.Lock()
-
-    def add_span(self, span: ReadableSpan) -> None:
-        """Thread-safe span addition."""
-        with self._lock:
-            self.spans.append(span)
-
-    def to_trace(self) -> Trace:
-        """Convert collected spans to a Trace object."""
-        from .exporters import HudSpan, _span_to_dict
-
-        trace = Trace()
-
-        # Convert spans to TraceSteps
-        for span in self.spans:
-            try:
-                # Use the same conversion logic as the exporter
-                span_dict = _span_to_dict(span)
-                hud_span = HudSpan.model_validate(span_dict)
-
-                # The attributes field is already a TraceStep
-                step = hud_span.attributes
-                # Add timing from the span itself
-                step.start_timestamp = hud_span.start_time
-                step.end_timestamp = hud_span.end_time
-                trace.append(step)
-
-            except Exception as e:
-                # Log but don't fail the whole trace
-                logger.debug("Failed to convert span: %s", e)
-
-        return trace
-
-
-class CollectingSpanExporter(SpanExporter):
-    """A span exporter that collects spans in memory for replay."""
-
-    def export(self, spans: list[ReadableSpan]) -> SpanExportResult:
-        """Collect spans if collection is enabled."""
-        if not _collecting_enabled.get():
-            return SpanExportResult.SUCCESS
-
-        for span in spans:
-            # Extract task_run_id from span
-            task_run_id = span.attributes.get("hud.task_run_id") if span.attributes else None
-            if not task_run_id or not isinstance(task_run_id, str):
-                continue
-
-            # Get or create collector
-            with _LOCK:
-                if task_run_id not in _TRACE_STORAGE:
-                    _TRACE_STORAGE[task_run_id] = TraceCollector(task_run_id)
-                collector = _TRACE_STORAGE[task_run_id]
-
-            # Add span
-            collector.add_span(span)
-
-        return SpanExportResult.SUCCESS
-
-    def shutdown(self) -> None:
-        """Clean up resources."""
-        with _LOCK:
-            _TRACE_STORAGE.clear()
-
-
-def enable_trace_collection(enabled: bool = True) -> None:
-    """Enable or disable in-memory trace collection."""
-    _collecting_enabled.set(enabled)
-
-
-def get_trace(task_run_id: str) -> Trace | None:
-    """Retrieve collected trace for a task run ID.
-
-    Returns None if no trace was collected or collection was disabled.
-    """
-    with _LOCK:
-        collector = _TRACE_STORAGE.get(task_run_id)
-        if collector:
-            return collector.to_trace()
-    return None
-
-
-def clear_trace(task_run_id: str) -> None:
-    """Clear collected trace for a task run ID."""
-    with _LOCK:
-        _TRACE_STORAGE.pop(task_run_id, None)
-
-
-def install_collector() -> None:
-    """Install the collecting span exporter.
-
-    This should be called after configure_telemetry().
-    """
-    provider = trace.get_tracer_provider()
-    # Guard for SDK tracer providers only
-    if hasattr(provider, "add_span_processor"):
-        from opentelemetry.sdk.trace.export import SimpleSpanProcessor
-
-        exporter = CollectingSpanExporter()
-        processor = SimpleSpanProcessor(exporter)
-        try:
-            provider.add_span_processor(processor)  # type: ignore[attr-defined]
-        except Exception:
-            logger.warning("Failed to add span processor")

hud/otel/config.py

@@ -1,181 +0,0 @@
-"""Central configuration for OpenTelemetry inside HUD SDK.
-
-This file is responsible for
-1. creating the global ``TracerProvider``
-2. attaching span processors (HUD enrichment, batch + exporter)
-3. activating the community MCP instrumentation so that *every* MCP
-   request/response/notification is traced automatically.
-
-It is *idempotent*: calling :func:`configure_telemetry` more than once
-returns the same provider and does nothing.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from opentelemetry import trace
-from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-from hud.settings import settings
-
-from .collector import enable_trace_collection, install_collector
-from .exporters import HudSpanExporter
-from .instrumentation import install_mcp_instrumentation
-from .processors import HudEnrichmentProcessor
-
-logger = logging.getLogger(__name__)
-
-# Global singleton provider so multiple calls do not create duplicates
-_TRACER_PROVIDER: TracerProvider | None = None
-
-
-def is_telemetry_configured() -> bool:
-    """Check if telemetry has been configured."""
-    return _TRACER_PROVIDER is not None
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
-def configure_telemetry(
-    *,
-    service_name: str = "hud-sdk",
-    service_version: str | None = None,
-    environment: str | None = None,
-    extra_resource_attributes: dict[str, Any] | None = None,
-    enable_otlp: bool = False,
-    otlp_endpoint: str | None = None,
-    otlp_headers: dict[str, str] | None = None,
-    enable_collection: bool = True,
-) -> TracerProvider:
-    """Initialise OpenTelemetry for the current Python process.
-
-    It is safe to call this in every entry-point; the provider will only
-    be created once.
-    """
-    global _TRACER_PROVIDER
-
-    if _TRACER_PROVIDER is not None:
-        return _TRACER_PROVIDER
-
-    # ------------------------------------------------------------------
-    # 1. Resource (identity of this service)
-    # ------------------------------------------------------------------
-    res_attrs: dict[str, Any] = {
-        "service.name": service_name,
-        "telemetry.sdk.name": "hud-otel",
-        "telemetry.sdk.language": "python",
-    }
-    if service_version:
-        res_attrs["service.version"] = service_version
-    if environment:
-        res_attrs["deployment.environment"] = environment
-    if extra_resource_attributes:
-        res_attrs.update(extra_resource_attributes)
-
-    resource = Resource.create(res_attrs)
-
-    # ------------------------------------------------------------------
-    # 2. Provider
-    # ------------------------------------------------------------------
-    provider = TracerProvider(resource=resource)
-    _TRACER_PROVIDER = provider
-
-    # ------------------------------------------------------------------
-    # 3. Processors / exporters
-    # ------------------------------------------------------------------
-    provider.add_span_processor(HudEnrichmentProcessor())
-
-    # HUD exporter (only if enabled and API key is available)
-    if settings.telemetry_enabled and settings.api_key:
-        exporter = HudSpanExporter(
-            telemetry_url=settings.hud_telemetry_url, api_key=settings.api_key
-        )
-        # Export more continuously to avoid big end flushes
-        provider.add_span_processor(
-            BatchSpanProcessor(
-                exporter,
-                schedule_delay_millis=1000,
-                max_queue_size=8192,
-                max_export_batch_size=256,
-                export_timeout_millis=30000,
-            )
-        )
-    elif settings.telemetry_enabled and not settings.api_key and not enable_otlp:
-        # Error if no exporters are configured
-        raise ValueError(
-            "No telemetry backend configured. Either:\n"
-            "1. Set HUD_API_KEY environment variable for HUD telemetry (https://hud.so)\n"
-            "2. Use enable_otlp=True with configure_telemetry() for alternative backends (e.g., Jaeger)\n"  # noqa: E501
-        )
-    elif not settings.telemetry_enabled:
-        logger.info("HUD telemetry disabled via HUD_TELEMETRY_ENABLED=false")
-
-    # OTLP exporter (optional - for standard OTel viewers)
-    if enable_otlp:
-        try:
-            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-
-            otlp_config = {}
-            if otlp_endpoint:
-                otlp_config["endpoint"] = otlp_endpoint
-                # Default to HTTP endpoint if not specified
-                if not otlp_endpoint.startswith(("http://", "https://")):
-                    otlp_config["endpoint"] = f"http://{otlp_endpoint}/v1/traces"
-            else:
-                # Default HTTP endpoint
-                otlp_config["endpoint"] = "http://localhost:4318/v1/traces"
-
-            if otlp_headers:
-                otlp_config["headers"] = otlp_headers
-
-            otlp_exporter = OTLPSpanExporter(**otlp_config)
-            provider.add_span_processor(
-                BatchSpanProcessor(
-                    otlp_exporter,
-                    schedule_delay_millis=1000,
-                    max_queue_size=8192,
-                    max_export_batch_size=256,
-                    export_timeout_millis=30000,
-                )
-            )
-            logger.info("OTLP HTTP exporter enabled - endpoint: %s", otlp_config["endpoint"])
-        except ImportError:
-            logger.warning(
-                "OTLP export requested but opentelemetry-exporter-otlp-proto-http not installed. "
-                "Install with: pip install 'hud-python[agent]'"
-            )
-
-    # ------------------------------------------------------------------
-    # 4. Activate provider and instrumentation
-    # ------------------------------------------------------------------
-    trace.set_tracer_provider(provider)
-    install_mcp_instrumentation(provider)
-
-    # Install in-memory collector if requested
-    if enable_collection:
-        install_collector()
-        enable_trace_collection(True)
-        logger.debug("In-memory trace collection enabled")
-
-    # Agent instrumentation now handled by @hud.instrument decorators
-    logger.debug("OpenTelemetry configuration completed")
-
-    logger.debug("OpenTelemetry configured (provider id=%s)", id(provider))
-    return provider
-
-
-def shutdown_telemetry() -> None:
-    """Flush and shutdown the global provider (if configured)."""
-    global _TRACER_PROVIDER
-    if _TRACER_PROVIDER is None:
-        return
-    _TRACER_PROVIDER.shutdown()  # type: ignore[arg-type]
-    _TRACER_PROVIDER = None
-    logger.debug("OpenTelemetry shutdown complete")