monocle-apptrace 0.5.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

monocle_apptrace/instrumentation/metamodel/mistral/_helper.py

@@ -0,0 +1,223 @@
+"""
+This module provides utility functions for extracting system, user,
+and assistant messages from various input formats.
+"""
+
+import json
+import logging
+from opentelemetry.context import get_value
+from monocle_apptrace.instrumentation.common.utils import (
+    Option,
+    get_json_dumps,
+    get_keys_as_tuple,
+    get_nested_value,
+    get_status_code,
+    try_option,
+    get_exception_message,
+)
+from monocle_apptrace.instrumentation.metamodel.finish_types import map_mistral_finish_reason_to_finish_type
+from monocle_apptrace.instrumentation.common.constants import AGENT_PREFIX_KEY, INFERENCE_AGENT_DELEGATION, INFERENCE_TURN_END, INFERENCE_TOOL_CALL
+
+logger = logging.getLogger(__name__)
+
+
+def extract_provider_name(instance):
+    provider_url: Option[str] = try_option(getattr, instance._client.base_url, 'host')
+    return provider_url.unwrap_or(None)
+
+def update_input_span_events(kwargs):
+    """Extract embedding input for spans"""
+    if "inputs" in kwargs and isinstance(kwargs["inputs"], list):
+        # Join multiple strings into one
+        return " | ".join(kwargs["inputs"])
+    elif "inputs" in kwargs and isinstance(kwargs["inputs"], str):
+        return kwargs["inputs"]
+    return ""
+
+def update_output_span_events(results):
+    """Extract embedding output for spans"""
+    try:
+        if hasattr(results, "data") and isinstance(results.data, list):
+            embeddings = results.data
+            # just return the indices, not full vectors
+            embedding_summaries = [
+                f"index={e.index}, dim={len(e.embedding)}"
+                for e in embeddings
+            ]
+            output = "\n".join(embedding_summaries)
+            if len(output) > 200:
+                output = output[:200] + "..."
+            return output
+    except Exception as e:
+        logger.warning("Error in update_output_span_events: %s", str(e))
+    return ""
+
+def extract_inference_endpoint(instance):
+    inference_endpoint: Option[str] = try_option(getattr, instance._client, 'base_url').map(str)
+    if inference_endpoint.is_none() and "meta" in instance.client.__dict__:
+        inference_endpoint = try_option(getattr, instance.client.meta, 'endpoint_url').map(str)
+
+    return inference_endpoint.unwrap_or(extract_provider_name(instance))
+
+
+def dummy_method(arguments):
+    pass
+
+
+def extract_messages(kwargs):
+    """Extract system and user messages"""
+    try:
+        messages = []
+        if "system" in kwargs and isinstance(kwargs["system"], str):
+            messages.append({"system": kwargs["system"]})
+        if 'messages' in kwargs and kwargs['messages']:
+            for msg in kwargs['messages']:
+                if msg.get('content') and msg.get('role'):
+                    messages.append({msg['role']: msg['content']})
+        return [get_json_dumps(message) for message in messages]
+    except Exception as e:
+        logger.warning("Warning: Error occurred in extract_messages: %s", str(e))
+        return []
+
+
+def get_exception_status_code(arguments):
+    exc = arguments.get("exception")
+    if exc is not None and hasattr(exc, "status_code"):
+        if exc.status_code == 401:
+            return "unauthorized"
+        elif exc.status_code == 403:
+            return "forbidden"
+        elif exc.status_code == 404:
+            return "not_found"
+        else:
+            return str(exc.status_code)
+    elif exc is not None:
+        return "error"
+    else:
+        return "success"
+
+
+def extract_assistant_message(arguments):
+    """
+    Extract the assistant message from a Mistral response or stream chunks.
+    Returns a JSON string like {"assistant": "<text>"}.
+    """
+    try:
+        result = arguments.get("result") if isinstance(arguments, dict) else arguments
+        if result is None:
+            return ""
+
+        # Handle full response
+        if hasattr(result, "choices") and result.choices:
+            msg_obj = result.choices[0].message
+            return get_json_dumps({msg_obj.role: msg_obj.content})
+
+        # Handle streaming: result might be a list of CompletionEvent chunks
+        if isinstance(result, list):
+            content = []
+            for chunk in result:
+                if hasattr(chunk, "data") and hasattr(chunk.data, "choices") and chunk.data.choices:
+                    choice = chunk.data.choices[0]
+                    if hasattr(choice, "delta") and hasattr(choice.delta, "content"):
+                        content.append(choice.delta.content or "")
+            return get_json_dumps({"assistant": "".join(content)})
+
+        return ""
+
+    except Exception as e:
+        logger.warning("Warning in extract_assistant_message: %s", str(e))
+        return ""
+
+
+'''def update_span_from_llm_response(response):
+    meta_dict = {}
+    if response is not None and hasattr(response, "usage"):
+        token_usage = getattr(response, "usage", None) or getattr(response, "response_metadata", {}).get("token_usage")
+        if token_usage is not None:
+            meta_dict.update({"completion_tokens": getattr(response.usage, "output_tokens", 0)})
+            meta_dict.update({"prompt_tokens": getattr(response.usage, "input_tokens", 0)})
+            meta_dict.update({"total_tokens": getattr(response.usage, "input_tokens", 0) + getattr(response.usage, "output_tokens", 0)})
+    return meta_dict'''
+
+def update_span_from_llm_response(result, include_token_counts=False):
+    tokens = {
+        "completion_tokens": getattr(result, "completion_tokens", 0),
+        "prompt_tokens": getattr(result, "prompt_tokens", 0),
+        "total_tokens": getattr(result, "total_tokens", 0),
+    } if include_token_counts else {}
+    # Add other metadata fields like finish_reason, etc.
+    return {**tokens, "inference_sub_type": "turn_end"}
+
+
+def extract_finish_reason(arguments):
+    """
+    Extract stop_reason from a Mistral response or stream chunks.
+    Works for both streaming (list of chunks) and full responses.
+    """
+    try:
+        response = arguments.get("result") if isinstance(arguments, dict) else arguments
+        if response is None:
+            return None
+
+        # Handle full response: single object with stop_reason
+        if hasattr(response, "stop_reason") and response.stop_reason:
+            return response.stop_reason
+
+        # Handle streaming: list of chunks, last chunk may have finish_reason
+        if isinstance(response, list):
+            for chunk in reversed(response):
+                if hasattr(chunk, "data") and hasattr(chunk.data, "choices") and chunk.data.choices:
+                    fr = getattr(chunk.data.choices[0], "finish_reason", None)
+                    if fr is not None:
+                        return fr
+
+    except Exception as e:
+        logger.warning("Warning: Error occurred in extract_finish_reason: %s", str(e))
+        return None
+
+    return None
+
+
+def map_finish_reason_to_finish_type(finish_reason):
+    """Map Mistral stop_reason to finish_type, similar to OpenAI mapping."""
+    return map_mistral_finish_reason_to_finish_type(finish_reason)
+
+
+def agent_inference_type(arguments):
+    """Extract agent inference type from Mistral response"""
+    try:
+        status = get_status_code(arguments)
+        if status in ('success', 'completed'):
+            response = arguments.get("result")
+            if response is None:
+                return INFERENCE_TURN_END
+
+            # Check if stop_reason indicates tool use
+            stop_reason = getattr(response, "stop_reason", None)
+            if stop_reason == "tool_use" and hasattr(response, "content") and response.content:
+                agent_prefix = get_value(AGENT_PREFIX_KEY)
+                for content_block in response.content:
+                    if getattr(content_block, "type", None) == "tool_use" and hasattr(content_block, "name"):
+                        if agent_prefix and content_block.name.startswith(agent_prefix):
+                            return INFERENCE_AGENT_DELEGATION
+                return INFERENCE_TOOL_CALL
+
+            # Fallback: check the extracted message for tool content
+            assistant_message = extract_assistant_message(arguments)
+            if assistant_message:
+                try:
+                    message = json.loads(assistant_message)
+                    assistant_content = message.get("assistant", "") if isinstance(message, dict) else ""
+                    agent_prefix = get_value(AGENT_PREFIX_KEY)
+                    if agent_prefix and agent_prefix in assistant_content:
+                        return INFERENCE_AGENT_DELEGATION
+                except (json.JSONDecodeError, TypeError):
+                    agent_prefix = get_value(AGENT_PREFIX_KEY)
+                    if agent_prefix and agent_prefix in assistant_message:
+                        return INFERENCE_AGENT_DELEGATION
+
+        return INFERENCE_TURN_END
+
+    except Exception as e:
+        logger.warning("Warning: Error occurred in agent_inference_type: %s", str(e))
+        return INFERENCE_TURN_END

