oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/{integrations → api/integrations}/llm.py

@@ -7,7 +7,7 @@ analysis and assistance.
 Examples:
     Basic usage with auto-selection:
 
-    >>> from oscura.integrations import llm
+    >>> from oscura.api.integrations import llm
     >>> client = llm.get_client()  # Auto-selects available provider
     >>> response = client.chat_completion("What is signal rise time?")
 
@@ -428,7 +428,7 @@ class LLMIntegration:
         try:
             provider_enum = LLMProvider(provider.lower())
         except ValueError:
-            raise LLMError(f"Unknown provider: {provider}")  # noqa: B904
+            raise LLMError(f"Unknown provider: {provider}")
 
         self.config = LLMConfig(
             provider=provider_enum,
@@ -482,11 +482,9 @@ class LLMIntegration:
             LLMError: If OpenAI package not available or configuration invalid
         """
         try:
-            import openai  # type: ignore[import-not-found]
+            import openai  # type: ignore[import-not-found]  # noqa: F401
         except ImportError:
-            raise LLMError(  # noqa: B904
-                "OpenAI package not installed. Install with: pip install openai"
-            )
+            raise LLMError("OpenAI package not installed. Install with: pip install openai")
 
         if not self.config.api_key:
             raise LLMError("OpenAI API key required")
@@ -506,11 +504,9 @@ class LLMIntegration:
             LLMError: If Anthropic package not available or configuration invalid
         """
         try:
-            import anthropic  # type: ignore[import-not-found]
+            import anthropic  # type: ignore[import-not-found]  # noqa: F401
         except ImportError:
-            raise LLMError(  # noqa: B904
-                "Anthropic package not installed. Install with: pip install anthropic"
-            )
+            raise LLMError("Anthropic package not installed. Install with: pip install anthropic")
 
         if not self.config.api_key:
             raise LLMError("Anthropic API key required")
@@ -620,7 +616,7 @@ class LLMIntegration:
 
         except Exception as e:
             self.trigger_hook(AnalysisHook.ON_ERROR, trace, question, e)
-            raise LLMError(f"LLM analysis failed: {e}")  # noqa: B904
+            raise LLMError(f"LLM analysis failed: {e}")
 
     def explain(self, measurement: Any) -> str:
         """Explain a measurement result.
@@ -663,13 +659,11 @@ class OpenAIClient:
 
         # Import and initialize OpenAI client
         try:
-            import openai  # type: ignore[ignore-without-code]
+            import openai
 
             self._openai = openai
         except ImportError:
-            raise LLMError(  # noqa: B904
-                "OpenAI package not installed. Install with: pip install openai"
-            )
+            raise LLMError("OpenAI package not installed. Install with: pip install openai")
 
         # Get API key from config or environment
         api_key = config.api_key or os.environ.get("OPENAI_API_KEY")
@@ -746,25 +740,25 @@ class OpenAIClient:
                     wait_time = 2**attempt
                     time.sleep(wait_time)
                     continue
-                raise LLMError(f"OpenAI rate limit exceeded: {e}")  # noqa: B904
+                raise LLMError(f"OpenAI rate limit exceeded: {e}")
 
             except self._openai.APITimeoutError as e:
                 last_exception = e
                 if attempt < self.config.max_retries - 1:
                     time.sleep(1)
                     continue
-                raise LLMError(f"OpenAI request timeout: {e}")  # noqa: B904
+                raise LLMError(f"OpenAI request timeout: {e}")
 
             except self._openai.APIError as e:
                 last_exception = e
                 if attempt < self.config.max_retries - 1:
                     time.sleep(1)
                     continue
-                raise LLMError(f"OpenAI API error: {e}")  # noqa: B904
+                raise LLMError(f"OpenAI API error: {e}")
 
             except Exception as e:
                 last_exception = e
-                raise LLMError(f"OpenAI request failed: {e}")  # noqa: B904
+                raise LLMError(f"OpenAI request failed: {e}")
 
         raise LLMError(
             f"OpenAI request failed after {self.config.max_retries} retries: {last_exception}"
@@ -967,6 +961,77 @@ class OpenAIClient:
         return response.answer
 
 
+def _convert_anthropic_messages(
+    messages: list[dict[str, str]], system: str | None
+) -> tuple[list[dict[str, str]], str | None]:
+    """Convert messages to Anthropic format (separate system from user messages).
+
+    Args:
+        messages: Original messages with mixed roles.
+        system: Optional system prompt.
+
+    Returns:
+        Tuple of (user_messages, system_message).
+    """
+    user_messages = []
+    system_message = system
+
+    for msg in messages:
+        if msg["role"] == "system" and not system_message:
+            system_message = msg["content"]
+        elif msg["role"] in ["user", "assistant"]:
+            user_messages.append(msg)
+
+    return (user_messages, system_message)
+
+
+def _extract_anthropic_answer(response: Any) -> str:
+    """Extract text answer from Anthropic response.
+
+    Args:
+        response: Anthropic API response.
+
+    Returns:
+        Concatenated text from all content blocks.
+    """
+    answer = ""
+    for block in response.content:
+        if hasattr(block, "text"):
+            answer += block.text
+    return answer
+
+
+def _build_anthropic_response(response: Any, answer: str, estimated_cost: float) -> LLMResponse:
+    """Build LLMResponse from Anthropic API response.
+
+    Args:
+        response: Anthropic API response.
+        answer: Extracted answer text.
+        estimated_cost: Estimated API cost.
+
+    Returns:
+        LLMResponse with metadata.
+    """
+    return LLMResponse(
+        answer=answer,
+        confidence=None,  # Anthropic doesn't provide confidence scores
+        suggested_commands=[],
+        metadata={
+            "model": response.model,
+            "usage": {
+                "input_tokens": response.usage.input_tokens,
+                "output_tokens": response.usage.output_tokens,
+            },
+            "stop_reason": response.stop_reason,
+        },
+        raw_response={
+            "id": response.id,
+            "type": response.type,
+        },
+        estimated_cost=estimated_cost,
+    )
+
+
 class AnthropicClient:
     """Anthropic client implementation.
 
@@ -991,13 +1056,11 @@ class AnthropicClient:
 
         # Import and initialize Anthropic client
         try:
-            import anthropic  # type: ignore[ignore-without-code]
+            import anthropic
 
             self._anthropic = anthropic
         except ImportError:
-            raise LLMError(  # noqa: B904
-                "Anthropic package not installed. Install with: pip install anthropic"
-            )
+            raise LLMError("Anthropic package not installed. Install with: pip install anthropic")
 
         # Get API key from config or environment
         api_key = config.api_key or os.environ.get("ANTHROPIC_API_KEY")
@@ -1030,100 +1093,138 @@ class AnthropicClient:
         """
         self.rate_limiter.acquire()
 
-        # Convert messages format (filter out system messages for Anthropic)
-        user_messages = []
-        system_message = system
-        for msg in messages:
-            if msg["role"] == "system" and not system_message:
-                system_message = msg["content"]
-            elif msg["role"] in ["user", "assistant"]:
-                user_messages.append(msg)
+        # Convert messages format for Anthropic
+        user_messages, system_message = _convert_anthropic_messages(messages, system)
 
+        # Retry loop with exponential backoff
         last_exception = None
         for attempt in range(self.config.max_retries):
             try:
-                # Build request parameters
-                request_params = {
-                    "model": self.config.model,
-                    "messages": user_messages,
-                    "max_tokens": kwargs.get("max_tokens", 1024),
-                }
-                if system_message:
-                    request_params["system"] = system_message
+                # Build and send request
+                response = self._send_anthropic_request(user_messages, system_message, kwargs)
 
-                # Add any additional kwargs
-                for key in ["temperature", "top_p", "top_k"]:
-                    if key in kwargs:
-                        request_params[key] = kwargs[key]
+                # Extract answer from response
+                answer = _extract_anthropic_answer(response)
 
-                response = self.client.messages.create(**request_params)
-
-                # Extract response content
-                answer = ""
-                for block in response.content:
-                    if hasattr(block, "text"):
-                        answer += block.text
-
-                # Track costs./API-020
-                input_tokens = response.usage.input_tokens
-                output_tokens = response.usage.output_tokens
-                estimated_cost = 0.0
+                # Track token usage and costs
+                estimated_cost = self._track_anthropic_costs(response)
 
-                if self.config.track_costs:
-                    estimated_cost = _global_cost_tracker.record(
-                        response.model, input_tokens, output_tokens
-                    )
-
-                return LLMResponse(
-                    answer=answer,
-                    confidence=None,  # Anthropic doesn't provide confidence scores
-                    suggested_commands=[],
-                    metadata={
-                        "model": response.model,
-                        "usage": {
-                            "input_tokens": input_tokens,
-                            "output_tokens": output_tokens,
-                        },
-                        "stop_reason": response.stop_reason,
-                    },
-                    raw_response={
-                        "id": response.id,
-                        "type": response.type,
-                    },
-                    estimated_cost=estimated_cost,
-                )
+                # Build and return LLM response
+                return _build_anthropic_response(response, answer, estimated_cost)
 
             except self._anthropic.RateLimitError as e:
                 last_exception = e
-                if attempt < self.config.max_retries - 1:
-                    # Exponential backoff for rate limits
-                    wait_time = 2**attempt
-                    time.sleep(wait_time)
-                    continue
-                raise LLMError(f"Anthropic rate limit exceeded: {e}")  # noqa: B904
+                if not self._handle_rate_limit_retry(attempt):
+                    raise LLMError(f"Anthropic rate limit exceeded: {e}")
 
             except self._anthropic.APITimeoutError as e:
                 last_exception = e
-                if attempt < self.config.max_retries - 1:
-                    time.sleep(1)
-                    continue
-                raise LLMError(f"Anthropic request timeout: {e}")  # noqa: B904
+                if not self._handle_timeout_retry(attempt):
+                    raise LLMError(f"Anthropic request timeout: {e}")
 
             except self._anthropic.APIError as e:
                 last_exception = e
-                if attempt < self.config.max_retries - 1:
-                    time.sleep(1)
-                    continue
-                raise LLMError(f"Anthropic API error: {e}")  # noqa: B904
+                if not self._handle_api_error_retry(attempt):
+                    raise LLMError(f"Anthropic API error: {e}")
 
             except Exception as e:
                 last_exception = e
-                raise LLMError(f"Anthropic request failed: {e}")  # noqa: B904
+                raise LLMError(f"Anthropic request failed: {e}")
 
         raise LLMError(
             f"Anthropic request failed after {self.config.max_retries} retries: {last_exception}"
         )
 
+    def _send_anthropic_request(
+        self,
+        user_messages: list[dict[str, str]],
+        system_message: str | None,
+        kwargs: dict[str, Any],
+    ) -> Any:
+        """Send request to Anthropic API.
+
+        Args:
+            user_messages: Filtered user/assistant messages.
+            system_message: System prompt.
+            kwargs: Additional API parameters.
+
+        Returns:
+            Anthropic API response.
+        """
+        request_params = {
+            "model": self.config.model,
+            "messages": user_messages,
+            "max_tokens": kwargs.get("max_tokens", 1024),
+        }
+        if system_message:
+            request_params["system"] = system_message
+
+        # Add optional parameters
+        for key in ["temperature", "top_p", "top_k"]:
+            if key in kwargs:
+                request_params[key] = kwargs[key]
+
+        return self.client.messages.create(**request_params)
+
+    def _track_anthropic_costs(self, response: Any) -> float:
+        """Track token usage and return estimated cost.
+
+        Args:
+            response: Anthropic API response.
+
+        Returns:
+            Estimated cost in USD.
+        """
+        input_tokens = response.usage.input_tokens
+        output_tokens = response.usage.output_tokens
+
+        if self.config.track_costs:
+            return _global_cost_tracker.record(response.model, input_tokens, output_tokens)
+        return 0.0
+
+    def _handle_rate_limit_retry(self, attempt: int) -> bool:
+        """Handle rate limit error with exponential backoff.
+
+        Args:
+            attempt: Current attempt number.
+
+        Returns:
+            True if should continue retry, False if should raise.
+        """
+        if attempt < self.config.max_retries - 1:
+            wait_time = 2**attempt
+            time.sleep(wait_time)
+            return True
+        return False
+
+    def _handle_timeout_retry(self, attempt: int) -> bool:
+        """Handle timeout error with retry.
+
+        Args:
+            attempt: Current attempt number.
+
+        Returns:
+            True if should continue retry, False if should raise.
+        """
+        if attempt < self.config.max_retries - 1:
+            time.sleep(1)
+            return True
+        return False
+
+    def _handle_api_error_retry(self, attempt: int) -> bool:
+        """Handle API error with retry.
+
+        Args:
+            attempt: Current attempt number.
+
+        Returns:
+            True if should continue retry, False if should raise.
+        """
+        if attempt < self.config.max_retries - 1:
+            time.sleep(1)
+            return True
+        return False
+
     def analyze_trace(self, trace: Any, question: str) -> LLMResponse:
         """Analyze trace with question.
 
@@ -1384,9 +1485,7 @@ def get_provider(name: str, **config_kwargs: Any) -> LLMClient:
     try:
         provider_enum = LLMProvider(name.lower())
     except ValueError:
-        raise LLMError(  # noqa: B904
-            f"Unknown provider: {name}. Available: {[p.value for p in LLMProvider]}"
-        )
+        raise LLMError(f"Unknown provider: {name}. Available: {[p.value for p in LLMProvider]}")
 
     # Build config with sensible defaults
     config = LLMConfig(
@@ -1416,7 +1515,7 @@ def get_provider(name: str, **config_kwargs: Any) -> LLMClient:
             )
     except ImportError as e:
         # .: Graceful degradation when API unavailable
-        raise LLMError(  # noqa: B904
+        raise LLMError(
             f"Provider {name} unavailable: {e}. "
             "Install the required package or use 'local' provider."
         )
@@ -1668,7 +1767,7 @@ class FailoverLLMClient:
         def operation(client: LLMClient) -> str:
             if hasattr(client, "chat_completion"):
                 messages = [{"role": "user", "content": prompt}]
-                response = client.chat_completion(messages, **kwargs)  # type: ignore[ignore-without-code]
+                response = client.chat_completion(messages, **kwargs)
                 return response.answer  # type: ignore[no-any-return]
             else:
                 response = client.query(prompt, {})
@@ -1697,7 +1796,7 @@ class FailoverLLMClient:
             trace = DictTrace(trace_data)
 
             if hasattr(client, "analyze_trace"):
-                response = client.analyze_trace(trace, "Analyze this signal")  # type: ignore[ignore-without-code]
+                response = client.analyze_trace(trace, "Analyze this signal")
             else:
                 response = client.analyze(trace, "Analyze this signal")
 
@@ -1729,7 +1828,7 @@ class FailoverLLMClient:
             trace = CharTrace(signal_characteristics)
 
             if hasattr(client, "suggest_measurements"):
-                response = client.suggest_measurements(trace)  # type: ignore[ignore-without-code]
+                response = client.suggest_measurements(trace)
             else:
                 response = client.analyze(trace, "What measurements should I perform?")
 
@@ -1795,7 +1894,7 @@ def is_provider_available(provider: str) -> bool:
         if not os.environ.get("OPENAI_API_KEY"):
             return False
         try:
-            import openai  # type: ignore[ignore-without-code]
+            import openai  # noqa: F401
 
             return True
         except ImportError:
@@ -1805,7 +1904,7 @@ def is_provider_available(provider: str) -> bool:
         if not os.environ.get("ANTHROPIC_API_KEY"):
             return False
         try:
-            import anthropic  # type: ignore[ignore-without-code]
+            import anthropic  # noqa: F401
 
             return True
         except ImportError:

oscura/api/operators.py

@@ -46,7 +46,7 @@ class TimeIndex:
     """
 
     # Time unit multipliers to seconds
-    TIME_UNITS = {  # noqa: RUF012
+    TIME_UNITS = {
         "s": 1.0,
         "ms": 1e-3,
         "us": 1e-6,
@@ -212,7 +212,7 @@ class UnitConverter:
     """
 
     # SI prefixes
-    SI_PREFIXES = {  # noqa: RUF012
+    SI_PREFIXES = {
         "P": 1e15,  # peta
         "T": 1e12,  # tera
         "G": 1e9,  # giga
@@ -227,7 +227,7 @@ class UnitConverter:
     }
 
     # Base units
-    BASE_UNITS = {  # noqa: RUF012
+    BASE_UNITS = {
         "V": "voltage",
         "A": "current",
         "W": "power",