EcoTrace AI SDK

Production-oriented AI Workload Observability & Optimization SDK

EcoTrace is a lightweight, provider-agnostic Python SDK for observing, analyzing, and optimizing AI/LLM workloads.

Core Pipeline

OBSERVE ──> DETECT ──> ANALYZE ──> OPTIMIZE ──> MEASURE

1. Observe: Capture AI requests and responses across multiple LLM providers.
2. Detect: Identify exact duplicate and semantically similar AI requests.
3. Analyze: Measure token consumption, latency distribution, and workload efficiency.
4. Optimize: Recommend strategies such as caching and model right-sizing.
5. Measure: Quantify cost, energy, carbon impact, and calculate composite EcoScore.

Architecture

EcoTrace is built around clean architecture principles and a provider-agnostic data model:

Public API (EcoTrace, @track)
   │
   ▼
Tracking (Tracker, Session, EventEmitter)
   │
   ▼
Capture (RequestCapture, ResponseCapture)
   │
   ▼
Providers (OpenAI, Gemini, Groq, Generic) ──> Storage (MemoryStorage, SQLiteStorage)
   │
   ▼
Analysis / Optimization / Impact (Consume normalized RequestEvent data)

• Provider Agnostic: Normalized RequestEvent abstraction decoupled from specific vendor SDKs.
• Zero API Keys Required for Import: The SDK imports and initializes cleanly without requiring live provider credentials.
• Minimal Dependencies: Core SDK depends strictly on the Python Standard Library.

Installation

pip install -e .

Basic Usage

Manual Tracking

from ecotrace import EcoTrace

eco = EcoTrace(project="my-ai-app")

result = eco.track(
    provider="openai",
    model="gpt-4o-mini",
    prompt="Explain quantum computing in simple terms.",
    response="Quantum computing uses qubits...",
    latency_ms=120.5
)

print(f"Tracked Event ID: {result.event.request_id}")
print(f"Total Tokens: {result.event.total_tokens}")

Decorator Usage

from ecotrace import EcoTrace, track

eco = EcoTrace()

@track(provider="openai", model="gpt-4o-mini")
def ask_ai(prompt: str) -> str:
    return "AI response"

response = ask_ai("What is Python?")

SDK Project Structure

ecotrace/
├── __init__.py
├── client.py
├── config.py
├── exceptions.py
│
├── capture/
│   ├── __init__.py
│   ├── request.py
│   └── response.py
│
├── providers/
│   ├── __init__.py
│   ├── base.py
│   ├── openai.py
│   ├── gemini.py
│   ├── groq.py
│   └── generic.py
│
├── tracking/
│   ├── __init__.py
│   ├── tracker.py
│   ├── session.py
│   └── events.py
│
├── analysis/
│   ├── __init__.py
│   ├── duplicates.py
│   ├── similarity.py
│   ├── tokens.py
│   ├── latency.py
│   └── efficiency.py
│
├── optimization/
│   ├── __init__.py
│   ├── optimizer.py
│   ├── recommendations.py
│   └── strategies.py
│
├── impact/
│   ├── __init__.py
│   ├── cost.py
│   ├── energy.py
│   ├── carbon.py
│   └── ecoscore.py
│
├── storage/
│   ├── __init__.py
│   ├── base.py
│   ├── memory.py
│   ├── sqlite.py
│   └── models.py
│
├── integrations/
│   ├── __init__.py
│   └── decorators.py
│
└── utils/
    ├── __init__.py
    ├── hashing.py
    ├── timestamps.py
    └── validation.py

Current Status & Next Steps

License

MIT License #\x00 \x00E\x00c\x00o\x00T\x00r\x00a\x00c\x00e\x00-\x00A\x00I\x00 \x00 \x00