def observe(
    client: ProviderClient,
    *,
    agent_id: str | None = None,
    session_id: str | None = None,
    baseline_window: int = 100,
    role: str | None = None,
    exporters: list[GovernanceExporter] | None = None
) -> ObserveProxy

from tealtiger import observe
from openai import OpenAI

# Minimal — zero config
client = observe(OpenAI())

# With configuration
client = observe(
    OpenAI(),
    agent_id="research-agent-01",
    session_id="session-abc-123",
    baseline_window=50
)

# Use exactly like the original client
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

from tealtiger import observe
from openai import AsyncOpenAI

# Async client
client = observe(AsyncOpenAI(), agent_id="async-agent")

# Use with await
response = await client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

from tealtiger import observe
import anthropic

# Async Anthropic
client = observe(anthropic.AsyncAnthropic(), agent_id="anthropic-async")

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

def get_cost(self) -> CostSummary

@dataclass
class CostSummary:
    session: float       # Total cost for this session (USD)
    agent: float         # Total cost for this agent across all sessions (USD)
    last_request: float  # Cost of the most recent request (USD)
    request_count: int   # Number of requests processed

client = observe(OpenAI())

client.chat.completions.create(model="gpt-4o", messages=[...])
client.chat.completions.create(model="gpt-4o", messages=[...])

cost = client.get_cost()
print(cost.session)        # 0.0067
print(cost.request_count)  # 2

def get_baseline(self) -> Baseline | None

@dataclass
class Baseline:
    request_count: int
    complete: bool
    stats: BaselineStats

@dataclass
class BaselineStats:
    latency: PercentileStats
    input_tokens: PercentileStats
    output_tokens: PercentileStats
    cost: PercentileStats
    tool_call_count: PercentileStats

@dataclass
class PercentileStats:
    p50: float
    p95: float
    p99: float

client = observe(OpenAI(), baseline_window=50)

# After 50 requests...
baseline = client.get_baseline()
print(baseline.stats.latency.p50)   # 480
print(baseline.stats.cost.p95)      # 0.012

def get_agent_id(self) -> str

def get_session_id(self) -> str

def get_burn_rate(self) -> float

def get_cost_by_agent(self) -> dict[str, float]

def freeze(agent_id: str) -> None

from tealtiger import freeze

# Freeze a specific agent
freeze("agent-research-01")

# Freeze ALL agents (emergency stop)
freeze("*")

def unfreeze(agent_id: str) -> None

from tealtiger import freeze, unfreeze

freeze("agent-research-01")
# ... agent is blocked ...
unfreeze("agent-research-01")
# ... agent resumes normal operation ...

class FrozenAgentError(TealTigerError):
    agent_id: str
    frozen_by: Literal["specific", "wildcard"]
    frozen_at: float  # Unix timestamp

from tealtiger import observe, freeze, FrozenAgentError
from openai import OpenAI

client = observe(OpenAI(), agent_id="demo")
freeze("demo")

try:
    client.chat.completions.create(model="gpt-4o", messages=[...])
except FrozenAgentError as e:
    print(e.agent_id)    # "demo"
    print(e.frozen_by)   # "specific"

from tealtiger import observe
from openai import OpenAI

# DeepSeek uses OpenAI-compatible API
deepseek = observe(
    OpenAI(base_url="https://api.deepseek.com/v1", api_key=os.environ["DEEPSEEK_KEY"])
)

# xAI uses OpenAI-compatible API
xai = observe(
    OpenAI(base_url="https://api.x.ai/v1", api_key=os.environ["XAI_KEY"])
)

from tealtiger import observe, freeze, unfreeze, FrozenAgentError
from openai import OpenAI

# 1. Wrap with observe
client = observe(
    OpenAI(),
    agent_id="demo-agent",
    session_id="session-001",
    baseline_window=20
)

# 2. Use normally
for i in range(25):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"Request {i}"}]
    )

# 3. Check accumulated data
cost = client.get_cost()
print(f"Session cost: ${cost.session:.4f}")
print(f"Requests: {cost.request_count}")

baseline = client.get_baseline()
print(f"Baseline complete: {baseline.complete}")
print(f"Latency p50: {baseline.stats.latency.p50}ms")

# 4. Emergency stop
freeze("demo-agent")

try:
    client.chat.completions.create(model="gpt-4o-mini", messages=[...])
except FrozenAgentError:
    print("Agent is frozen!")

# 5. Resume
unfreeze("demo-agent")
client.chat.completions.create(model="gpt-4o-mini", messages=[...])  # Works again

from tealtiger import observe
from openai import OpenAI

with observe(OpenAI(), agent_id="scoped-agent") as client:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(client.get_cost())
# Session finalizes automatically on exit