# How Crystil Works

## Overview

Crystil sits between your application and the LLM providers you already use.

It does not replace your existing clients — it wraps them.

> Your App → Crystil → LLM Provider

Crystil acts as:

- Observer (tracking usage)
- Analyzer (calculating cost)
- Gatekeeper (optional via Sentinel)

### High-Level Flow

When you integrate Crystil:

1. You register your LLM client with Crystil
2. Crystil wraps the client
3. All requests pass through Crystil automatically
4. Crystil captures and processes metadata
5. Data is sent to Crystil for analysis

```mermaid
sequenceDiagram
    participant SDK as Client<br/>(w/Crystil SDK)
    participant LLM
    box rgba(80, 0, 255, 0.05) Crystil Services
      participant Col as Collector
      participant API
      participant AI
      participant DB as Database
    end

    SDK->>AI: Check validity<br/>(if Sentinel is enabled)
    SDK->>LLM: Request
    LLM-->>SDK: Response
    SDK->>Col: Collect request<br/>(input + output)
    Col->>API: Store requests
    API<<->>AI: Analyze requests
    API->>DB: Store analyzed requests<br/>with Tasks and Workflows
```

This allows Crystil to observe, measure, and enrich every LLM request without requiring changes to your application
logic.

---

## Step-by-Step

### 1 - Client Registration

```python
from openai import OpenAI
from crystil import Crystil

client = OpenAI(...)
crystil = Crystil(api_key="YOUR_API_KEY").openai.register(client)
```

At this point, Crystil becomes part of the request lifecycle.

### 2 - Request Interception

Every time you make an LLM call:

```python
client.chat.completions.create(...)
```

Crystil intercepts:

- Model used
- Prompt data
- Token usage
- Request timing

### 3 - Optional Guardrails (Sentinel)

If enabled:

```python
crystil.sentinel.raise_if_irrelevant()
```

Crystil evaluates the request before it reaches the model.

If the prompt is irrelevant:

- The request is blocked
- An exception is raised

If Crystil fails:

- The request proceeds (fail-open behavior)

### 4 - Cost Calculation

Crystil calculates:

- Input tokens
- Cached tokens
- Output tokens
- Model-specific pricing
- Total cost per request

### 5 - Transaction Grouping

If a transaction is active:

```python
crystil.new_transaction()
```

All requests are grouped within the transaction.

### 6 - Attribution Assignment

If attribution is set:

```python
crystil.attribution(parent_id="customer_123")
```

All requests are tagged with ownership metadata.

### 7 - Data Processing

Crystil aggregates:

- Request-level data
- Transaction-level data
- Attribution-level data

This forms the foundation for cost visibility.

---

## What Crystil Does NOT Do

Crystil does NOT:

- Replace your LLM provider
- Modify your prompts or responses
- Require changes to your business logic

It is designed to be:

- Lightweight
- Non-invasive
- Drop-in

## Performance and Reliability

Crystil is designed to be:

- Low latency
- Minimal overhead
- Safe in production environments

Crystil follows a **fail-open strategy**:

- If Crystil is unavailable → requests proceed
- If Sentinel fails → requests proceed
- If API issues occur → no disruption to your app

---

## Real-World Example

User submits a request:

> "Summarize this document"

Flow:

1. App calls LLM via client with Crystil registration
2. Crystil SDK intercepts request
3. Sentinel evaluates prompt (optional)
4. Request is sent as normal to LLM
5. Response from LLM is returned as normal
6. Asynchronously, Crystil records cost and metadata, groups activities into Tasks and Workflows, attributed to Customers

---

## Best Practices

### Know Thyself

Do not fall into the trap of _Crystil is just a wrapper_, like with other LLM gateways or
observability tools. Simply tracking token counts is not nothing, but it is far from actually helpful.
You should know each and every place you are using AI in your products and organization, and
you should understand the context of each request. Who is my customer? How are multiple requests linked together?

A little bit of knowledge will make all the difference when you try to justify and optimize your
AI costs.

### Register once per client

Avoid re-wrapping clients unnecessarily. Nothing will explode if you do, but there is no reason
to do so.

### Set transaction boundaries clearly

Consider when a customer interaction logically begins and ends. Create a new transaction when appropriate. Your
dashboards will thank you.

### Apply attribution early

Ensure costs are tracked accurately by customer. If one customer is using half of your budget,
you will want to know that.