monocle_apptrace/instrumentation/metamodel/mistral/entities/inference.py

@@ -0,0 +1,94 @@
+from monocle_apptrace.instrumentation.common.constants import SPAN_TYPES
+from monocle_apptrace.instrumentation.metamodel.mistral import _helper
+from monocle_apptrace.instrumentation.common.utils import get_error_message, resolve_from_alias
+
+MISTRAL_INFERENCE = {
+    "type": SPAN_TYPES.INFERENCE,
+    "attributes": [
+        [
+            {
+                "_comment": "provider type ,name , deployment , inference_endpoint",
+                "attribute": "type",
+                "accessor": lambda arguments: 'inference.mistral'
+            },
+            {
+                "attribute": "provider_name",
+                "accessor": lambda arguments: "mistral"
+            },
+            {
+                "attribute": "inference_endpoint",
+                "accessor": lambda arguments: "https://api.mistral.ai"
+            }
+        ],
+        [
+            {
+                "_comment": "LLM Model",
+                "attribute": "name",
+                "accessor": lambda arguments: resolve_from_alias(arguments['kwargs'], ['model', 'model_name', 'endpoint_name', 'deployment_name'])
+            },
+            {
+                "attribute": "type",
+                "accessor": lambda arguments: 'model.llm.' + resolve_from_alias(arguments['kwargs'], ['model', 'model_name', 'endpoint_name', 'deployment_name'])
+            }
+        ]
+    ],
+    "events": [
+        {
+            "name": "data.input",
+            "attributes": [
+                {
+                    "_comment": "this is instruction and user query to LLM",
+                    "attribute": "input",
+                    "accessor": lambda arguments: _helper.extract_messages(arguments['kwargs'])
+                }
+            ]
+        },
+        {
+            "name": "data.output",
+            "attributes": [
+                {
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
+                },
+                {
+                    "_comment": "this is result from LLM, works for streaming and non-streaming",
+                    "attribute": "response",
+                    "accessor": lambda arguments: (
+                        # Handle streaming: combine chunks if result is iterable and doesn't have 'choices'
+                        _helper.extract_assistant_message(
+                            {"result": list(arguments["result"])}
+                            if hasattr(arguments.get("result"), "__iter__") and not hasattr(arguments.get("result"), "choices")
+                            else arguments
+                        )
+                    )
+                }
+            ]
+        },
+        {
+            "name": "metadata",
+            "attributes": [
+                {
+                    "_comment": "this is metadata usage from LLM, includes token counts",
+                    "accessor": lambda arguments: _helper.update_span_from_llm_response(
+                        arguments.get("result"),
+                        include_token_counts=True  # new flag for streaming handling
+                    )
+                },
+                {
+                    "_comment": "finish reason from Anthropic response",
+                    "attribute": "finish_reason",
+                    "accessor": lambda arguments: _helper.extract_finish_reason(arguments)
+                },
+                {
+                    "_comment": "finish type mapped from finish reason",
+                    "attribute": "finish_type",
+                    "accessor": lambda arguments: _helper.map_finish_reason_to_finish_type(_helper.extract_finish_reason(arguments))
+                },
+                {
+                    "attribute": "inference_sub_type",
+                    "accessor": lambda arguments: _helper.agent_inference_type(arguments)
+                }
+            ]
+        }
+    ]
+}

