Metadata-Version: 2.4
Name: cogslayer
Version: 0.1.0
Summary: Lightweight Python SDK for LLM cost tracking and attribution. Track every OpenAI, Anthropic, and Gemini call — cost, tokens, latency — by feature, team, and user.
Project-URL: Homepage, https://cogslayer.com
Project-URL: Documentation, https://cogslayer.com/docs
Project-URL: Repository, https://github.com/cogslayer/cogslayer
Project-URL: Issues, https://github.com/cogslayer/cogslayer/issues
Project-URL: Changelog, https://github.com/cogslayer/cogslayer/releases
License-Expression: MIT
Keywords: ai,anthropic,attribution,cost,gemini,llm,observability,openai,tokens,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: anthropic>=0.18; extra == 'all'
Requires-Dist: django; extra == 'all'
Requires-Dist: flask; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: robyn; extra == 'all'
Requires-Dist: starlette; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Provides-Extra: django
Requires-Dist: django; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: starlette; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask; extra == 'flask'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == 'gemini'
Provides-Extra: grok
Requires-Dist: openai>=1.0; extra == 'grok'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: robyn
Requires-Dist: robyn; extra == 'robyn'
Description-Content-Type: text/markdown

# CogsLayer

Know the true cost of every feature you ship.

CogsLayer tracks the direct costs of delivering your software — starting with AI. Attribute spend to features, teams, and models. Cut what's wasted.

**Start free at [cogslayer.com](https://cogslayer.com).**

## Two ways in

### 1. Python SDK (2 lines of code)

```bash
pip install cogslayer
```

```python
import cogslayer
from cogslayer.openai import OpenAI

cogslayer.init(api_key="cl_live_xxx", service="my-api")

client = OpenAI()

@cogslayer.track(feature="chat", team="growth")
def ask(prompt: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content
```

Drop-in replacement clients for OpenAI, Anthropic, and Gemini. Every call is automatically tracked with cost, tokens, latency, and attribution context.

### 2. Provider integration (60 seconds, zero code)

Paste your OpenAI org key or Anthropic admin key. CogsLayer pulls **actual billed costs** — not token-based estimates — and syncs automatically.

Supported: OpenAI, Anthropic, Cursor, Claude Code.

## Track. Understand. Save.

| | What you get |
|---|---|
| **Track** | Every call tracked with cost, tokens, and latency. Attribute spend to features, teams, models, and services with `@cogslayer.track`. Agent sessions grouped automatically. |
| **Understand** | Dashboard with spend by team, feature, model, provider. Actual billed costs from provider APIs. Estimate vs. billed drift detection. Budget alerts and forecasting. |
| **Save** | Waste detection flags duplicates, retry bloat, and oversized models. Optimization rules with one-click apply. Realized savings ledger proves ROI. |

## Wrapped clients

### OpenAI

```python
from cogslayer.openai import OpenAI, AsyncOpenAI

client = OpenAI()           # exact same API as openai.OpenAI
async_client = AsyncOpenAI()  # exact same API as openai.AsyncOpenAI
```

Tracks `chat.completions.create()`, `chat.completions.parse()`, `chat.completions.stream()`, and `responses.create()`.

#### OpenAI-compatible providers

```python
from cogslayer.openai import OpenAI

groq = OpenAI(
    base_url="https://api.groq.com/openai/v1",
    api_key="gsk_...",
    provider="groq",
)
```

Works with Groq, Together, Fireworks, Ollama, or any OpenAI-compatible API.

### Anthropic

```python
from cogslayer.anthropic import Anthropic, AsyncAnthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

Tracks `messages.create()` and `messages.stream()`. Captures cache tokens.

### Google Gemini

```python
from cogslayer.gemini import Client

client = Client(api_key="...")

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Hello",
)
```

Tracks `models.generate_content()` (sync and async). Streaming supported.

## What gets tracked

| Metric | Description |
|---|---|
| `prompt_tokens` | Input tokens |
| `completion_tokens` | Output tokens |
| `reasoning_tokens` | Thinking tokens (o1, o3, o4-mini) |
| `cached_tokens` | Prompt tokens served from cache |
| `cost_usd` | Estimated cost from pricing registry |
| `latency_ms` | Round-trip time |
| `has_tool_calls` | Whether the response included tool calls |
| `api_type` | `chat` / `responses` / `messages` / `generate` |

## Attribution

Every call is tagged with context from `@cogslayer.track()`:

| Field | Description |
|---|---|
| `feature` | Product feature (e.g. `"chat"`, `"code-review"`) |
| `team` | Owning team (e.g. `"engineering"`, `"support"`) |
| `user_id` | End-user identifier |
| `service` | Service name (set in `init()`) |
| `environment` | `"production"` / `"staging"` / etc. |

## Streaming

Fully supported across all providers. CogsLayer injects `stream_options` for OpenAI and captures token counts from the final chunk automatically.

```python
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

## Custom pricing

```python
cogslayer.register_model(
    "my-fine-tuned-gpt4",
    prompt_price_per_1k=0.006,
    completion_price_per_1k=0.012,
)
```

## Running locally

```bash
./dev.sh
```

Requires Docker and Node 20+. Starts Supabase, platform API (`:8000`), dashboard (`:3000`), and website (`:3001`).

## Supported providers

| Provider | SDK wrapper | Integration (billed costs) |
|---|---|---|
| OpenAI | `from cogslayer.openai import OpenAI` | Yes |
| Anthropic | `from cogslayer.anthropic import Anthropic` | Yes |
| Google Gemini | `from cogslayer.gemini import Client` | — |
| Cursor | — | Yes |
| Claude Code | — | Yes |
| Any OpenAI-compatible | `OpenAI(base_url=..., provider="groq")` | — |
