glassbox-sdk 0.1.0
See Your AI Costs in Real-Time
Requires Python: >=3.8
Keywords: ai, observability, monitoring, costs, terminal, cli, openai, anthropic, gpt-4, claude

# Glassbox

**See Your AI Costs in Real-Time**

The terminal tool that makes AI development transparent. See every call, track every cost, catch every failure. One command, zero config, local-first.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**Trust Signals:**
- ✅ **Open Source** - [View Source](https://github.com/HudsonBales/glassbox) (MIT License)
- ✅ **Local-First** - Data stays on your machine
- ✅ **No Telemetry** - Zero data collection
- ✅ **Production-Safe** - Never breaks your code
- ✅ **Transparent** - You see everything we do

Run `glassbox trust` to see full trust guarantees.

## 🚀 Quick Start (2 Minutes)

### Install from PyPI

```bash
pip install glassbox-sdk
```

### Or Install from Source

If you want the latest development version:

```bash
git clone https://github.com/HudsonBales/glassbox.git
cd glassbox/sdk/python
pip install -e .
```

### Initialize
```bash
glassbox init
```

### Use
```python
import glassbox
glassbox.init()  # That's it!

# Your existing AI code works as-is
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(...)
# ✅ Automatically tracked!
```

### View Your Costs
```bash
glassbox live    # See costs in real-time
glassbox stats   # View statistics
```

**🎉 Done! You can now see your AI costs in real-time!**

👉 **New user?** See [docs/NEW_USER_GUIDE.md](docs/NEW_USER_GUIDE.md) for complete walkthrough.

---

## Features

- 🚀 **One-line setup**: `glassbox.init(API_KEY)` - Works with ANY AI tech stack
- 🌐 **Universal compatibility**: HTTP interception, decorators, auto-wrapping, manual API
- 💰 **Cost tracking**: Real-time cost monitoring with spike detection
- ⚡ **Latency monitoring**: Track response times
- ✓ **Validity checks**: Automatic output validation
- 📊 **Prompt drift detection**: Alerts for performance degradation
- 📱 **Local-first**: SQLite storage - all data stays on your machine
- 📺 **CLI tool**: `glassbox live` for instant log viewing
- 🎯 **Smart insights**: Cost spikes, failing prompts, performance alerts
- 📊 **Real-time metrics**: See costs, latency, and validity as they happen
- 🎨 **Demo mode**: Auto-generates sample data so you can explore immediately

## Universal AI Stack Support

Glassbox works with **ANY AI tech stack** using multiple strategies:

1. **HTTP Interception** - Automatically tracks ANY HTTP-based AI API
2. **Auto-Wrapping** - Zero-config for OpenAI, Anthropic, LangChain
3. **Decorators** - User-controlled tracking for custom functions
4. **Manual API** - Full control when needed

See [docs/UNIVERSAL_INTEGRATION_GUIDE.md](docs/UNIVERSAL_INTEGRATION_GUIDE.md) for details.

## Project Structure

```
glassbox/
├─ sdk/
│  ├─ python/          # Python SDK & CLI
│  └─ js/              # JavaScript SDK (optional)
```

## 📖 Documentation

- **[docs/NEW_USER_GUIDE.md](docs/NEW_USER_GUIDE.md)** - Complete guide for new users
- **[docs/QUICK_START_USER.md](docs/QUICK_START_USER.md)** - 30-second quick start
- **[docs/INSTALLATION.md](docs/INSTALLATION.md)** - Detailed installation guide
- **[docs/UNIVERSAL_INTEGRATION_GUIDE.md](docs/UNIVERSAL_INTEGRATION_GUIDE.md)** - Integration guide

## 🎯 Usage Examples

### Python SDK - Works with ANY AI Stack!

**One-line setup - Universal compatibility:**

```python
import glassbox

# That's it! Works with ANY AI provider
glassbox.init(API_KEY="your-api-key")

# Method 1: HTTP Interception (works with ANY HTTP API)
import requests
response = requests.post("https://api.any-ai-provider.com/v1/generate", ...)
# ✅ Automatically tracked!

# Method 2: Decorator (works with ANY function)
@glassbox.track(model="my-ai")
def my_ai_call(prompt):
    return custom_api.generate(prompt)
# ✅ Automatically tracked!

# Method 3: Auto-wrapping (OpenAI, Anthropic, LangChain)
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(...)
# ✅ Automatically tracked!
```

**Manual logging (if needed):**

```python
# Option 1: Context manager
with glassbox.get_logger().track_call("gpt-4") as call:
    response = client.chat.completions.create(...)
    call.log(response)

# Option 2: Convenience function
response = client.chat.completions.create(...)
glassbox.log_call("gpt-4", response)
```

### CLI Commands

```bash
# View live logs in real-time
glassbox live

# Show statistics
glassbox stats

# Verify setup
glassbox verify

# Generate test logs
glassbox test

# Check status
glassbox status

# Get help
glassbox troubleshoot
```

👉 **See [docs/NEW_USER_GUIDE.md](docs/NEW_USER_GUIDE.md) for complete CLI guide.**

## JavaScript SDK (Optional)

```javascript
import { init, logCall } from '@glassbox/glassbox-sdk';

// Initialize Glassbox
init('your-api-key', { appId: 'my-app' });

// Use with OpenAI
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Log the call
logCall('gpt-4', response);
```

## Configuration

### Environment Variables

- `GLASSBOX_DB_PATH` - Custom database path (default: `.glassbox.db`)
- `GLASSBOX_API_KEY` - Optional API key for backend sync
- `GLASSBOX_BACKEND_URL` - Optional backend URL for cloud sync

## Supported Models

- **OpenAI**: GPT-4, GPT-4 Turbo, GPT-3.5 Turbo
- **Anthropic**: Claude 3 Opus, Sonnet, Haiku
- **Custom models**: Automatic cost estimation with fallback pricing

## Local-First Architecture

Glassbox uses SQLite for local storage, ensuring:
- **Offline support**: Works without internet connection
- **Fast writes**: No network latency for logging
- **Privacy**: All data stays on your machine
- **Optional sync**: Background sync to your own backend (if configured)

## Requirements

- Python 3.8+
- SQLite3 (included with Python)

## License

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

## Contributing

Contributions welcome! Please open an issue or pull request on [GitHub](https://github.com/HudsonBales/glassbox).

## Support

- **Documentation**: See [docs/NEW_USER_GUIDE.md](docs/NEW_USER_GUIDE.md)
- **Issues**: [GitHub Issues](https://github.com/HudsonBales/glassbox/issues)
- **Trust**: Run `glassbox trust` for privacy and security guarantees