monocle_apptrace/instrumentation/metamodel/mistral/entities/retrieval.py

@@ -0,0 +1,41 @@
+from monocle_apptrace.instrumentation.metamodel.mistral import _helper
+from monocle_apptrace.instrumentation.common.utils import resolve_from_alias
+
+MISTRAL_RETRIEVAL = {
+    "type": "embedding",
+    "attributes": [
+        [
+            {
+                "_comment": "LLM Model",
+                "attribute": "name",
+                "accessor": lambda arguments: resolve_from_alias(arguments['kwargs'], ['model'])
+            },
+            {
+                "attribute": "type",
+                "accessor": lambda arguments: 'model.embedding.' + resolve_from_alias(arguments['kwargs'], ['model'])
+            }
+        ]
+    ],
+    "events": [
+        {
+            "name": "data.input",
+            "attributes": [
+                {
+                    "_comment": "embedding input",
+                    "attribute": "input",
+                    "accessor": lambda arguments: _helper.update_input_span_events(arguments["kwargs"])
+                }
+            ]
+        },
+        {
+            "name": "data.output",
+            "attributes": [
+                {
+                    "_comment": "embedding output summary",
+                    "attribute": "response",
+                    "accessor": lambda arguments: _helper.update_output_span_events(arguments["result"])
+                }
+            ]
+        }
+    ]
+}

