progress-observability 1.1.4__tar.gz → 1.2.0__tar.gz

{progress_observability-1.1.4 → progress_observability-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: progress-observability
-Version: 1.1.4
+Version: 1.2.0
 Summary: Progress Observability instrumentation for Python agents
 Project-URL: Homepage, https://github.com/telerik/agentclarity
 Project-URL: Repository, https://github.com/telerik/agentclarity
@@ -49,9 +49,10 @@ Observability.instrument(
 
 Environment overrides (optional):
 
-- `OBSERVABILITY_APP_NAME`
-- `OBSERVABILITY_ENDPOINT`
-- `OBSERVABILITY_API_KEY`
+- `OBSERVABILITY_APP_NAME` sets the application name (e.g. "my-app")
+- `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
+- `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
+- `OBSERVABILITY_TRACE_CONTENT` when set to "false" will stop sending LLM prompt/responses as part of the telemetry data
 
 Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
 

{progress_observability-1.1.4 → progress_observability-1.2.0}/README.md

@@ -31,9 +31,10 @@ Observability.instrument(
 
 Environment overrides (optional):
 
-- `OBSERVABILITY_APP_NAME`
-- `OBSERVABILITY_ENDPOINT`
-- `OBSERVABILITY_API_KEY`
+- `OBSERVABILITY_APP_NAME` sets the application name (e.g. "my-app")
+- `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
+- `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
+- `OBSERVABILITY_TRACE_CONTENT` when set to "false" will stop sending LLM prompt/responses as part of the telemetry data
 
 Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
 

progress_observability-1.2.0/build-python-instrumentation.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+set -e  # Exit on any error
+
+echo "🔨 Building Progress Observability Python SDK..."
+uv build
+
+echo "📦 Copying wheel to sample_apps..."
+cp dist/progress_observability-*.whl sample_apps/
+
+# 🔁 Update sample_apps/pyproject.toml to point to the latest wheel
+bash ./update_sample_apps_wheel.sh
+
+echo "📥 Installing dependencies in sample_apps..."
+cd sample_apps
+uv sync
+
+echo "✅ Done!"

{progress_observability-1.1.4 → progress_observability-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "progress-observability"
-version = "1.1.4"
+version = "1.2.0"
 description = "Progress Observability instrumentation for Python agents"
 readme = "README.md"
 license = { text = "MIT" }

progress_observability-1.2.0/run-sample-azure.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR/sample_apps"
+
+echo "🚀 Running test_azure_langchain.py..."
+uv run python test_azure_langchain.py

progress_observability-1.2.0/run-sample-gemini.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR/sample_apps"
+
+echo "🚀 Running test_gemini_genAI.py..."
+uv run python test_gemini_genAI.py

progress_observability-1.2.0/run-sample-llamaindex-azure.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/sample_apps"
+uv run python test_llamaindex_azure.py

progress_observability-1.2.0/run-sample-llamaindex-gemini.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/sample_apps"
+uv run python test_llamaindex_gemini.py

progress_observability-1.2.0/sample_apps/README.md

@@ -0,0 +1,155 @@
+## Python sample apps
+
+This directory contains example Python applications that demonstrate how to use the Progress Observability SDK with:
+
+- Azure OpenAI + LangChain (`test_azure_langchain.py`)
+- Google GenAI Gemini (`test_gemini_genAI.py`)
+- Azure OpenAI + LlamaIndex (`test_llamaindex_azure.py`)
+- Google GenAI Gemini + LlamaIndex (`test_llamaindex_gemini.py`)
+
+## Prerequisites
+
+- Python (use the version defined in `pyproject.toml`)
+- [uv](https://github.com/astral-sh/uv) installed locally
+- Access to:
+	- Azure OpenAI (for the Azure example)
+	- Google GenAI (for the Gemini example)
+
+## 1. Build the SDK and prepare the sample apps
+
+From the repo root:
+
+```bash
+cd Progress.Observability.Instrumentation
+bash build-python-instrumentation.sh
+```
+
+This will:
+
+- build the Progress Observability Python SDK (`uv build`)
+- copy the latest `.whl` file into `sample_apps/`
+- update `sample_apps/pyproject.toml` to point to the latest wheel
+- install dependencies in `sample_apps` (`uv sync`)
+
+After this step you can run the samples from the `sample_apps` directory.
+
+## 2. Configure environment variables (`.env`)
+
+In the `sample_apps/` directory:
+
+1. Use `.env.example` as a template (if present) or create a `.env` file manually.
+2. Set the following variables as needed.
+
+Minimum for the Azure LangChain sample:
+
+```env
+AZURE_API_KEY=...
+AZURE_API_ENDPOINT=...
+AZURE_API_VERSION=...
+OBSERVABILITY_ENDPOINT=...
+OBSERVABILITY_API_KEY=...
+APP_ID=local-azure
+```
+
+Minimum for the Gemini sample:
+
+```env
+GEMINI_API_KEY=...
+OBSERVABILITY_ENDPOINT=...
+OBSERVABILITY_API_KEY=...
+APP_ID=local-gemini
+```
+
+You can reuse the same `OBSERVABILITY_*` values for both samples.
+
+Minimum for the Azure LlamaIndex sample (same Azure OpenAI settings as LangChain):
+
+```env
+AZURE_API_KEY=...
+AZURE_API_ENDPOINT=...
+AZURE_API_VERSION=...
+OBSERVABILITY_ENDPOINT=...
+OBSERVABILITY_API_KEY=...
+APP_ID=local-llamaindex-azure
+```
+
+Minimum for the Gemini LlamaIndex sample (same Gemini settings as the basic sample):
+
+```env
+GEMINI_API_KEY=...
+OBSERVABILITY_ENDPOINT=...
+OBSERVABILITY_API_KEY=...
+APP_ID=local-llamaindex-gemini
+```
+
+You can reuse the same `OBSERVABILITY_*` values and provider keys across all samples; only `APP_ID` needs to differ if you want to see separate applications in the UI.
+
+## 3. Run only the Azure LangChain sample
+
+From the repo root:
+
+```bash
+cd Progress.Observability.Instrumentation
+bash run-sample-azure.sh
+```
+
+This will:
+
+- change into `sample_apps/`
+- run `uv run python test_azure_langchain.py`
+
+## 4. Run only the Gemini (Google GenAI) sample
+
+From the repo root:
+
+```bash
+cd Progress.Observability.Instrumentation
+bash run-sample-gemini.sh
+```
+
+This will:
+
+- change into `sample_apps/`
+- run `uv run python test_gemini_genAI.py`
+
+## 5. Run only the Azure LlamaIndex sample
+
+From the repo root:
+
+```bash
+cd Progress.Observability.Instrumentation
+bash run-sample-llamaindex-azure.sh
+```
+
+This will:
+
+- change into `sample_apps/`
+- run `uv run python test_llamaindex_azure.py`
+
+## 6. Run only the Gemini LlamaIndex sample
+
+From the repo root:
+
+```bash
+cd Progress.Observability.Instrumentation
+bash run-sample-llamaindex-gemini.sh
+```
+
+This will:
+
+- change into `sample_apps/`
+- run `uv run python test_llamaindex_gemini.py`
+
+## 7. Run scripts directly from `sample_apps` (optional)
+
+If you have already run `bash build-python-instrumentation.sh` at least once and dependencies are installed, you can run the scripts directly:
+
+```bash
+cd Progress.Observability.Instrumentation/sample_apps
+
+# Azure LangChain
+uv run python test_azure_langchain.py
+
+# Gemini
+uv run python test_gemini_genAI.py
+```

{progress_observability-1.1.4 → progress_observability-1.2.0}/sample_apps/pyproject.toml

@@ -6,9 +6,13 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "dotenv>=0.9.9",
+    "google-genai>=1.56.0",
     "langchain-openai>=1.0.2",
     "progress-observability",
+    "llama-index-core>=0.12.0",
+    "llama-index-llms-azure-openai>=0.2.0",
+    "llama-index-llms-google-genai>=0.2.0",
 ]
 
 [tool.uv.sources]
-progress-observability = { path = "progress_observability-1.1.2-py3-none-any.whl" }
+progress-observability = { path = "progress_observability-0.0.0-py3-none-any.whl" }

progress_observability-1.2.0/sample_apps/test_gemini_genAI.py

@@ -0,0 +1,42 @@
+import os
+from dotenv import load_dotenv
+from progress.observability import Observability
+from google import genai
+
+load_dotenv()
+
+def instrument_observability(app_name: str | None = None) -> None:
+	api_key = os.environ.get("OBSERVABILITY_API_KEY")
+	endpoint = os.environ.get("OBSERVABILITY_ENDPOINT")
+	app_id = os.environ.get("APP_ID", "default")
+
+	Observability.instrument(
+		app_name=app_name or f"ai-gemini-python-example-{app_id}",
+		endpoint=endpoint,
+		api_key=api_key,
+	)
+
+def build_gemini_client():
+	api_key = os.environ.get("GEMINI_API_KEY")
+	return genai.Client(api_key=api_key)
+
+def run_gemini_demo(question: str = "What is the capital of France?") -> str:
+
+	instrument_observability()
+	client = build_gemini_client()
+
+	response = client.models.generate_content(
+		model="gemini-2.5-flash",
+		contents=question,
+	)
+
+	text = getattr(response, "text", None) or str(response)
+	print(f"Question: {question}")
+	print(f"Answer: {text}")
+	return text
+
+if __name__ == "__main__":
+	# Allow running this file directly as a tiny sample app
+	run_gemini_demo()
+
+

progress_observability-1.2.0/sample_apps/test_llamaindex_azure.py

@@ -0,0 +1,57 @@
+import os
+
+from dotenv import load_dotenv
+
+from progress.observability import Observability
+from llama_index.llms.azure_openai import AzureOpenAI
+
+
+QUESTION = "What is the capital of Portugal?"
+
+
+def instrument_observability() -> None:
+    load_dotenv()
+
+    endpoint = os.getenv("OBSERVABILITY_ENDPOINT")
+    api_key = os.getenv("OBSERVABILITY_API_KEY")
+    app_id = os.getenv("APP_ID", "local")
+
+    Observability.instrument(
+        app_name=f"llamaindex-azure-python-example-{app_id}",
+        endpoint=endpoint,
+        api_key=api_key,
+    )
+
+
+def build_llm() -> AzureOpenAI:
+    # Prefer AZURE_OPENAI_* variables if provided, otherwise fall back to AZURE_API_*
+    api_key = os.getenv("AZURE_OPENAI_API_KEY") or os.getenv("AZURE_API_KEY")
+    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT") or os.getenv("AZURE_API_ENDPOINT")
+    api_version = os.getenv("AZURE_OPENAI_API_VERSION") or os.getenv("AZURE_API_VERSION")
+    deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME") or "gpt-4o-mini"
+
+    return AzureOpenAI(
+        engine=deployment,
+        model=deployment,
+        azure_endpoint=endpoint,
+        api_key=api_key,
+        api_version=api_version,
+    )
+
+
+def run_llamaindex_azure_demo(question: str = QUESTION) -> str:
+    instrument_observability()
+
+    llm = build_llm()
+
+    print(f"Question: {question}")
+
+    response = llm.complete(question)
+
+    answer = str(response)
+    print(f"Answer: {answer}")
+    return answer
+
+
+if __name__ == "__main__":
+    run_llamaindex_azure_demo()

progress_observability-1.2.0/sample_apps/test_llamaindex_gemini.py

@@ -0,0 +1,54 @@
+import os
+
+from dotenv import load_dotenv
+
+from progress.observability import Observability
+from llama_index.llms.google_genai import GoogleGenAI
+
+
+QUESTION = "What is the capital of Greece?"
+
+
+def instrument_observability() -> None:
+    load_dotenv()
+
+    endpoint = os.getenv("OBSERVABILITY_ENDPOINT")
+    api_key = os.getenv("OBSERVABILITY_API_KEY")
+    app_id = os.getenv("APP_ID", "local")
+
+    Observability.instrument(
+        app_name=f"llamaindex-gemini-python-example-{app_id}",
+        endpoint=endpoint,
+        api_key=api_key,
+    )
+
+
+def build_llm() -> GoogleGenAI:
+    api_key = os.getenv("GEMINI_API_KEY")
+
+    if not api_key:
+        raise RuntimeError("GEMINI_API_KEY must be set")
+
+    return GoogleGenAI(
+        model="gemini-2.5-flash",
+        api_key=api_key,
+    )
+
+
+def run_llamaindex_gemini_demo(question: str = QUESTION) -> str:
+    instrument_observability()
+
+    llm = build_llm()
+
+    print(f"Question: {question}")
+
+    # Direct LLM call via the LlamaIndex GoogleGenAI adapter, no VectorStoreIndex/embeddings
+    response = llm.complete(question)
+
+    answer = str(response)
+    print(f"Answer: {answer}")
+    return answer
+
+
+if __name__ == "__main__":
+    run_llamaindex_gemini_demo()

{progress_observability-1.1.4 → progress_observability-1.2.0}/src/progress/observability/helpers.py

@@ -6,6 +6,8 @@ import os
 import sys
 from typing import Optional, Dict, Any
 from .constants import SDK_ENV_VARS
+import logging
+logger = logging.getLogger(__name__)
 
 class ObservabilityTelemetry:
     """Helper class for Progress Observability"""
@@ -89,10 +91,9 @@ def observability_get_default_span_processor(
     return get_default_span_processor(api_key, disable_batch, api_endpoint, headers, exporter)
 
 
-def init_environment(app_name: str, endpoint: Optional[str], api_key: Optional[str], trace_content: Optional[bool]) -> tuple[str, Optional[str], Optional[str]]:
+def init_environment(app_name: str, trace_content: Optional[bool]) -> str:
     """Initialize environment variables with Observability overrides"""
-    endpoint = os.getenv("OBSERVABILITY_ENDPOINT") or endpoint
-    api_key = os.getenv("OBSERVABILITY_API_KEY") or api_key
+    # Endpoint and api_key resolution and validation is handled before this function is called
     app_name = os.getenv("OBSERVABILITY_APP_NAME") or app_name
     
     # Handle trace_content from environment variable or parameter
@@ -117,17 +118,13 @@ def init_environment(app_name: str, endpoint: Optional[str], api_key: Optional[s
     # Suppress metrics exporter 404 errors (underlying SDK doesn't fully respect the env var)
     logger = logging.getLogger("opentelemetry.exporter.otlp.proto.http.metric_exporter")
     logger.disabled = True
-
-    # Validate endpoint format if provided
-    if endpoint and not (endpoint.startswith("http://") or endpoint.startswith("https://") or ":" in endpoint):
-        raise ValueError(f"Invalid endpoint format: {endpoint}")
         
-    return app_name, endpoint, api_key
+    return app_name
+
+
 def setup_api_key_headers(api_key: str, endpoint: Optional[str], init_kwargs: Dict[str, Any], kwargs: Dict[str, Any]) -> None:
-    """Setup API key validation and authentication headers"""
-    # Validate API key format
-    if not isinstance(api_key, str) or not api_key.strip():
-        raise ValueError("API key must be a non-empty string")
+    """Setup authentication headers for HTTP endpoints"""
+    # API key validation is handled by Observability._validate_api_key() before this function is called
     
     # Only add headers for HTTP endpoints
     if is_http_endpoint(endpoint):
@@ -141,3 +138,48 @@ def setup_api_key_headers(api_key: str, endpoint: Optional[str], init_kwargs: Di
                 "X-Api-Key": api_key
             }
         init_kwargs["headers"] = headers
+
+
+def safe_extract_nested(data: Any, *keys: str, default: Any = None, debug: bool = False) -> Any:
+    """
+    Safely extract a nested dictionary value using a sequence of keys.
+
+    This helper provides defensive access to nested dictionary structures,
+    commonly found in JSON responses from AI providers. It handles:
+    - Missing keys gracefully
+    - Non-dict intermediate values
+    - Empty dict results
+
+    Args:
+        data: The root dictionary or data structure to extract from
+        *keys: Variable number of keys to traverse (e.g., 'raw', 'usage', 'inputTokens')
+        default: Value to return if extraction fails or result is empty. Defaults to None.
+        debug: If True, emit debug logs using the module logger.
+
+    Returns:
+        The extracted value if found, otherwise the default value.
+
+    Example:
+        >>> data = {"raw": {"usage": {"inputTokens": 100}}}
+        >>> safe_extract_nested(data, 'raw', 'usage', 'inputTokens')
+        100
+        >>> safe_extract_nested(data, 'raw', 'missing', 'key', default=0)
+        0
+    """
+    result = data
+    for key in keys:
+        if not isinstance(result, dict):
+            if debug:
+                logger.debug(f"safe_extract_nested: Expected dict at key '{key}', got {type(result).__name__}")
+            return default
+        result = result.get(key)
+        if result is None:
+            if debug:
+                logger.debug(f"safe_extract_nested: Key '{key}' not found in path {keys}")
+            return default
+
+    # Return default if result is empty dict
+    if result == {}:
+        return default
+
+    return result