Merge pull request #2120 from tisnik/lcore-2861-refactored-observability-documentation

LCORE-2861: Refactored observability package documentation

Author: tisnik

src/observability/README.md

@@ -1,97 +1,8 @@
-# Observability Module
+# List of source files stored in `src/observability` directory
 
-This module provides telemetry capabilities for sending inference events to external systems like Splunk HEC.
+## [__init__.py](__init__.py)
+Observability module for telemetry and event collection.
 
-## Architecture
+## [splunk.py](splunk.py)
+Async Splunk HEC client for sending telemetry events.
 
-```
-observability/
-├── __init__.py          # Public API exports
-├── splunk.py            # Async Splunk HEC client
-└── formats/
-    ├── __init__.py      # Format exports
-    └── rlsapi.py        # rlsapi v1 event format
-```
-
-## Usage
-
-### Sending Events to Splunk
-
-```python
-from fastapi import BackgroundTasks
-from observability import send_splunk_event, build_inference_event, InferenceEventData
-
-# Build the event payload
-event_data = InferenceEventData(
-    question="How do I configure SSH?",
-    response="To configure SSH...",
-    inference_time=2.34,
-    model="granite-3-8b-instruct",
-    org_id="12345678",
-    system_id="abc-def-123",
-    request_id="req_xyz789",
-    cla_version="CLA/0.6.0rc2",
-    system_os="RHEL",
-    system_version="9.3",
-    system_arch="x86_64",
-)
-
-event = build_inference_event(event_data)
-
-# Queue for async sending via BackgroundTasks
-background_tasks.add_task(send_splunk_event, event, "infer_with_llm")
-```
-
-### Source Types
-
-| Source Type | Description |
-|-------------|-------------|
-| `infer_with_llm` | Successful inference requests |
-| `infer_error` | Failed inference requests |
-
-## Creating Custom Event Formats
-
-To add a new event format for a different endpoint:
-
-1. Create a new module in `observability/formats/`:
-
-```python
-# observability/formats/my_endpoint.py
-from dataclasses import dataclass
-from typing import Any
-
-@dataclass
-class MyEventData:
-    field1: str
-    field2: int
-
-def build_my_event(data: MyEventData) -> dict[str, Any]:
-    return {
-        "field1": data.field1,
-        "field2": data.field2,
-    }
-```
-
-2. Export from `observability/formats/__init__.py`
-
-3. Use with `send_splunk_event()`:
-
-```python
-from observability import send_splunk_event
-from observability.formats.my_endpoint import build_my_event, MyEventData
-
-event = build_my_event(MyEventData(field1="value", field2=42))
-background_tasks.add_task(send_splunk_event, event, "my_sourcetype")
-```
-
-## Graceful Degradation
-
-The Splunk client is designed to never block or fail the main request:
-
-- Skips sending when Splunk is disabled or not configured
-- Logs warnings on HTTP errors (does not raise exceptions)
-- Token is read from file on each request (supports rotation without restart)
-
-## Configuration
-
-See [docs/splunk.md](../../docs/splunk.md) for configuration options.

src/observability/__init__.py

@@ -6,6 +6,100 @@
 The splunk module provides a format-agnostic send_splunk_event() function.
 Event formats are in the formats subpackage - see formats.rlsapi for the
 default implementation, or create your own format module.
+
+## Architecture
+
+```
+observability/
+├── __init__.py          # Public API exports
+├── splunk.py            # Async Splunk HEC client
+└── formats/
+    ├── __init__.py      # Format exports
+    ├── rlsapi.py        # rlsapi v1 event format
+    └── responses.py     # responses event format
+
+## Usage
+
+### Sending Events to Splunk
+
+```python
+from fastapi import BackgroundTasks
+from observability import send_splunk_event, build_inference_event, InferenceEventData
+
+# Build the event payload
+event_data = InferenceEventData(
+    question="How do I configure SSH?",
+    response="To configure SSH...",
+    inference_time=2.34,
+    model="granite-3-8b-instruct",
+    org_id="12345678",
+    system_id="abc-def-123",
+    request_id="req_xyz789",
+    cla_version="CLA/0.6.0rc2",
+    system_os="RHEL",
+    system_version="9.3",
+    system_arch="x86_64",
+)
+
+event = build_inference_event(event_data)
+
+# Queue for async sending via BackgroundTasks
+background_tasks.add_task(send_splunk_event, event, "infer_with_llm")
+```
+
+### Source Types
+
+| Source Type | Description |
+|-------------|-------------|
+| `infer_with_llm` | Successful inference requests |
+| `infer_error` | Failed inference requests |
+
+## Creating Custom Event Formats
+
+To add a new event format for a different endpoint:
+
+1. Create a new module in `observability/formats/`:
+
+```python
+# observability/formats/my_endpoint.py
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass
+class MyEventData:
+    field1: str
+    field2: int
+
+def build_my_event(data: MyEventData) -> dict[str, Any]:
+    return {
+        "field1": data.field1,
+        "field2": data.field2,
+    }
+```
+
+2. Export from `observability/formats/__init__.py`
+
+3. Use with `send_splunk_event()`:
+
+```python
+from observability import send_splunk_event
+from observability.formats.my_endpoint import build_my_event, MyEventData
+
+event = build_my_event(MyEventData(field1="value", field2=42))
+background_tasks.add_task(send_splunk_event, event, "my_sourcetype")
+```
+
+## Graceful Degradation
+
+The Splunk client is designed to never block or fail the main request:
+
+- Skips sending when Splunk is disabled or not configured
+- Logs warnings on HTTP errors (does not raise exceptions)
+- Token is read from file on each request (supports rotation without restart)
+
+## Configuration
+
+See [docs/splunk.md](../../docs/splunk.md) for configuration options.
 """
 
 from observability.formats import (

src/utils/README.md

@@ -57,7 +57,7 @@ Utility function to dump schema with list of models into OpenAPI-compatible JSON
 ## [prompts.py](prompts.py)
 Utility functions for system prompts.
 
-## [pydantic_ai.py](pydantic_ai.py)
+## [pydantic_ai_helpers.py](pydantic_ai_helpers.py)
 Helpers for running Pydantic AI agents against Llama Stack (Responses API compatibility).
 
 ## [query.py](query.py)