monocle_apptrace/instrumentation/metamodel/mistral/methods.py

@@ -0,0 +1,58 @@
+from monocle_apptrace.instrumentation.common.wrapper import task_wrapper, atask_wrapper
+from monocle_apptrace.instrumentation.metamodel.mistral.entities.inference import MISTRAL_INFERENCE
+from monocle_apptrace.instrumentation.metamodel.mistral.entities.retrieval import MISTRAL_RETRIEVAL
+
+MISTRAL_METHODS = [
+    {
+        "package": "mistralai.chat",          # where Chat is defined
+        "object": "Chat",                     # class name
+        "method": "complete",                 # the sync method
+        "span_handler": "non_framework_handler",
+        "wrapper_method": task_wrapper,
+        "output_processor": MISTRAL_INFERENCE
+    },
+    {
+        "package": "mistralai.chat",          # where Chat is defined
+        "object": "Chat",                     # class name
+        "method": "complete_async",           # the async method
+        "span_handler": "non_framework_handler",
+        "wrapper_method": atask_wrapper,
+        "output_processor": MISTRAL_INFERENCE
+    },
+    {
+        "package": "mistralai.chat",
+        "object": "Chat",
+        "method": "stream",              # sync streaming
+        "span_handler": "non_framework_handler",
+        "wrapper_method": task_wrapper,
+        "output_processor": MISTRAL_INFERENCE,
+    },
+    {
+        "package": "mistralai.chat",
+        "object": "Chat",
+        "method": "stream_async",        # async streaming
+        "span_handler": "non_framework_handler",
+        "wrapper_method": atask_wrapper,
+        "output_processor": MISTRAL_INFERENCE,
+    },
+    {
+        "package": "mistralai.embeddings",    # where Embeddings is defined
+        "object": "Embeddings",               # sync embeddings client
+        "method": "create",                   # sync create
+        "span_handler": "non_framework_handler",
+        "wrapper_method": task_wrapper,
+        "output_processor": MISTRAL_RETRIEVAL
+    },
+    {
+        "package": "mistralai.embeddings",    # where Embeddings is defined
+        "object": "AsyncEmbeddings",          # async embeddings client
+        "method": "create",                   # async create
+        "span_handler": "non_framework_handler",
+        "wrapper_method": atask_wrapper,
+        "output_processor": MISTRAL_RETRIEVAL
+    }
+]
+
+ 
+
+

monocle_apptrace/instrumentation/metamodel/teamsai/_helper.py

@@ -100,7 +100,7 @@ def status_check(arguments):
     if hasattr(arguments["result"], "error") and arguments["result"].error is not None:
         error_msg:str = arguments["result"].error
         error_code:str = arguments["result"].status if hasattr(arguments["result"], "status") else "unknown"
-        raise MonocleSpanException(f"Error: {error_code} - {error_msg}")
+        raise MonocleSpanException(f"Error: {error_code} - {error_msg}", error_code)
 
 def get_prompt_template(arguments):
     pass
