thinkhive 4.2.0__tar.gz → 4.2.2__tar.gz

{thinkhive-4.2.0 → thinkhive-4.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thinkhive
-Version: 4.2.0
+Version: 4.2.2
 Summary: AI agent observability SDK with business metrics, ROI analytics, and 25+ trace format support
 Home-page: https://github.com/Abdul-Omira/ThinkHiveMind
 Author: ThinkHive
@@ -30,7 +30,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# ThinkHive Python SDK v4.2.0
+# ThinkHive Python SDK v4.2.1
 
 OpenTelemetry-based observability SDK for AI agents supporting 25 trace formats including LangSmith, Langfuse, Opik, Braintrust, Datadog, MLflow, and more.
 
@@ -53,7 +53,7 @@ thinkhive.init(
 )
 
 # Trace LLM calls
-@thinkhive.trace_llm(model_name="gpt-4", provider="openai")
+@thinkhive.trace_llm(name="generate-response", model_name="gpt-4", provider="openai")
 def call_llm(prompt):
     response = openai.chat.completions.create(
         model="gpt-4",
@@ -62,13 +62,13 @@ def call_llm(prompt):
     return response
 
 # Trace retrieval operations
-@thinkhive.trace_retrieval()
+@thinkhive.trace_retrieval(name="search-kb", query="refund policy")
 def search_documents(query):
     results = vector_db.search(query)
     return results
 
 # Trace tool calls
-@thinkhive.trace_tool(tool_name="web_search")
+@thinkhive.trace_tool(name="lookup-order", tool_name="web_search")
 def search_web(query):
     return requests.get(f"https://api.example.com/search?q={query}")
 ```
@@ -317,7 +317,7 @@ result = api_keys.create(
 print(f"Key: {result['key']}")  # Only shown once!
 
 # List all keys
-keys = api_keys.list_keys()
+keys = api_keys.list()  # or api_keys.list_keys()
 
 # Revoke a key
 api_keys.revoke("key-id")
@@ -433,7 +433,7 @@ from thinkhive import (
 try:
     result = runs.create(agent_id="agent-123", ...)
 except RateLimitError as e:
-    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
+    print(f"Rate limited. Retry after {e.retry_after}ms")  # or e.retry_after_ms
 except AgentScopeError as e:
     print(f"No access to agent. Allowed: {e.allowed_agents}")
 except NotFoundError as e:
@@ -511,7 +511,7 @@ print(f"Estimated cost: {cost['estimatedCredits']} credits")
 from thinkhive.api import signals
 
 # List all signals
-all_signals = signals.list_signals()
+all_signals = signals.list()  # or signals.list_signals()
 
 # Create a custom signal
 signals.create(
@@ -540,7 +540,8 @@ notifications.create_rule({
 })
 
 # List notifications
-alerts = notifications.list_notifications("agent-123", unread_only=True)
+alerts = notifications.list("agent-123", unread_only=True)
+# or: notifications.list_notifications("agent-123", unread_only=True)
 ```
 
 ## Documents (RAG)
@@ -552,7 +553,7 @@ from thinkhive.api import documents
 documents.upload("agent-123", file_name="faq.txt", file_type="text/plain", file_size=1024)
 
 # List documents
-docs = documents.list_documents("agent-123")
+docs = documents.list("agent-123")  # or documents.list_documents("agent-123")
 ```
 
 ## Shadow Tests
@@ -576,7 +577,8 @@ shadow_tests.create(
 from thinkhive.api import sessions
 
 # List conversation sessions
-all_sessions = sessions.list_sessions("agent-123", limit=20)
+all_sessions = sessions.list("agent-123", limit=20)
+# or: sessions.list_sessions("agent-123", limit=20)
 
 # Get all traces in a session
 traces = sessions.get_session_traces("session-789", "agent-123")
@@ -601,7 +603,8 @@ from thinkhive.api import llm_costs
 from thinkhive import format_cost
 
 # Get cost summary
-summary = llm_costs.get_summary(period="30d")
+summary = llm_costs.summary(period="30d")
+# or: llm_costs.get_summary(period="30d")
 print(f"Total cost: {format_cost(summary.get('totalCost', 0))}")
 
 # Get per-agent breakdown
@@ -625,6 +628,32 @@ savings = llm_costs.get_savings()
 
 ## Upgrading
 
+### v4.2.0 → v4.2.1
+
+Improvements in v4.2.1:
+- **Decorators** now accept `name=` parameter for custom span names (`@trace_llm(name="my-llm")`)
+- **`configure()`** now accepts `service_name` parameter
+- **`RateLimitError`** has `retry_after` alias (in addition to `retry_after_ms`)
+- **Rule helpers** (`create_regex_rule`, etc.) now return named rule objects with `{type, name, config}` structure
+- **`calculate_pass_at_k`** now supports both `(pass_rate, k)` and `(n, c, k)` calling conventions
+- **`aggregate_worst`** / **`aggregate_average`** accept simple `[float]` lists in addition to `[dict]`
+- **Method aliases added** for cross-SDK consistency:
+  - `runs.list()` / `runs.delete()`
+  - `calibration.status()` / `calibration.all_metrics()`
+  - `signals.list()` / `signals.delete()`
+  - `api_keys.list()`
+  - `linking.create()` / `linking.get_for_run()` / `linking.stats()` / `linking.verify()` / `linking.delete()`
+  - `roi_analytics.summary()` / `roi_analytics.correlations()`
+  - `business_metrics.current()` / `business_metrics.history()` / `business_metrics.record()`
+  - `quality_metrics.evaluate()`
+  - `llm_costs.summary()`
+  - `notifications.list()`
+  - `documents.list()` / `documents.delete()`
+  - `shadow_tests.list()`
+  - `sessions.list()`
+  - `customer_context.capture()`
+  - `guardrails.evaluate()`
+
 ### v4.1.0 → v4.2.0
 
 New in v4.2.0:

{thinkhive-4.2.0 → thinkhive-4.2.2}/README.md

@@ -1,4 +1,4 @@
-# ThinkHive Python SDK v4.2.0
+# ThinkHive Python SDK v4.2.1
 
 OpenTelemetry-based observability SDK for AI agents supporting 25 trace formats including LangSmith, Langfuse, Opik, Braintrust, Datadog, MLflow, and more.
 
@@ -21,7 +21,7 @@ thinkhive.init(
 )
 
 # Trace LLM calls
-@thinkhive.trace_llm(model_name="gpt-4", provider="openai")
+@thinkhive.trace_llm(name="generate-response", model_name="gpt-4", provider="openai")
 def call_llm(prompt):
     response = openai.chat.completions.create(
         model="gpt-4",
@@ -30,13 +30,13 @@ def call_llm(prompt):
     return response
 
 # Trace retrieval operations
-@thinkhive.trace_retrieval()
+@thinkhive.trace_retrieval(name="search-kb", query="refund policy")
 def search_documents(query):
     results = vector_db.search(query)
     return results
 
 # Trace tool calls
-@thinkhive.trace_tool(tool_name="web_search")
+@thinkhive.trace_tool(name="lookup-order", tool_name="web_search")
 def search_web(query):
     return requests.get(f"https://api.example.com/search?q={query}")
 ```
@@ -285,7 +285,7 @@ result = api_keys.create(
 print(f"Key: {result['key']}")  # Only shown once!
 
 # List all keys
-keys = api_keys.list_keys()
+keys = api_keys.list()  # or api_keys.list_keys()
 
 # Revoke a key
 api_keys.revoke("key-id")
@@ -401,7 +401,7 @@ from thinkhive import (
 try:
     result = runs.create(agent_id="agent-123", ...)
 except RateLimitError as e:
-    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
+    print(f"Rate limited. Retry after {e.retry_after}ms")  # or e.retry_after_ms
 except AgentScopeError as e:
     print(f"No access to agent. Allowed: {e.allowed_agents}")
 except NotFoundError as e:
@@ -479,7 +479,7 @@ print(f"Estimated cost: {cost['estimatedCredits']} credits")
 from thinkhive.api import signals
 
 # List all signals
-all_signals = signals.list_signals()
+all_signals = signals.list()  # or signals.list_signals()
 
 # Create a custom signal
 signals.create(
@@ -508,7 +508,8 @@ notifications.create_rule({
 })
 
 # List notifications
-alerts = notifications.list_notifications("agent-123", unread_only=True)
+alerts = notifications.list("agent-123", unread_only=True)
+# or: notifications.list_notifications("agent-123", unread_only=True)
 ```
 
 ## Documents (RAG)
@@ -520,7 +521,7 @@ from thinkhive.api import documents
 documents.upload("agent-123", file_name="faq.txt", file_type="text/plain", file_size=1024)
 
 # List documents
-docs = documents.list_documents("agent-123")
+docs = documents.list("agent-123")  # or documents.list_documents("agent-123")
 ```
 
 ## Shadow Tests
@@ -544,7 +545,8 @@ shadow_tests.create(
 from thinkhive.api import sessions
 
 # List conversation sessions
-all_sessions = sessions.list_sessions("agent-123", limit=20)
+all_sessions = sessions.list("agent-123", limit=20)
+# or: sessions.list_sessions("agent-123", limit=20)
 
 # Get all traces in a session
 traces = sessions.get_session_traces("session-789", "agent-123")
@@ -569,7 +571,8 @@ from thinkhive.api import llm_costs
 from thinkhive import format_cost
 
 # Get cost summary
-summary = llm_costs.get_summary(period="30d")
+summary = llm_costs.summary(period="30d")
+# or: llm_costs.get_summary(period="30d")
 print(f"Total cost: {format_cost(summary.get('totalCost', 0))}")
 
 # Get per-agent breakdown
@@ -593,6 +596,32 @@ savings = llm_costs.get_savings()
 
 ## Upgrading
 
+### v4.2.0 → v4.2.1
+
+Improvements in v4.2.1:
+- **Decorators** now accept `name=` parameter for custom span names (`@trace_llm(name="my-llm")`)
+- **`configure()`** now accepts `service_name` parameter
+- **`RateLimitError`** has `retry_after` alias (in addition to `retry_after_ms`)
+- **Rule helpers** (`create_regex_rule`, etc.) now return named rule objects with `{type, name, config}` structure
+- **`calculate_pass_at_k`** now supports both `(pass_rate, k)` and `(n, c, k)` calling conventions
+- **`aggregate_worst`** / **`aggregate_average`** accept simple `[float]` lists in addition to `[dict]`
+- **Method aliases added** for cross-SDK consistency:
+  - `runs.list()` / `runs.delete()`
+  - `calibration.status()` / `calibration.all_metrics()`
+  - `signals.list()` / `signals.delete()`
+  - `api_keys.list()`
+  - `linking.create()` / `linking.get_for_run()` / `linking.stats()` / `linking.verify()` / `linking.delete()`
+  - `roi_analytics.summary()` / `roi_analytics.correlations()`
+  - `business_metrics.current()` / `business_metrics.history()` / `business_metrics.record()`
+  - `quality_metrics.evaluate()`
+  - `llm_costs.summary()`
+  - `notifications.list()`
+  - `documents.list()` / `documents.delete()`
+  - `shadow_tests.list()`
+  - `sessions.list()`
+  - `customer_context.capture()`
+  - `guardrails.evaluate()`
+
 ### v4.1.0 → v4.2.0
 
 New in v4.2.0:

{thinkhive-4.2.0 → thinkhive-4.2.2}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="thinkhive",
-    version="4.2.0",
+    version="4.2.2",
     author="ThinkHive",
     author_email="support@thinkhive.ai",
     description="AI agent observability SDK with business metrics, ROI analytics, and 25+ trace format support",

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/__init__.py

@@ -20,7 +20,7 @@ from typing import Optional, Dict, Any, Callable
 import os
 import logging
 
-__version__ = "4.2.0"
+__version__ = "4.2.2"
 
 # Global tracer
 _tracer: Optional[trace.Tracer] = None
@@ -103,6 +103,7 @@ def get_tracer() -> trace.Tracer:
 def trace_llm(
     model_name: Optional[str] = None,
     provider: Optional[str] = None,
+    name: Optional[str] = None,
 ):
     """
     Decorator for tracing LLM calls
@@ -116,8 +117,9 @@ def trace_llm(
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             tracer = get_tracer()
+            span_name = name or func.__name__
             with tracer.start_as_current_span(
-                func.__name__,
+                span_name,
                 attributes={
                     "openinference.span.kind": "LLM",
                     "llm.model_name": model_name,
@@ -148,7 +150,7 @@ def trace_llm(
     return decorator
 
 
-def trace_retrieval(query: Optional[str] = None):
+def trace_retrieval(query: Optional[str] = None, name: Optional[str] = None):
     """
     Decorator for tracing retrieval/RAG operations
 
@@ -161,8 +163,9 @@ def trace_retrieval(query: Optional[str] = None):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             tracer = get_tracer()
+            span_name = name or func.__name__
             with tracer.start_as_current_span(
-                func.__name__,
+                span_name,
                 attributes={
                     "openinference.span.kind": "RETRIEVER",
                     "retrieval.query": query or (args[0] if args else None),
@@ -193,7 +196,7 @@ def trace_retrieval(query: Optional[str] = None):
     return decorator
 
 
-def trace_tool(tool_name: Optional[str] = None):
+def trace_tool(tool_name: Optional[str] = None, name: Optional[str] = None):
     """
     Decorator for tracing tool/function calls
 
@@ -206,11 +209,12 @@ def trace_tool(tool_name: Optional[str] = None):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             tracer = get_tracer()
+            span_name = name or tool_name or func.__name__
             with tracer.start_as_current_span(
-                tool_name or func.__name__,
+                span_name,
                 attributes={
                     "openinference.span.kind": "TOOL",
-                    "tool.name": tool_name or func.__name__,
+                    "tool.name": tool_name or name or func.__name__,
                 }
             ) as span:
                 try:

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/api_keys.py

@@ -119,6 +119,9 @@ class ApiKeysClient:
         response = api_request("POST", "/api-keys/test", api_version="v2")
         return response.get("data", response) if isinstance(response, dict) else response
 
+    # Convenience alias for cross-SDK parity
+    list = list_keys
+
 
 def has_permission(key: Dict[str, Any], permission: str) -> bool:
     """

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/business_metrics.py

@@ -392,6 +392,11 @@ def format_metric_value(value: float, unit: str) -> str:
         return str(round(value * 100) / 100)
 
 
+# Convenience aliases for cross-SDK parity
+current = get_current
+history = get_history
+record = record_value
+
 __all__ = [
     # Dataclasses
     "MetricTrend",
@@ -413,4 +418,8 @@ __all__ = [
     "get_status_message",
     "get_trace_progress",
     "format_metric_value",
+    # Aliases
+    "current",
+    "history",
+    "record",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/calibration.py

@@ -5,7 +5,7 @@ Prediction accuracy tracking with Brier scores and calibration metrics
 
 from typing import Optional, Dict, Any, List, Literal
 from dataclasses import dataclass
-from ..client import post, get
+from ..client import post, get, api_request
 
 PredictionType = Literal[
     "outcome",
@@ -115,7 +115,7 @@ def get_status(agent_id: str, prediction_type: PredictionType) -> CalibrationSta
         >>> print(f"Is calibrated: {status.is_calibrated}")
     """
     params = {"predictionType": prediction_type}
-    response = get(f"/calibration/{agent_id}/status", params=params, api_version="v3")
+    response = api_request("GET", f"/calibration/{agent_id}/status", params=params, api_version="v3")
     return CalibrationStatus.from_dict(response)
 
 
@@ -267,6 +267,10 @@ def format_brier_score(score: float) -> str:
     return f"{score:.4f}"
 
 
+# Convenience aliases for cross-SDK parity
+status = get_status
+all_metrics = get_metrics
+
 __all__ = [
     # Types
     "PredictionType",
@@ -284,4 +288,7 @@ __all__ = [
     "is_well_calibrated",
     "get_calibration_quality",
     "format_brier_score",
+    # Aliases
+    "status",
+    "all_metrics",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/conversation_eval.py

@@ -69,18 +69,23 @@ conversation_eval = ConversationEvalApi()
 
 # Aggregation helper functions
 
-def aggregate_worst(turn_results: List[Dict[str, Any]]) -> Dict[str, Any]:
+def aggregate_worst(turn_results):
     """
     Calculate worst-turn aggregation
 
-    Args:
-        turn_results: List of turn evaluation results
+    Accepts List[Dict] (turn results) or List[float] (simple scores):
+    - aggregate_worst([{"score": 0.9, "passed": True}, ...]) → {"passed": ..., "score": ...}
+    - aggregate_worst([0.9, 0.5, 0.7]) → 0.5
 
     Returns:
-        Dict with passed and score (fails if any turn fails)
+        Dict with passed and score, or float if given simple numbers
     """
     if not turn_results:
-        return {"passed": False, "score": 0}
+        return 0 if (turn_results is not None and isinstance(turn_results, list)) else {"passed": False, "score": 0}
+
+    # Simple number list
+    if isinstance(turn_results[0], (int, float)):
+        return min(turn_results)
 
     scores = [t.get("score", 0) for t in turn_results]
     worst_score = min(scores)
@@ -89,18 +94,23 @@ def aggregate_worst(turn_results: List[Dict[str, Any]]) -> Dict[str, Any]:
     return {"passed": passed, "score": worst_score}
 
 
-def aggregate_average(turn_results: List[Dict[str, Any]]) -> Dict[str, Any]:
+def aggregate_average(turn_results):
     """
     Calculate average aggregation
 
-    Args:
-        turn_results: List of turn evaluation results
+    Accepts List[Dict] (turn results) or List[float] (simple scores):
+    - aggregate_average([{"score": 0.6, "passed": True}, ...]) → {"passed": ..., "score": ...}
+    - aggregate_average([0.6, 0.8]) → 0.7
 
     Returns:
-        Dict with passed (majority vote) and average score
+        Dict with passed (majority vote) and average score, or float if given simple numbers
     """
     if not turn_results:
-        return {"passed": False, "score": 0}
+        return 0 if (turn_results is not None and isinstance(turn_results, list)) else {"passed": False, "score": 0}
+
+    # Simple number list
+    if isinstance(turn_results[0], (int, float)):
+        return sum(turn_results) / len(turn_results)
 
     scores = [t.get("score", 0) for t in turn_results]
     avg_score = sum(scores) / len(scores)

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/customer_context.py

@@ -304,6 +304,9 @@ def format_arr(arr: float) -> str:
     return f"${arr:,.0f}"
 
 
+# Convenience alias for cross-SDK parity
+capture = create_snapshot
+
 __all__ = [
     # Types
     "CustomerSegment",
@@ -320,4 +323,6 @@ __all__ = [
     "is_at_risk",
     "get_segment_priority",
     "format_arr",
+    # Aliases
+    "capture",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/deterministic_graders.py

@@ -71,70 +71,79 @@ deterministic_graders = DeterministicGradersApi()
 
 # Helper functions
 
-def create_regex_rule(pattern: str, flags: str = "gi") -> Dict[str, str]:
+def create_regex_rule(name: str, field: str = "output", pattern: str = "", flags: str = "gi") -> Dict[str, Any]:
     """
-    Create a regex rule configuration
+    Create a named regex rule configuration
 
     Args:
+        name: Rule name for identification
+        field: Field to check ('output', 'input', etc.)
         pattern: Regular expression pattern
         flags: Regex flags (default: 'gi')
 
     Returns:
-        Rule configuration object
+        Named rule configuration object with type, name, and config
     """
-    return {"pattern": pattern, "flags": flags}
+    return {"type": "regex", "name": name, "config": {"field": field, "pattern": pattern, "flags": flags}}
 
 
 def create_contains_rule(
-    values: List[str],
+    name: str,
+    field: str = "output",
+    values: Optional[List[str]] = None,
     case_sensitive: bool = False,
 ) -> Dict[str, Any]:
     """
-    Create a contains rule configuration
+    Create a named contains rule configuration
 
     Args:
+        name: Rule name for identification
+        field: Field to check ('output', 'input', etc.)
         values: Strings to check for
         case_sensitive: Whether comparison is case-sensitive
 
     Returns:
-        Rule configuration object
+        Named rule configuration object with type, name, and config
     """
-    return {"values": values, "caseSensitive": case_sensitive}
+    return {"type": "contains", "name": name, "config": {"field": field, "values": values or [], "caseSensitive": case_sensitive}}
 
 
 def create_length_rule(
+    name: str,
     min_length: Optional[int] = None,
     max_length: Optional[int] = None,
 ) -> Dict[str, Any]:
     """
-    Create a length rule configuration
+    Create a named length rule configuration
 
     Args:
+        name: Rule name for identification
         min_length: Minimum length
         max_length: Maximum length
 
     Returns:
-        Rule configuration object
+        Named rule configuration object with type, name, and config
     """
-    config = {}
+    config: Dict[str, Any] = {}
     if min_length is not None:
         config["min"] = min_length
     if max_length is not None:
         config["max"] = max_length
-    return config
+    return {"type": "length", "name": name, "config": config}
 
 
-def create_json_schema_rule(schema: Dict[str, Any]) -> Dict[str, Any]:
+def create_json_schema_rule(name: str, schema: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """
-    Create a JSON schema rule configuration
+    Create a named JSON schema rule configuration
 
     Args:
+        name: Rule name for identification
         schema: JSON Schema object
 
     Returns:
-        Rule configuration object
+        Named rule configuration object with type, name, and config
     """
-    return {"schema": schema}
+    return {"type": "json_schema", "name": name, "config": {"schema": schema or {}}}
 
 
 def all_rules_passed(results: List[Dict[str, Any]]) -> bool:

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/documents.py

@@ -5,7 +5,7 @@ Agent document management for RAG (Retrieval-Augmented Generation)
 
 from typing import Optional, Dict, Any, List
 from dataclasses import dataclass
-from ..client import post, get, delete
+from ..client import post, get, delete as _client_delete
 
 
 @dataclass
@@ -82,12 +82,18 @@ def delete_document(agent_id: str, doc_id: str) -> None:
         agent_id: The agent ID
         doc_id: The document ID to delete
     """
-    delete(f"/agents/{agent_id}/documents/{doc_id}", api_version="")
+    _client_delete(f"/agents/{agent_id}/documents/{doc_id}", api_version="")
 
 
+# Convenience aliases for cross-SDK parity
+list = list_documents
+delete = delete_document
+
 __all__ = [
     "Document",
     "list_documents",
     "upload",
     "delete_document",
+    "list",
+    "delete",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/linking.py

@@ -255,6 +255,41 @@ def get_supported_platforms() -> List[str]:
     return list(_SUPPORTED_PLATFORMS)
 
 
+# Convenience aliases for cross-SDK parity
+create = link_run_to_ticket
+get_for_run = get_linked_ticket
+delete = unlink_run
+
+
+def stats() -> Dict[str, Any]:
+    """
+    Get supported platform stats.
+
+    Returns:
+        Dict with platform count and list of supported platforms
+    """
+    platforms = get_supported_platforms()
+    return {"platform_count": len(platforms), "platforms": platforms}
+
+
+def verify(
+    run_id: str,
+    *,
+    verified: bool = True,
+) -> Dict[str, Any]:
+    """
+    Update link verification status for a run.
+
+    Args:
+        run_id: The run ID whose link to verify
+        verified: Whether the link is verified (default True)
+
+    Returns:
+        Updated run data
+    """
+    return put(f"/runs/{run_id}", {"ticketLinking": {"verified": verified}}, api_version="v3")
+
+
 __all__ = [
     # Types
     "LinkMethod",
@@ -271,4 +306,10 @@ __all__ = [
     "get_method_confidence",
     "is_high_confidence_link",
     "get_supported_platforms",
+    # Aliases
+    "create",
+    "get_for_run",
+    "delete",
+    "stats",
+    "verify",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/llm_costs.py

@@ -5,7 +5,7 @@ LLM cost tracking and optimization insights
 
 from typing import Optional, Dict, Any
 from dataclasses import dataclass
-from ..client import get
+from ..client import get, api_request
 
 
 @dataclass
@@ -57,7 +57,7 @@ def get_summary(*, period: str = "30d") -> CostSummary:
         CostSummary with total costs and breakdown
     """
     params: Dict[str, Any] = {"period": period}
-    response = get("/llm-costs/summary", params=params, api_version="")
+    response = api_request("GET", "/llm-costs/summary", params=params, api_version="")
     return CostSummary.from_dict(response)
 
 
@@ -110,6 +110,9 @@ def format_cost(amount: float) -> str:
     return f"${amount:,.2f}"
 
 
+# Convenience alias for cross-SDK parity
+summary = get_summary
+
 __all__ = [
     "CostSummary",
     "CostBreakdown",
@@ -118,4 +121,5 @@ __all__ = [
     "get_savings",
     "get_optimization_stats",
     "format_cost",
+    "summary",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/nondeterminism.py

@@ -178,18 +178,35 @@ nondeterminism = NondeterminismApi()
 
 # Helper functions
 
-def calculate_pass_at_k(pass_rate: float, k: int) -> float:
+def calculate_pass_at_k(pass_rate_or_n: float, k_or_c: int, k: Optional[int] = None) -> float:
     """
-    Calculate pass@k probability from pass rate
+    Calculate pass@k probability
 
-    Args:
-        pass_rate: Single-run pass rate (0-1)
-        k: Number of runs
+    Supports two calling conventions:
+    - calculate_pass_at_k(pass_rate, k) — from pass rate directly
+    - calculate_pass_at_k(n, c, k) — from n total runs, c correct, sample k
 
     Returns:
         Probability that at least 1 of k runs passes
     """
-    return 1 - math.pow(1 - pass_rate, k)
+    if k is not None:
+        # (n, c, k) form: 1 - C(n-c, k) / C(n, k)
+        n = int(pass_rate_or_n)
+        c = int(k_or_c)
+        if c >= n:
+            return 1.0
+        if c == 0:
+            return 0.0
+        if k > n:
+            return 1.0 if c > 0 else 0.0
+
+        # Use logarithmic calculation to avoid overflow
+        log_num = sum(math.log(n - c - i) for i in range(k) if (n - c - i) > 0)
+        log_den = sum(math.log(n - i) for i in range(k))
+        return 1 - math.exp(log_num - log_den)
+
+    # (pass_rate, k) form
+    return 1 - math.pow(1 - pass_rate_or_n, k_or_c)
 
 
 def calculate_pass_to_k(pass_rate: float, k: int) -> float:

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/notifications.py

@@ -23,7 +23,7 @@ Usage:
 """
 
 from typing import Optional, Dict, Any, List
-from ..client import get, post, patch, delete
+from ..client import get, post, patch, delete, api_request
 
 
 class NotificationsClient:
@@ -42,7 +42,7 @@ class NotificationsClient:
             List of notification rules
         """
         params: Dict[str, Any] = {"agentId": agent_id}
-        return get("/notification-rules", params=params, api_version="")
+        return api_request("GET", "/notification-rules", params=params, api_version="")
 
     def get_rule(
         self,
@@ -119,7 +119,7 @@ class NotificationsClient:
         if unread_only:
             params["unreadOnly"] = True
 
-        return get("/notifications", params=params, api_version="")
+        return api_request("GET", "/notifications", params=params, api_version="")
 
     def mark_as_read(self, notification_id: str) -> Dict[str, Any]:
         """
@@ -133,6 +133,9 @@ class NotificationsClient:
         """
         return patch(f"/notifications/{notification_id}/read", api_version="")
 
+    # Convenience alias for cross-SDK parity
+    list = list_notifications
+
 
 # Singleton instance
 notifications = NotificationsClient()

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/quality_metrics.py

@@ -372,6 +372,9 @@ def needs_improvement(evaluation: RAGEvaluation, *, threshold: float = 0.5) -> b
     return any(score < threshold for score in dimensions)
 
 
+# Convenience alias for cross-SDK parity
+evaluate = evaluate_rag
+
 __all__ = [
     "RAGEvaluation",
     "HallucinationInstance",
@@ -387,4 +390,5 @@ __all__ = [
     "has_critical_hallucinations",
     "get_grade_color",
     "needs_improvement",
+    "evaluate",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/roi_analytics.py

@@ -457,6 +457,10 @@ def get_trend_v3(
     return get("/roi/trend", params=params, api_version="v3")
 
 
+# Convenience aliases for cross-SDK parity
+summary = get_summary
+correlations = get_correlations
+
 __all__ = [
     # Dataclasses
     "IndustryConfig",
@@ -478,4 +482,7 @@ __all__ = [
     "get_config_versions",
     "calculate_v3",
     "get_trend_v3",
+    # Aliases
+    "summary",
+    "correlations",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/runs.py

@@ -6,7 +6,7 @@ Run-centric API for creating and managing runs (v3 atomic unit)
 from typing import Optional, Dict, Any, List, Literal
 from dataclasses import dataclass
 from datetime import datetime
-from ..client import post, get, put, delete
+from ..client import post, get, put, delete as _client_delete
 
 RunOutcome = Literal[
     "resolved",
@@ -245,7 +245,7 @@ def delete_run(run_id: str) -> None:
     Args:
         run_id: The run ID to delete
     """
-    delete(f"/runs/{run_id}", api_version="v3")
+    _client_delete(f"/runs/{run_id}", api_version="v3")
 
 
 def batch_create(runs_data: List[Dict[str, Any]]) -> Dict[str, Any]:
@@ -329,6 +329,10 @@ def get_stats(
     return RunStats.from_dict(response)
 
 
+# Convenience aliases for cross-SDK parity
+list = list_runs
+delete = delete_run
+
 __all__ = [
     "RunResult",
     "RunStats",
@@ -340,4 +344,6 @@ __all__ = [
     "delete_run",
     "batch_create",
     "get_stats",
+    "list",
+    "delete",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/sessions.py

@@ -4,7 +4,7 @@ Trace session grouping for managing conversation sessions
 """
 
 from typing import Optional, Dict, Any, List
-from ..client import get
+from ..client import get, api_request
 
 
 def list_sessions(
@@ -30,7 +30,7 @@ def list_sessions(
         "offset": offset,
     }
 
-    return get("/traces/sessions", params=params, api_version="")
+    return api_request("GET", "/sessions", params=params, api_version="")
 
 
 def get_session_traces(session_id: str, agent_id: str) -> Dict[str, Any]:
@@ -52,7 +52,11 @@ def get_session_traces(session_id: str, agent_id: str) -> Dict[str, Any]:
     return get("/traces", params=params, api_version="")
 
 
+# Convenience alias for cross-SDK parity
+list = list_sessions
+
 __all__ = [
     "list_sessions",
     "get_session_traces",
+    "list",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/shadow_tests.py

@@ -117,6 +117,9 @@ def update(test_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
     return patch(f"/shadow-tests/{test_id}", data, api_version="")
 
 
+# Convenience alias for cross-SDK parity
+list = list_tests
+
 __all__ = [
     "ShadowTest",
     "list_tests",
@@ -124,4 +127,5 @@ __all__ = [
     "get_by_fix",
     "create",
     "update",
+    "list",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/api/signals.py

@@ -5,7 +5,7 @@ Behavioral signal management for detecting patterns in agent interactions
 
 from typing import Optional, Dict, Any, List
 from dataclasses import dataclass
-from ..client import post, get, put, delete
+from ..client import post, get, put, delete as _client_delete, api_request
 
 
 @dataclass
@@ -58,7 +58,10 @@ def list_signals(
     if is_enabled is not None:
         params["isEnabled"] = is_enabled
 
-    return get("/signals/", params=params, api_version="v1")
+    response = api_request("GET", "/signals/", params=params, api_version="v1")
+    if type(response) is type([]):
+        return response
+    return response.get("signals", [])
 
 
 def create(
@@ -140,7 +143,7 @@ def delete_signal(signal_id: str) -> None:
     Args:
         signal_id: The signal ID to delete
     """
-    delete(f"/signals/{signal_id}", api_version="v1")
+    _client_delete(f"/signals/{signal_id}", api_version="v1")
 
 
 def seed_defaults() -> Dict[str, Any]:
@@ -179,7 +182,10 @@ def get_stats(
     if agent_id is not None:
         params["agentId"] = agent_id
 
-    return get("/signals/stats", params=params, api_version="v1")
+    response = api_request("GET", "/signals/stats", params=params, api_version="v1")
+    if type(response) is type([]):
+        return {"stats": response}
+    return response
 
 
 def get_trends(
@@ -272,6 +278,10 @@ def get_events(
     return get(f"/signals/{signal_id}/events", params=params, api_version="v1")
 
 
+# Convenience aliases for cross-SDK parity
+list = list_signals
+delete = delete_signal
+
 __all__ = [
     "Signal",
     "list_signals",
@@ -283,4 +293,6 @@ __all__ = [
     "get_trends",
     "get_traces",
     "get_events",
+    "list",
+    "delete",
 ]

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/client.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 
 T = TypeVar('T')
 
-SDK_VERSION = "4.0.1"
+SDK_VERSION = "4.2.0"
 
 # Retry configuration
 MAX_RETRIES = 3
@@ -70,6 +70,7 @@ class RateLimitError(ThinkHiveApiError):
     def __init__(self, message: str, retry_after_ms: Optional[int] = None):
         super().__init__(message, status_code=429, code="RATE_LIMIT_EXCEEDED")
         self.retry_after_ms = retry_after_ms
+        self.retry_after = retry_after_ms  # Alias for cross-SDK parity
 
 
 class IpWhitelistError(ThinkHiveApiError):
@@ -95,6 +96,7 @@ def configure(
     endpoint: Optional[str] = None,
     timeout: Optional[int] = None,
     max_retries: Optional[int] = None,
+    service_name: Optional[str] = None,
 ) -> None:
     """
     Configure the HTTP client
@@ -105,6 +107,7 @@ def configure(
         endpoint: API endpoint URL
         timeout: Request timeout in seconds (default: 30)
         max_retries: Maximum number of retries for transient failures (default: 3)
+        service_name: Service name for tracing (default: 'my-ai-agent')
     """
     global _config
 
@@ -118,6 +121,8 @@ def configure(
         _config["timeout"] = timeout
     if max_retries is not None:
         _config["max_retries"] = max_retries
+    if service_name is not None:
+        _config["service_name"] = service_name
 
     # Try environment variables as fallback
     if not _config["api_key"]:

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive/guardrails.py

@@ -97,7 +97,10 @@ def _guardrails_request(method: str, path: str, body: Optional[Dict[str, Any]] =
             data = response.json()
             if not data.get("success", True):
                 raise ThinkHiveApiError(data.get("message", "Request failed"), 500)
-            return data.get("data")
+            # Support both wrapped {success, data} and raw responses
+            if "data" in data:
+                return data["data"]
+            return data
 
         except requests.exceptions.Timeout:
             if attempt < max_retries:
@@ -211,3 +214,7 @@ def list_scanners() -> List[Dict[str, Any]]:
     """
     data = _guardrails_request("GET", "/v1/guardrails/scanners")
     return data.get("scanners", [])
+
+
+# Convenience alias for cross-SDK parity
+evaluate = scan

{thinkhive-4.2.0 → thinkhive-4.2.2}/thinkhive.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thinkhive
-Version: 4.2.0
+Version: 4.2.2
 Summary: AI agent observability SDK with business metrics, ROI analytics, and 25+ trace format support
 Home-page: https://github.com/Abdul-Omira/ThinkHiveMind
 Author: ThinkHive
@@ -30,7 +30,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# ThinkHive Python SDK v4.2.0
+# ThinkHive Python SDK v4.2.1
 
 OpenTelemetry-based observability SDK for AI agents supporting 25 trace formats including LangSmith, Langfuse, Opik, Braintrust, Datadog, MLflow, and more.
 
@@ -53,7 +53,7 @@ thinkhive.init(
 )
 
 # Trace LLM calls
-@thinkhive.trace_llm(model_name="gpt-4", provider="openai")
+@thinkhive.trace_llm(name="generate-response", model_name="gpt-4", provider="openai")
 def call_llm(prompt):
     response = openai.chat.completions.create(
         model="gpt-4",
@@ -62,13 +62,13 @@ def call_llm(prompt):
     return response
 
 # Trace retrieval operations
-@thinkhive.trace_retrieval()
+@thinkhive.trace_retrieval(name="search-kb", query="refund policy")
 def search_documents(query):
     results = vector_db.search(query)
     return results
 
 # Trace tool calls
-@thinkhive.trace_tool(tool_name="web_search")
+@thinkhive.trace_tool(name="lookup-order", tool_name="web_search")
 def search_web(query):
     return requests.get(f"https://api.example.com/search?q={query}")
 ```
@@ -317,7 +317,7 @@ result = api_keys.create(
 print(f"Key: {result['key']}")  # Only shown once!
 
 # List all keys
-keys = api_keys.list_keys()
+keys = api_keys.list()  # or api_keys.list_keys()
 
 # Revoke a key
 api_keys.revoke("key-id")
@@ -433,7 +433,7 @@ from thinkhive import (
 try:
     result = runs.create(agent_id="agent-123", ...)
 except RateLimitError as e:
-    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
+    print(f"Rate limited. Retry after {e.retry_after}ms")  # or e.retry_after_ms
 except AgentScopeError as e:
     print(f"No access to agent. Allowed: {e.allowed_agents}")
 except NotFoundError as e:
@@ -511,7 +511,7 @@ print(f"Estimated cost: {cost['estimatedCredits']} credits")
 from thinkhive.api import signals
 
 # List all signals
-all_signals = signals.list_signals()
+all_signals = signals.list()  # or signals.list_signals()
 
 # Create a custom signal
 signals.create(
@@ -540,7 +540,8 @@ notifications.create_rule({
 })
 
 # List notifications
-alerts = notifications.list_notifications("agent-123", unread_only=True)
+alerts = notifications.list("agent-123", unread_only=True)
+# or: notifications.list_notifications("agent-123", unread_only=True)
 ```
 
 ## Documents (RAG)
@@ -552,7 +553,7 @@ from thinkhive.api import documents
 documents.upload("agent-123", file_name="faq.txt", file_type="text/plain", file_size=1024)
 
 # List documents
-docs = documents.list_documents("agent-123")
+docs = documents.list("agent-123")  # or documents.list_documents("agent-123")
 ```
 
 ## Shadow Tests
@@ -576,7 +577,8 @@ shadow_tests.create(
 from thinkhive.api import sessions
 
 # List conversation sessions
-all_sessions = sessions.list_sessions("agent-123", limit=20)
+all_sessions = sessions.list("agent-123", limit=20)
+# or: sessions.list_sessions("agent-123", limit=20)
 
 # Get all traces in a session
 traces = sessions.get_session_traces("session-789", "agent-123")
@@ -601,7 +603,8 @@ from thinkhive.api import llm_costs
 from thinkhive import format_cost
 
 # Get cost summary
-summary = llm_costs.get_summary(period="30d")
+summary = llm_costs.summary(period="30d")
+# or: llm_costs.get_summary(period="30d")
 print(f"Total cost: {format_cost(summary.get('totalCost', 0))}")
 
 # Get per-agent breakdown
@@ -625,6 +628,32 @@ savings = llm_costs.get_savings()
 
 ## Upgrading
 
+### v4.2.0 → v4.2.1
+
+Improvements in v4.2.1:
+- **Decorators** now accept `name=` parameter for custom span names (`@trace_llm(name="my-llm")`)
+- **`configure()`** now accepts `service_name` parameter
+- **`RateLimitError`** has `retry_after` alias (in addition to `retry_after_ms`)
+- **Rule helpers** (`create_regex_rule`, etc.) now return named rule objects with `{type, name, config}` structure
+- **`calculate_pass_at_k`** now supports both `(pass_rate, k)` and `(n, c, k)` calling conventions
+- **`aggregate_worst`** / **`aggregate_average`** accept simple `[float]` lists in addition to `[dict]`
+- **Method aliases added** for cross-SDK consistency:
+  - `runs.list()` / `runs.delete()`
+  - `calibration.status()` / `calibration.all_metrics()`
+  - `signals.list()` / `signals.delete()`
+  - `api_keys.list()`
+  - `linking.create()` / `linking.get_for_run()` / `linking.stats()` / `linking.verify()` / `linking.delete()`
+  - `roi_analytics.summary()` / `roi_analytics.correlations()`
+  - `business_metrics.current()` / `business_metrics.history()` / `business_metrics.record()`
+  - `quality_metrics.evaluate()`
+  - `llm_costs.summary()`
+  - `notifications.list()`
+  - `documents.list()` / `documents.delete()`
+  - `shadow_tests.list()`
+  - `sessions.list()`
+  - `customer_context.capture()`
+  - `guardrails.evaluate()`
+
 ### v4.1.0 → v4.2.0
 
 New in v4.2.0: