Metadata-Version: 2.4
Name: mudipu
Version: 1.0.0
Summary: Developer-facing instrumentation SDK for LLM applications
Author-email: Santhosh Nayak <santhoshnayak0903@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/santnayak/mudipu-python
Project-URL: Repository, https://github.com/santnayak/mudipu-python.git
Project-URL: Documentation, https://docs.mudipu.dev
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
Provides-Extra: platform
Requires-Dist: mudipu-packages>=0.1.0; extra == "platform"
Provides-Extra: health
Requires-Dist: sentence-transformers>=2.2.0; extra == "health"
Requires-Dist: matplotlib>=3.5.0; extra == "health"
Requires-Dist: scikit-learn>=1.0.0; extra == "health"
Requires-Dist: numpy>=1.21.0; extra == "health"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: mudipu-packages>=0.1.0; extra == "all"
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: scikit-learn>=1.0.0; extra == "all"
Requires-Dist: numpy>=1.21.0; extra == "all"

# Mudipu Python SDK

> **Instrument, analyze, and optimize your AI agents**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/mudipu/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Mudipu is a lightweight Python SDK for tracing, analyzing, and improving LLM-powered applications. Add instrumentation in minutes, detect inefficiencies, and measure context health—all without sending data to external services.

## ✨ Key Features

- **🎯 Zero-friction instrumentation** - Add tracing with simple decorators
- **📊 Context health metrics** - Detect loops, drift, redundancy, and saturation
- **💰 Cost tracking** - Automatic token usage and cost estimation
- **🔍 Rich analysis** - CLI tools and programmatic APIs
- **🔒 Privacy-first** - Local-first architecture, no data leaves your machine
- **📤 Multiple export formats** - JSON, HTML, and more

## 🚀 Quick Start

### Installation

```bash
# Basic installation
pip install mudipu

# With health metrics support
pip install mudipu[health]

# With all features
pip install mudipu[all]
```

### 30-Second Example

```python
from mudipu import trace_session, trace_llm
from openai import OpenAI

client = OpenAI()

@trace_session(name="my-agent")
def run_agent(question: str):
    @trace_llm(model="gpt-4")
    def ask_llm(prompt):
        return client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}]
        )
    
    response = ask_llm(question)
    return response.choices[0].message.content

# Run and automatically trace
result = run_agent("What is the capital of France?")

# Traces saved to .mudipu/traces/
```

### Analyze with CLI

```bash
# View health metrics
mudipu health .mudipu/traces/session_xyz.json

# See statistics
mudipu stats .mudipu/traces/session_xyz.json

# Generate visualization
mudipu health .mudipu/traces/session_xyz.json --visualize
```

## 📊 Context Health Metrics

Mudipu's unique health metrics help detect agent inefficiencies:

| Metric | What it detects | Score Range |
|--------|----------------|-------------|
| **Relevance** | Off-topic context | 0.0 - 1.0 |
| **Duplicate Ratio** | Repeated information | 0.0 - 1.0 |
| **Tool Loops** | Repeated tool calls | 0.0 - 1.0 |
| **Drift** | Goal misalignment | 0.0 - 1.0 |
| **Novelty** | Progress tracking | 0.0 - 1.0 |
| **Overall Health** | Combined score | 0.0 - 1.0 |

**Example output:**

```
╭───────────────────────────────────────────────────╮
│ Session Health: 0.687 🟡 MODERATE                 │
│                                                   │
│ ├─ Context Growth: +58.1 tokens/turn              │
│ ├─ Drift Score: 0.024 ✓                           |
│ ├─ Loop Score: 0.333 ⚠️                           │
│ ├─ Progress: 0.333                                │
│ └─ Effectiveness: 0.700                           │
│                                                   │
│ ⚠️  Tool loops detected                           │
╰───────────────────────────────────────────────────╯
```

👉 [**Learn more about health metrics**](./docs/health-metrics.md)

## 📖 Documentation

- **[Getting Started Guide](./docs/getting-started.md)** - Installation and basic usage
- **[Health Metrics Deep Dive](./docs/health-metrics.md)** - Understanding context health
- **[API Reference](./docs/api-reference.md)** - Complete API documentation
- **[Configuration Guide](./docs/configuration.md)** - Customize SDK behavior
- **[CLI Reference](./docs/cli-reference.md)** - Command-line tools
- **[Examples](./examples/)** - Real-world use cases

## 🎯 Use Cases

- **Debug agent loops** - Detect when your agent gets stuck
- **Optimize context** - Identify redundant information
- **Track costs** - Monitor token usage and expenses
- **Improve quality** - Measure goal alignment over time
- **Analyze traces** - Understand agent behavior patterns

## 🛠️ Architecture

Mudipu is designed to be:

1. **Local-first**: All data stays on your machine
2. **Lightweight**: Minimal performance overhead
3. **Framework-agnostic**: Works with any LLM library
4. **Extensible**: Add custom metrics and exporters

```
Your Agent Code
    ↓
[Mudipu Decorators]
    ↓
[Trace Capture]
    ↓
┌──────┴──────┬──────────┐
↓             ↓          ↓
Local JSON   HTML    Analysis CLI
```

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## 📝 License

MIT License - see [LICENSE](./LICENSE) for details.

## 🔗 Links

- **Documentation**: [./docs/](./docs/)
- **PyPI**: https://pypi.org/project/mudipu/
- **GitHub**: https://github.com/santnayak/mudipu-python
- **Issues**: https://github.com/santnayak/mudipu-python/issues

## ⭐ Acknowledgments

Built with:
- [sentence-transformers](https://github.com/UKPLab/sentence-transformers) for semantic analysis
- [Rich](https://github.com/Textualize/rich) for beautiful CLI output
- [Click](https://click.palletsprojects.com/) for command-line interface

---