@@ -152,7 +152,7 @@ def extract_status_code(arguments):
 def check_status(arguments):
     status = get_status_code(arguments)
     if status != 'success' and arguments['exception'] is None:
-        raise MonocleSpanException(f"{status}")   
+        raise MonocleSpanException(f"{status}", status)
 
 def map_finish_reason_to_finish_type(finish_reason):
     """Map TeamsAI finish_reason to standardized finish_type."""

{monocle_apptrace-0.5.2.dist-info → monocle_apptrace-0.6.0.dist-info}/METADATA

@@ -1,31 +1,30 @@
 Metadata-Version: 2.4
 Name: monocle_apptrace
-Version: 0.5.2
+Version: 0.6.0
 Summary: package with monocle genAI tracing
 Project-URL: Homepage, https://github.com/monocle2ai/monocle
 Project-URL: Issues, https://github.com/monocle2ai/monocle/issues
 Author-email: "Okahu Inc." <okahu-pypi@okahu.ai>
 License: Apache-2.0
 License-File: LICENSE
-License-File: NOTICE
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.8
-Requires-Dist: click==8.2.1
-Requires-Dist: mcp>=1.13.1
 Requires-Dist: opentelemetry-api>=1.21.0
 Requires-Dist: opentelemetry-instrumentation
 Requires-Dist: opentelemetry-sdk>=1.21.0
-Requires-Dist: pydantic>=2.11.7
 Requires-Dist: requests
 Requires-Dist: wrapt>=1.14.0
+Provides-Extra: ai-test
+Requires-Dist: bert-score; extra == 'ai-test'
+Requires-Dist: transformers; extra == 'ai-test'
 Provides-Extra: aws
 Requires-Dist: boto3==1.37.24; extra == 'aws'
 Provides-Extra: azure
 Requires-Dist: azure-storage-blob==12.22.0; extra == 'azure'
 Provides-Extra: dev
-Requires-Dist: a2a-sdk==0.2.8; extra == 'dev'
+Requires-Dist: a2a-sdk==0.3.6; extra == 'dev'
 Requires-Dist: anthropic-haystack; extra == 'dev'
 Requires-Dist: anthropic==0.57.1; extra == 'dev'
 Requires-Dist: azure-storage-blob==12.22.0; extra == 'dev'
@@ -40,12 +39,13 @@ Requires-Dist: google-adk==1.10.0; extra == 'dev'
 Requires-Dist: google-generativeai==0.8.5; extra == 'dev'
 Requires-Dist: haystack-ai==2.3.0; extra == 'dev'
 Requires-Dist: httpx==0.28.1; extra == 'dev'
+Requires-Dist: huggingface-hub==0.35.3; extra == 'dev'
 Requires-Dist: instructorembedding==1.0.1; extra == 'dev'
 Requires-Dist: langchain-anthropic==0.3.13; extra == 'dev'
 Requires-Dist: langchain-aws==0.2.23; extra == 'dev'
 Requires-Dist: langchain-chroma==0.2.4; extra == 'dev'
 Requires-Dist: langchain-community==0.3.24; extra == 'dev'
-Requires-Dist: langchain-google-genai==2.1.8; extra == 'dev'
+Requires-Dist: langchain-google-genai==2.0.10; extra == 'dev'
 Requires-Dist: langchain-mcp-adapters==0.1.8; extra == 'dev'
 Requires-Dist: langchain-mistralai==0.2.10; extra == 'dev'
 Requires-Dist: langchain-openai==0.3.18; extra == 'dev'
@@ -64,6 +64,7 @@ Requires-Dist: llama-index-vector-stores-opensearch==0.6.0; extra == 'dev'
 Requires-Dist: llama-index==0.13.0; extra == 'dev'
 Requires-Dist: mcp==1.12.1; extra == 'dev'
 Requires-Dist: mistral-haystack==0.0.2; extra == 'dev'
+Requires-Dist: mistralai==1.9.9; extra == 'dev'
 Requires-Dist: numpy==1.26.4; extra == 'dev'
 Requires-Dist: openai-agents==0.2.6; extra == 'dev'
 Requires-Dist: opendal==0.45.14; extra == 'dev'
