humex 0.2.0__py3-none-any.whl

humex/__init__.py

@@ -0,0 +1,50 @@
+"""humex — behavioral metrics for autonomous-vehicle and physical-AI scenarios.
+
+High-level Python APIs for:
+- Loading and preparing scenarios
+- Analyzing scenarios with metrics
+- Converting and computing metric DAGs
+- Natural language interaction via LLM
+
+See ``humex.api.core_apis`` for a comprehensive facade listing all public APIs
+with full signatures, parameter descriptions, and usage examples::
+
+    import humex.api.core_apis
+    help(humex.api.core_apis)
+
+    from humex.api.core_apis import (
+        analyze,
+        ScenarioAPI,
+        ConvertAnalyzerMetricsAPI,
+        ComputeAnalyzerMetricsAPI,
+    )
+"""
+
+from .api import (
+    Chat,
+    ScenarioAPI,
+    ConvertAnalyzerMetricsAPI,
+    ComputeAnalyzerMetricsAPI,
+)
+from .hmap import HMap, LaneMap, RoadMap, RoleTable, build_lane_map, build_role_table
+
+__version__ = "0.2.0"
+
+# Plugin-API version. Converter plugins may declare a ``MIN_HUMEX_API_VERSION``
+# class attr; the registry skips converters whose minimum exceeds this value
+# instead of letting an incompatible plugin crash the host. Bump on breaking
+# changes to BaseConverter / ConversionResult / registry contracts.
+__api_version__ = 1
+
+__all__ = [
+    "ScenarioAPI",
+    "ConvertAnalyzerMetricsAPI",
+    "ComputeAnalyzerMetricsAPI",
+    "Chat",
+    "HMap",
+    "LaneMap",
+    "RoadMap",
+    "RoleTable",
+    "build_lane_map",
+    "build_role_table",
+]

humex/api/__init__.py

@@ -0,0 +1,28 @@
+"""High-level API for humex framework.
+
+This module provides convenient Python functions and classes for analyzing scenarios,
+loading scenarios, converting metrics configs, and interacting with humex via natural language.
+
+Classes:
+- ScenarioAPI: Load scenarios from various sources
+- ConvertAnalyzerMetricsAPI: Convert analyzer configs to DAG format
+- ComputeAnalyzerMetricsAPI: End-to-end metrics computation
+- Chat: LLM chat interface
+- TranslateMetrics: Natural language to metrics config translator
+
+Functions (for backward compatibility):
+- chat(): Functional chat interface
+- translate_metrics(): Functional metrics translation interface
+"""
+
+from .scenario_api import ScenarioAPI
+from .metrics_api import ConvertAnalyzerMetricsAPI, ComputeAnalyzerMetricsAPI
+from .ai_api import Chat, TranslateMetrics
+
+__all__ = [
+    'ScenarioAPI',
+    'ConvertAnalyzerMetricsAPI',
+    'ComputeAnalyzerMetricsAPI',
+    'Chat',
+    'TranslateMetrics',
+]

humex/api/ai_api/__init__.py

@@ -0,0 +1,18 @@
+"""AI API module providing LLM integration with pluggable model support.
+
+This module provides interfaces to various AI models (currently Claude via Claude CLI)
+for tasks like chat interactions and metrics requirement translation.
+
+Classes:
+- Chat: Class-based chat interface
+- TranslateMetrics: Class-based metrics translation interface
+
+Functions (for backward compatibility):
+- chat(): Functional chat interface
+- translate_metrics(): Functional metrics translation interface
+"""
+
+from humex.api.ai_api.chat import Chat
+from humex.api.ai_api.translate_metrics import TranslateMetrics
+
+__all__ = ["Chat", "TranslateMetrics"]

humex/api/ai_api/chat.py

