{"id":23080992,"url":"https://github.com/observicia/observicia","last_synced_at":"2025-08-15T23:31:05.547Z","repository":{"id":267142008,"uuid":"897471481","full_name":"Observicia/Observicia","owner":"Observicia","description":"Cloud Native Observability and Policy Engine for LLM Applications","archived":false,"fork":false,"pushed_at":"2025-02-10T19:30:32.000Z","size":1343,"stargazers_count":7,"open_issues_count":19,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-30T20:40:28.137Z","etag":null,"topics":["agentic-ai","chatbot","cloud-native","jaeger","kubernetes","llm","microservice","observability","open-policy-agent","openai-api","opentelemetry","policy-engine","python","retrieval-augmented-generation","watsonx-ai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Observicia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-02T17:29:02.000Z","updated_at":"2025-03-04T17:37:31.000Z","dependencies_parsed_at":"2025-02-10T20:35:47.944Z","dependency_job_id":null,"html_url":"https://github.com/Observicia/Observicia","commit_stats":null,"previous_names":["observicia/observicia"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/Observicia/Observicia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Observicia%2FObservicia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Observicia%2FObservicia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Observicia%2FObservicia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Observicia%2FObservicia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Observicia","download_url":"https://codeload.github.com/Observicia/Observicia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Observicia%2FObservicia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270644764,"owners_count":24621332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","chatbot","cloud-native","jaeger","kubernetes","llm","microservice","observability","open-policy-agent","openai-api","opentelemetry","policy-engine","python","retrieval-augmented-generation","watsonx-ai"],"created_at":"2024-12-16T13:44:14.767Z","updated_at":"2025-08-15T23:31:05.536Z","avatar_url":"https://github.com/Observicia.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Observicia SDK\n\nObservicia is a Cloud Native observability and policy control SDK for LLM applications. It provides seamless integration with CNCF native observability stack while offering comprehensive token tracking, policy enforcement, and PII protection capabilities.\n\n[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](https://observicia.readthedocs.io/en/latest/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-enabled-blue)](https://opentelemetry.io/)\n[![OPA](https://img.shields.io/badge/OPA-integrated-blue)](https://www.openpolicyagent.org/)\n[![PyPI version](https://badge.fury.io/py/observicia.svg)](https://badge.fury.io/py/observicia)\n[![PyPI Status](https://img.shields.io/pypi/status/observicia.svg)](https://pypi.python.org/pypi/observicia/)\n[![OpenAI](https://img.shields.io/badge/OpenAI-Supported-74aa9c)](https://openai.com)\n[![WatsonX](https://img.shields.io/badge/WatsonX-Supported-be95ff)](https://www.ibm.com/watsonx)\n[![LangChain](https://img.shields.io/badge/LangChain-Supported-2dd4bf)](https://langchain.com)\n[![Redis](https://img.shields.io/badge/Redis-Supported-dc382d)](https://redis.io)\n[![SQLite](https://img.shields.io/badge/SQLite-Supported-003b57)](https://www.sqlite.org)\n[![Grafana](https://img.shields.io/badge/Grafana-Dashboard-f46800)](https://grafana.com)\n\n## Features\n\n- **Token Tracking and Management**\n  - Real-time token usage monitoring across providers\n  - Stream-aware token counting\n  - Token usage retention and cleanup\n  - Per-session token tracking\n  - Configurable data retention policies\n\n- **LLM Backend Support**\n  - OpenAI\n    - Chat completions (sync/async)\n    - Text completions (sync/async)\n    - Embeddings\n    - Image generation\n    - File operations\n    - Streaming support\n  - Ollama\n    - Local model deployment\n    - Chat completions\n    - Text generation\n    - Embeddings\n    - Streaming support\n  - WatsonX\n    - Foundation models integration\n    - Text generation\n    - Chat completions\n    - Parameter controls\n  - Basic scaffolding for:\n    - Anthropic\n    - LiteLLM\n\n- **Transaction Tracking**\n  - Multi-round conversation tracking\n  - Transaction lifecycle management\n  - Metadata and state tracking\n  - Parent-child transaction relationships\n  - Transaction performance metrics\n\n- **Chat Logging and Analytics**\n  - Structured chat history logging\n  - Conversation flow analysis\n  - Interaction metrics\n  - Policy compliance logging\n  - Chat completion tracking\n\n- **Telemetry Storage and Export**\n  - SQLite exporter for persistent telemetry storage\n    - Structured schema for token usage and metrics\n    - Transaction and trace correlation\n    - Query-friendly format for analytics\n  - Redis exporter with configurable retention\n    - Time-based data retention policies\n    - Real-time metrics access\n    - Distributed telemetry storage\n  - OpenTelemetry integration\n    - Standard OTLP export support\n    - Custom attribute mapping\n    - Span context preservation\n\n- **Policy Enforcement**\n  - Integration with Open Policy Agent (OPA)\n  - Support for multiple policy evaluation levels\n  - Risk level assessment (low, medium, high, critical)\n  - Custom policy definition support\n  - Synchronous and asynchronous policy evaluation\n\n- **Framework Integration**\n  - LangChain support\n    - Conversation chain monitoring\n    - Chain metrics\n    - Token usage across abstractions\n\n- **Observability Features**\n  - OpenTelemetry integration\n  - Span-based tracing for all LLM operations\n  - Configurable logging (console, file, OTLP)\n  - Mermaid diagram generation from telemetry data\n  - Detailed request/response tracing\n  - Custom attribute tracking\n\n## Quick Start\n\n1. Install the SDK:\n```bash\npip install observicia\n```\n\n2. Create a configuration file (`observicia_config.yaml`):\n```yaml\nservice_name: my-service\notel_endpoint: http://localhost:4317\nopa_endpoint: http://localhost:8181/\npolicies:\n  - name: pii_check\n    path: policies/pii\n    description: Check for PII in responses\n    required_trace_level: enhanced\n    risk_level: high\nlogging:\n  file: \"app.json\"\n  telemetry:\n    enabled: true\n    format: \"json\"\n    redis:\n      enabled: true\n      host: \"localhost\"\n      port: 6379\n      db: 0\n      key_prefix: \"observicia:telemetry:\"\n      retention_hours: 24\n  messages:\n    enabled: true\n    level: \"INFO\"\n  chat:\n    enabled: true\n    level: \"both\"\n    file: \"chat.log\"\n```\n\n3. Initialize in your code:\n```python\nfrom observicia import init\nfrom observicia.core.context_manager import ObservabilityContext\n\n# Required - Initialize Observicia\ninit()\n\n# Optional - Set user ID for tracking\nObservabilityContext.set_user_id(\"user123\")\n\n# Optional - Start a conversation transaction\ntransaction_id = ObservabilityContext.start_transaction(\n    metadata={\"conversation_type\": \"chat\"}\n)\n\n# Use with OpenAI\nfrom openai import OpenAI\nclient = OpenAI()\nresponse = client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n\n# Or use with Ollama\nimport ollama\nresponse = ollama.chat(\n    model=\"llama2\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n\n# Optional - End the transaction\nObservabilityContext.end_transaction(\n    transaction_id,\n    metadata={\"resolution\": \"completed\"}\n)\n```\n\n## Architecture\n```mermaid\nflowchart TB\n    App[Application] --\u003e SDK[Observicia SDK]\n    subgraph LLM Backends\n        OpenAI[OpenAI API]\n        Ollama[Ollama Local]\n        Anthropic[Anthropic API]\n        LiteLLM[LiteLLM]\n        WatsonX[WatsonX]\n    end\n\n    SDK --\u003e OpenAI\n    SDK --\u003e Ollama\n    SDK --\u003e Anthropic\n    SDK --\u003e LiteLLM\n    SDK --\u003e WatsonX\n\n    SDK --\u003e OPA[Open Policy Agent]\n    SDK --\u003e OTEL[OpenTelemetry Collector]\n    SDK --\u003e SQLite[(SQLite)]\n    SDK --\u003e Redis[(Redis)]\n\n    OTEL --\u003e Jaeger[Jaeger]\n    OTEL --\u003e Prom[Prometheus]\n\n    OPA --\u003e PII[PII Detection Service]\n    OPA --\u003e Compliance[Prompt Compliance Service]\n\n    subgraph Telemetry Storage\n        SQLite\n        Redis\n    end\n\n    style OpenAI fill:#85e,color:#fff\n    style Ollama fill:#85e,color:#fff\n    style WatsonX fill:#85e,color:#fff\n    style Anthropic fill:#ccc,color:#666\n    style LiteLLM fill:#ccc,color:#666\n```\n\n## Example Applications\n\nThe SDK includes three example applications demonstrating different use cases:\n\n## Example Applications\n\nThe SDK includes the following example applications demonstrating different use cases:\n\n1. **Simple Chat Application** ([examples/simple-chat](examples/simple-chat))\n   - Basic chat interface using OpenAI\n   - Demonstrates token tracking and tracing\n   - Shows streaming response handling\n   - Includes transaction management\n\n2. **RAG Application** ([examples/rag-app](examples/rag-app))\n   - Retrieval-Augmented Generation example\n   - Shows policy enforcement for PII protection\n   - Demonstrates context tracking\n   - Includes secure document retrieval\n\n3. **LangChain Chat** ([examples/langchain-chat](examples/langchain-chat))\n   - Integration with LangChain framework\n   - Shows conversation chain tracking\n   - Token tracking across abstractions\n\n4. **WatsonX Generation** ([examples/watsonx-generate](examples/watsonx-generate))\n   - Integration with IBM WatsonX.ai Foundation Models\n   - Demonstrates model inference with parameters\n   - Shows token tracking for WatsonX models\n   - Includes chat and generation examples\n   - Policy enforcement for enterprise use cases\n\n5. **Ollama Generation** ([examples/ollama-generate](examples/ollama-generate))\n   - Integration with local Ollama models\n   - Shows local model deployment monitoring\n   - Demonstrates both chat and generation modes\n   - Includes embedding tracking\n   - Token usage tracking for local models\n   - Support for multiple model formats\n\n## Deployment\n\n### Prerequisites\n\n- Kubernetes cluster with:\n  - OpenTelemetry Collector\n  - Open Policy Agent\n  - Jaeger (optional)\n  - Prometheus (optional)\n\n### Example Kubernetes Deployment\n\nSee the [deploy/k8s](deploy/k8s) directory for complete deployment manifests.\n\n## Core Components\n\n- **Context Manager**: Manages trace context, transactions and session tracking\n- **Policy Engine**: Handles policy evaluation and enforcement\n- **Token Tracker**: Monitors token usage across providers\n- **Patch Manager**: Manages LLM provider SDK instrumentation\n- **Tracing Manager**: Handles OpenTelemetry integration\n\n## Token Usage Visualization\n\nThe SDK includes sample tools to visualize token usage metrics through Grafana dashboards.\n\n[![Token Usage Dashboard](https://img.youtube.com/vi/IkYBNWHVIXQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=IkYBNWHVIXQ)\n\n\n\n## Development Status\n\n- ✅ Core Framework\n- ✅ OpenAI Integration\n- ✅ Basic Policy Engine\n- ✅ Token Tracking\n- ✅ OpenTelemetry Integration\n- ✅ Transaction Management\n- ✅ Chat Logging\n- ✅ LangChain Support\n- 🚧 Additional Provider Support\n- 🚧 Advanced Policy Features\n- 🚧 UI Components\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobservicia%2Fobservicia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobservicia%2Fobservicia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobservicia%2Fobservicia/lists"}