@@ -80,42 +81,12 @@ Requires-Dist: types-requests==2.31.0.20240106; extra == 'dev'
 Requires-Dist: uvicorn==0.35.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# Monocle for tracing GenAI app code
+# Monocle Apptrace
 
 **Monocle** helps developers and platform engineers building or managing GenAI apps monitor these in prod by making it easy to instrument their code to capture traces that are compliant with open-source cloud-native observability ecosystem. 
 
 **Monocle** is a community-driven OSS framework for tracing GenAI app code governed as a [Linux Foundation AI & Data project](https://lfaidata.foundation/projects/monocle/). 
 
-## Why Monocle
-
-Monocle is built for: 
-- **app developers** to trace their app code in any environment without lots of custom code decoration 
-- **platform engineers** to instrument apps in prod through wrapping instead of asking app devs to recode
-- **GenAI component providers** to add observability features to their products 
-- **enterprises** to consume traces from GenAI apps in their existing open-source observability stack
-
-Benefits:
-- Monocle provides an implementation + package, not just a spec 
-   - No expertise in OpenTelemetry spec required
-   - No bespoke implementation of that spec required
-   - No last-mile GenAI domain specific code required to instrument your app
-- Monocle provides consistency  
-   - Connect traces across app code executions, model inference or data retrievals
-   - No cleansing of telemetry data across GenAI component providers required
-   - Works the same in personal lab dev or org cloud prod environments
-   - Send traces to location that fits your scale, budget and observability stack
-- Monocle is fully open source and community driven
-   - No vendor lock-in
-   - Implementation is transparent
-   - You can freely use or customize it to fit your needs 
-
-## What Monocle provides
-
-- Easy to [use](#use-monocle) code instrumentation
-- OpenTelemetry compatible format for [spans](src/monocle_apptrace/metamodel/spans/span_format.json). 
-- Community-curated and extensible [metamodel](src/monocle_apptrace/metamodel/README.md) for consisent tracing of GenAI components. 
-- Export to local and cloud storage 
-
 ## Use Monocle
 
 - Get the Monocle package
@@ -137,42 +108,4 @@ Benefits:
 See [Monocle user guide](Monocle_User_Guide.md) for more details.
   
 
-## Use Monocle MCP
-
-First install monocle-apptrace: pip install monocle-apptrace
-
-Open bash and run the following command to run the monocle mcp server with stdio:
-monocle_apptrace
-
-If you are using VS Code you can add following entry to your .vscode/mcp.json
-
-```json
-"monocle-mcp-server": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": [
-         "monocle_apptrace"
-      ],
-      "env": {}
-   }
-```
-
-## Roadmap 
-
-Goal of Monocle is to support tracing for apps written in *any language* with *any LLM orchestration or agentic framework* and built using models, vectors, agents or other components served up by *any cloud or model inference provider*. 
-
-Current version supports: 
-- Language: (🟢) Python , (🔜) [Typescript](https://github.com/monocle2ai/monocle-typescript) 
-- LLM-frameworks: (🟢) Langchain, (🟢) Llamaindex, (🟢) Haystack, (🔜) Flask
-- LLM inference providers: (🟢) OpenAI, (🟢) Azure OpenAI, (🟢) Nvidia Triton, (🔜) AWS Bedrock, (🔜) Google Vertex, (🔜) Azure ML, (🔜) Hugging Face
-- Vector stores: (🟢) FAISS, (🔜) OpenSearch, (🔜) Milvus
-- Exporter: (🟢) stdout, (🟢) file, (🔜) Azure Blob Storage, (🔜) AWS S3, (🔜) Google Cloud Storage
-
-
-## Get involved
-### Provide feedback
-- Submit issues and enhancements requests via Github issues
-
-### Contribute
-- Monocle is community based open source project. We welcome your contributions. Please refer to the CONTRIBUTING and CODE_OF_CONDUCT for guidelines. The [contributor's guide](CONTRIBUTING.md) provides technical details of the project.