@@ -0,0 +1,91 @@
+"""Chat API for humex framework interactions."""
+
+from typing import Optional
+
+from humex.api.ai_api.models._claude_cli import ClaudeCLIModel
+from humex.api.ai_api.models._qwen import QwenModel
+
+
+class Chat:
+    """Chat interface for humex-related queries.
+
+    Provides a conversational interface for asking questions and getting advice
+    about humex framework, scenarios, metrics, and analysis.
+    """
+
+    def __init__(self, model: str = "claude_cli", qwen_model: Optional[str] = None):
+        """Initialize Chat with specified model.
+
+        Args:
+            model: Model to use for chat. Supports "claude_cli" (default) or "qwen".
+            qwen_model: Ollama model name when using "qwen" (default: "qwen2.5:0.5b").
+                       Examples: "qwen2.5:0.5b", "qwen2.5:7b", "qwen2.5-coder:7b"
+
+        Raises:
+            ValueError: If an unsupported model is specified
+        """
+        if model not in ("claude_cli", "qwen"):
+            raise ValueError(
+                f"Unsupported model: {model}. Supported models: 'claude_cli', 'qwen'"
+            )
+        self.model = model
+        self._qwen_instance = QwenModel(qwen_model) if model == "qwen" else None
+
+    def send(self, message: str, context: Optional[str] = None) -> str:
+        """Send a chat message and get a response.
+
+        Args:
+            message: User's question or message
+            context: Optional context about what the user is working on
+                    (e.g., "scenario analysis", "metric configuration")
+
+        Returns:
+            Plain text response string from the selected model
+
+        Raises:
+            FileNotFoundError: If Claude CLI is not installed (when using claude_cli)
+            Exception: If the model call fails
+
+        Example:
+            >>> chat_api = Chat()
+            >>> response = chat_api.send("How do I analyze a scenario?")
+            >>> print(response)
+            # Returns helpful response about analyzing scenarios
+
+            >>> response = chat_api.send("What metrics should I track?", context="vehicle safety")
+            >>> print(response)
+            # Returns response tailored to vehicle safety metrics
+        """
+        if self.model == "claude_cli":
+            return ClaudeCLIModel.chat(message, context)
+        elif self.model == "qwen":
+            return self._qwen_instance.chat(message, context)
+        else:
+            raise ValueError(
+                f"Unsupported model: {self.model}. Supported models: 'claude_cli', 'qwen'"
+            )
+
+
+# Convenience function for backward compatibility
+def chat(
+    message: str,
+    model: str = "claude_cli",
+    context: Optional[str] = None,
+    qwen_model: Optional[str] = None
+) -> str:
+    """Convenience function for chat interactions.
+
+    This function provides backward compatibility with the functional API.
+    For new code, consider using the Chat class directly.
+
+    Args:
+        message: User's question or message
+        model: Model to use for chat (default: "claude_cli"). Supports "claude_cli" or "qwen".
+        context: Optional context about what the user is working on
+        qwen_model: Ollama model name when using "qwen" (default: "qwen2.5:0.5b")
+
+    Returns:
+        Plain text response string from the selected model
+    """
+    chat_api = Chat(model=model, qwen_model=qwen_model)
+    return chat_api.send(message, context=context)

humex/api/ai_api/models/__init__.py

@@ -0,0 +1,6 @@
+"""AI model implementations."""
+
+from humex.api.ai_api.models._claude_cli import ClaudeCLIModel
+from humex.api.ai_api.models._qwen import QwenModel
+
+__all__ = ["ClaudeCLIModel", "QwenModel"]

humex/api/ai_api/models/_claude_cli.py

@@ -0,0 +1,109 @@
+"""Claude CLI model implementation for AI API."""
+
+import subprocess
+from typing import Optional
+
+
+class ClaudeCLIModel:
+    """Interface to Claude AI via Claude Code CLI.
+
+    This class provides methods to interact with Claude through the Claude Code CLI.
+    It handles subprocess management, error handling, and response parsing.
+    """
+
+    @staticmethod
+    def _call_claude(prompt: str) -> str:
+        """Call Claude CLI with a prompt and return the response.
+
+        Args:
+            prompt: The full prompt to send to Claude (including system instructions if needed)
+
+        Returns:
+            The text response from Claude
+
+        Raises:
+            FileNotFoundError: If Claude CLI is not installed
+            subprocess.CalledProcessError: If the Claude CLI command fails
+        """
+        try:
+            result = subprocess.run(
+                ["claude", "--print", prompt],
+                capture_output=True,
+                text=True,
+                stdin=subprocess.DEVNULL,
+                timeout=120
+            )
+
+            if result.returncode != 0:
+                error_msg = result.stderr if result.stderr else result.stdout
+                raise subprocess.CalledProcessError(
+                    result.returncode,
+                    "claude --print",
+                    output=result.stdout,
+                    stderr=result.stderr
+                )
+
+            return result.stdout.strip()
+
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                "Claude CLI not found. Please ensure Claude Code CLI is installed and available in PATH. "
+                "Install with: npm install -g @anthropic-ai/claude"
+            )
+
+    @classmethod
+    def chat(cls, message: str, context: Optional[str] = None) -> str:
+        """Send a chat message to Claude and get a response.
+
+        Args:
+            message: User's question or message
+            context: Optional context about what the user is working on
+
+        Returns:
+            Plain text response from Claude
+
+        Raises:
+            FileNotFoundError: If Claude CLI is not installed
+            Exception: If Claude CLI call fails
+        """
+        context_msg = ""
+        if context:
+            context_msg = f"(Context: {context}) "
+
+        prompt = f"{context_msg}{message}"
+
+        try:
+            reply = cls._call_claude(prompt)
+            return reply
+        except Exception as e:
+            raise Exception(f"Chat failed: {str(e)}")
+
+    @classmethod
+    def translate_metrics(cls, prompt: str) -> str:
+        """Translate requirement to metrics YAML configuration using a complete prompt.
+
+        This method accepts a full prompt that combines system knowledge with user requirements.
+        The prompt should be properly formatted and include all necessary context about
+        monitors, operators, and DAG structure.
+
+        Args:
+            prompt: Complete prompt for translation, combining system context and user requirement
+
+        Returns:
+            YAML formatted string containing the configuration. Can be directly used
+            with humex's analyzer or logic systems.
+
+        Raises:
+            FileNotFoundError: If Claude CLI is not installed
+            Exception: If Claude CLI call fails
+        """
+        try:
+            yaml_config = cls._call_claude(prompt)
+            return yaml_config
+        except Exception as e:
+            raise Exception(f"Failed to translate requirement: {str(e)}")
+
+
+if __name__=='__main__':
+    x = ClaudeCLIModel.chat(message="hi, what question did i just ask you")
+    print(x)

humex/api/ai_api/models/_qwen.py

@@ -0,0 +1,124 @@
+"""Qwen model implementation for AI API via local Ollama.
+
+The Ollama endpoint defaults to ``http://localhost:11434``. Override with the
+``HUMEX_LLM_BASE_URL`` env var to point at a remote Ollama instance.
+"""
+
+import os
+import requests
+from typing import Optional
+
+
+class QwenModel:
+    """Interface to Qwen AI via local Ollama API.
+
+    This class provides methods to interact with Qwen through a locally running
+    Ollama server. It handles HTTP requests, error handling, and response parsing.
+    """
+
+    BASE_URL = os.environ.get("HUMEX_LLM_BASE_URL", "http://localhost:11434")
+    DEFAULT_MODEL = "qwen2.5:0.5b"
+
+    def __init__(self, model_name: Optional[str] = None):
+        """Initialize QwenModel with specified model.
+
+        Args:
+            model_name: Ollama model name to use (default: "qwen2.5:0.5b").
+                       Examples: "qwen2.5:0.5b", "qwen2.5:7b", "qwen2.5-coder:7b"
+        """
+        self.model_name = model_name or self.DEFAULT_MODEL
+
+    def _call_qwen(self, prompt: str) -> str:
+        """Call Qwen via Ollama HTTP API and return the response.
+
+        Args:
+            prompt: The full prompt to send to Qwen (including system instructions if needed)
+
+        Returns:
+            The text response from Qwen
+
+        Raises:
+            ConnectionError: If cannot connect to Ollama server
+            requests.exceptions.RequestException: If the API request fails
+        """
+        url = f"{self.BASE_URL}/api/generate"
+        payload = {
+            "model": self.model_name,
+            "prompt": prompt,
+            "stream": False,
+        }
+
+        try:
+            response = requests.post(url, json=payload, timeout=120)
+            response.raise_for_status()
+
+            result = response.json()
+            return result.get("response", "").strip()
+
+        except requests.exceptions.ConnectionError:
+            raise ConnectionError(
+                f"Cannot connect to Ollama server at {QwenModel.BASE_URL}. "
+                "Please ensure Ollama is running with: ollama serve"
+            )
+        except requests.exceptions.Timeout:
+            raise TimeoutError(
+                f"Request to Qwen timed out after 120 seconds. "
+                "The model may be overloaded or the prompt too complex."
+            )
+
+    def chat(self, message: str, context: Optional[str] = None) -> str:
+        """Send a chat message to Qwen and get a response.
+
+        Args:
+            message: User's question or message
+            context: Optional context about what the user is working on
+
+        Returns:
+            Plain text response from Qwen
+
+        Raises:
+            ConnectionError: If cannot connect to Ollama server
+            Exception: If Qwen API call fails
+        """
+        context_msg = ""
+        if context:
+            context_msg = f"(Context: {context}) "
+
+        prompt = f"{context_msg}{message}"
+
+        try:
+            reply = self._call_qwen(prompt)
+            return reply
+        except Exception as e:
+            raise Exception(f"Chat failed: {str(e)}")
+
+    def translate_metrics(self, prompt: str) -> str:
+        """Translate requirement to metrics YAML configuration using a complete prompt.
+
+        This method accepts a full prompt that combines system knowledge with user requirements.
+        The prompt should be properly formatted and include all necessary context about
+        monitors, operators, and DAG structure.
+
+        Args:
+            prompt: Complete prompt for translation, combining system context and user requirement
+
+        Returns:
+            YAML formatted string containing the configuration. Can be directly used
+            with humex's analyzer or logic systems.
+
+        Raises:
+            ConnectionError: If cannot connect to Ollama server
+            Exception: If Qwen API call fails
+        """
+        try:
+            yaml_config = self._call_qwen(prompt)
+            return yaml_config
+        except Exception as e:
+            raise Exception(f"Failed to translate requirement: {str(e)}")
+
+
+
+if __name__ == '__main__':
+    model = QwenModel()
+    response = model.chat("Hello, world!")
+    print(response)

humex/api/ai_api/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Prompt templates for AI API LLM interactions.
+
+This module contains system prompts that provide context to LLMs about humex
+metrics system, including monitors, operators, and DAG structures.
+"""