elltri 0.1.0__py3-none-any.whl

cost_platform/__init__.py

@@ -0,0 +1,3 @@
+from cost_platform.wrapper import AgentTelemetry
+
+__all__ = ["AgentTelemetry"]

cost_platform/db/engine.py

@@ -0,0 +1,40 @@
+import json
+import os
+
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+_DEFAULT_URL = "postgresql://cost_platform:changeme@localhost:5433/cost_platform"
+
+
+def _database_url() -> str:
+    if url := os.environ.get("DATABASE_URL"):
+        return url
+    # ECS injects the Secrets Manager value as DB_SECRET_JSON containing
+    # {username, password, host, port, dbname}.
+    if secret := os.environ.get("DB_SECRET_JSON"):
+        s = json.loads(secret)
+        return (
+            f"postgresql://{s['username']}:{s['password']}"
+            f"@{s['host']}:{s.get('port', 5432)}/{s['dbname']}"
+        )
+    return _DEFAULT_URL
+
+
+def _async_url(url: str) -> str:
+    # asyncpg requires the postgresql+asyncpg:// scheme
+    if url.startswith("postgresql://"):
+        return url.replace("postgresql://", "postgresql+asyncpg://", 1)
+    if url.startswith("postgres://"):
+        return url.replace("postgres://", "postgresql+asyncpg://", 1)
+    return url
+
+
+def get_sync_engine() -> Engine:
+    """Return a synchronous engine (psycopg2). Used by Alembic and batch jobs."""
+    return create_engine(_database_url())
+
+
+def get_async_engine() -> AsyncEngine:
+    """Return an async engine (asyncpg). Used by FastAPI services."""
+    return create_async_engine(_async_url(_database_url()))

cost_platform/db/models.py

@@ -0,0 +1,186 @@
+import enum
+import uuid
+from datetime import UTC, date, datetime
+from decimal import Decimal
+
+from sqlalchemy import (
+    Date,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    Numeric,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy import (
+    Enum as SAEnum,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class OrgStatus(enum.StrEnum):
+    active = "active"
+    suspended = "suspended"
+    churned = "churned"
+
+
+class ApiKeyRole(enum.StrEnum):
+    admin = "admin"
+    ingest = "ingest"
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Organisation(Base):
+    __tablename__ = "organisations"
+
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    org_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    org_slug: Mapped[str] = mapped_column(String(100), nullable=False, unique=True)
+    status: Mapped[OrgStatus] = mapped_column(
+        SAEnum(OrgStatus, name="org_status"),
+        nullable=False,
+        default=OrgStatus.active,
+    )
+    plan_type: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    provisioned_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        server_default=func.now(),
+    )
+    anthropic_workspace_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    anthropic_admin_api_key_secret_arn: Mapped[str | None] = mapped_column(
+        String(2048), nullable=True
+    )
+
+
+class ApiKey(Base):
+    __tablename__ = "api_keys"
+
+    key_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("organisations.org_id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    key_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    role: Mapped[ApiKeyRole] = mapped_column(
+        SAEnum(ApiKeyRole, name="api_key_role"), nullable=False
+    )
+    label: Mapped[str] = mapped_column(String(255), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        server_default=func.now(),
+    )
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    __table_args__ = (Index("ix_api_keys_key_hash", "key_hash", unique=True),)
+
+
+class OrgRateOverride(Base):
+    __tablename__ = "org_rate_overrides"
+
+    override_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("organisations.org_id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    provider: Mapped[str] = mapped_column(String(50), nullable=False)
+    model_id: Mapped[str] = mapped_column(String(100), nullable=False)
+    effective_from: Mapped[date] = mapped_column(Date(), nullable=False)
+    discount_pct: Mapped[Decimal] = mapped_column(Numeric(5, 4), nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "org_id", "provider", "model_id", "effective_from",
+            name="uq_org_rate_overrides_key",
+        ),
+    )
+
+
+class ReviewerRate(Base):
+    __tablename__ = "reviewer_rates"
+
+    rate_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("organisations.org_id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    owner_team: Mapped[str] = mapped_column(String(255), nullable=False)
+    hourly_rate: Mapped[Decimal] = mapped_column(Numeric(10, 4), nullable=False)
+    currency: Mapped[str] = mapped_column(String(3), nullable=False, default="USD")
+    effective_from: Mapped[date] = mapped_column(Date(), nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "org_id", "owner_team", "effective_from",
+            name="uq_reviewer_rates_key",
+        ),
+    )
+
+
+class AgentStatus(enum.StrEnum):
+    active = "active"
+    deprecated = "deprecated"
+
+
+class AgentRegistry(Base):
+    __tablename__ = "agent_registry"
+
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("organisations.org_id", ondelete="RESTRICT"),
+        primary_key=True,
+    )
+    agent_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    agent_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(String, nullable=True)
+    owner_team: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    department: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    cost_centre: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    product: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    category: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    status: Mapped[AgentStatus] = mapped_column(
+        SAEnum(AgentStatus, name="agent_status"),
+        nullable=False,
+        default=AgentStatus.active,
+    )
+    onboarded_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        server_default=func.now(),
+    )
+
+
+class TransformationCheckpoint(Base):
+    __tablename__ = "transformation_checkpoints"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    job_name: Mapped[str] = mapped_column(String, nullable=False, unique=True)
+    last_processed_prefix: Mapped[str | None] = mapped_column(String, nullable=True)
+    last_run_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )

cost_platform/emitter.py

@@ -0,0 +1,206 @@
+"""
+OTLPEmitter — serialises TelemetryEvent and OutcomeEvent as OTel spans and exports
+them to the collector via OTLP HTTP.
+
+Collector endpoint: OTEL_EXPORTER_OTLP_ENDPOINT env var (default http://localhost:4318).
+Auth: COST_PLATFORM_API_KEY is sent as x-api-key in the OTLP export headers.
+      This is how the collector's key-validation sidecar resolves org_id.
+
+If COST_PLATFORM_API_KEY is not set at init time, the emitter operates in no-op mode:
+emit_event and emit_outcome do nothing.
+
+Both emit methods are async and must never raise. Catch all exceptions, log to stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+if TYPE_CHECKING:
+    from cost_platform.models import OutcomeEvent, TelemetryEvent
+
+
+class OTLPEmitter:
+    def __init__(self) -> None:
+        api_key = os.environ.get("COST_PLATFORM_API_KEY", "")
+        if not api_key:
+            print(
+                "cost_platform: COST_PLATFORM_API_KEY not set — running in no-op mode",
+                file=sys.stderr,
+            )
+            self._tracer: trace.Tracer | None = None
+            return
+
+        base = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318").rstrip("/")
+        exporter = OTLPSpanExporter(
+            endpoint=f"{base}/v1/traces",
+            headers={"x-api-key": api_key},
+        )
+        resource = Resource.create({"service.name": "cost-platform-wrapper"})
+        provider = TracerProvider(resource=resource)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        self._tracer = provider.get_tracer("cost_platform", schema_url="")
+
+    # ------------------------------------------------------------------
+    # Public async interface (fire-and-forget; never raises)
+    # ------------------------------------------------------------------
+
+    async def emit_event(self, event: TelemetryEvent) -> None:
+        try:
+            self._emit_telemetry_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: telemetry emit failed: {exc}", file=sys.stderr)
+
+    async def emit_outcome(self, event: OutcomeEvent) -> None:
+        try:
+            self._emit_outcome_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: outcome emit failed: {exc}", file=sys.stderr)
+
+    # ------------------------------------------------------------------
+    # Internal sync helpers (called by async methods and by wrapper sync path)
+    # ------------------------------------------------------------------
+
+    def emit_event_sync(self, event: TelemetryEvent) -> None:
+        """Synchronous entry-point for the wrapper's sync messages.create() path."""
+        try:
+            self._emit_telemetry_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: telemetry emit failed: {exc}", file=sys.stderr)
+
+    def emit_outcome_sync(self, event: OutcomeEvent) -> None:
+        """Synchronous entry-point for the wrapper's sync complete() path."""
+        try:
+            self._emit_outcome_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: outcome emit failed: {exc}", file=sys.stderr)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _emit_telemetry_sync(self, event: TelemetryEvent) -> None:
+        if self._tracer is None:
+            return
+        with self._tracer.start_as_current_span("cost_platform.action") as span:
+            span.set_attribute("event_type", "telemetry")
+            # Group 1 — Trace Identity
+            span.set_attribute("cp.org_id", event.org_id)
+            span.set_attribute("cp.workflow_id", event.workflow_id)
+            span.set_attribute("cp.agent_id", event.agent_id)
+            span.set_attribute("cp.agent_version", event.agent_version)
+            span.set_attribute("cp.environment", event.environment)
+            if event.parent_span_id is not None:
+                span.set_attribute("cp.parent_span_id", event.parent_span_id)
+            if event.step_name is not None:
+                span.set_attribute("cp.step_name", event.step_name)
+            if event.step_index is not None:
+                span.set_attribute("cp.step_index", event.step_index)
+
+            # Group 2 — Call Metadata
+            span.set_attribute("cp.provider", event.provider)
+            span.set_attribute("gen_ai.system", event.provider)
+            span.set_attribute("gen_ai.request.model", event.model_id)
+            span.set_attribute("cp.model_id", event.model_id)
+            span.set_attribute("cp.request_id", event.request_id)
+            span.set_attribute("cp.latency_ms_total", event.latency_ms_total)
+            span.set_attribute("cp.stop_reason", event.stop_reason)
+            span.set_attribute("cp.service_tier", event.service_tier)
+            span.set_attribute("cp.batch_mode", event.batch_mode)
+            span.set_attribute("cp.retry_attempt", event.retry_attempt)
+            if event.latency_ms_ttfb is not None:
+                span.set_attribute("cp.latency_ms_ttfb", event.latency_ms_ttfb)
+            if event.error_code is not None:
+                span.set_attribute("cp.error_code", event.error_code)
+
+            # Group 3 — Token Counts
+            span.set_attribute("gen_ai.usage.input_tokens", event.tokens_input_fresh)
+            span.set_attribute("gen_ai.usage.output_tokens", event.tokens_output_total)
+            span.set_attribute("cp.tokens_input_fresh", event.tokens_input_fresh)
+            span.set_attribute("cp.tokens_input_total", event.tokens_input_total)
+            span.set_attribute("cp.tokens_output_total", event.tokens_output_total)
+            if event.tokens_input_cache_write_5m is not None:
+                span.set_attribute(
+                    "cp.tokens_input_cache_write_5m", event.tokens_input_cache_write_5m
+                )
+            if event.tokens_input_cache_write_1h is not None:
+                span.set_attribute(
+                    "cp.tokens_input_cache_write_1h", event.tokens_input_cache_write_1h
+                )
+            if event.tokens_input_cache_read is not None:
+                span.set_attribute("cp.tokens_input_cache_read", event.tokens_input_cache_read)
+            if event.tokens_output_thinking_est is not None:
+                span.set_attribute(
+                    "cp.tokens_output_thinking_est", event.tokens_output_thinking_est
+                )
+
+            # Group 4 — Cost Fields (None when emitted from wrapper; set by transformation job)
+            if event.cost_usd_input_fresh is not None:
+                span.set_attribute("cp.cost_usd_input_fresh", event.cost_usd_input_fresh)
+            if event.cost_usd_output is not None:
+                span.set_attribute("cp.cost_usd_output", event.cost_usd_output)
+            if event.cost_usd_tools is not None:
+                span.set_attribute("cp.cost_usd_tools", event.cost_usd_tools)
+            if event.cost_usd_total is not None:
+                span.set_attribute("cp.cost_usd_total", event.cost_usd_total)
+            if event.rate_card_version is not None:
+                span.set_attribute("cp.rate_card_version", event.rate_card_version)
+            if event.cost_usd_input_cache_write is not None:
+                span.set_attribute(
+                    "cp.cost_usd_input_cache_write", event.cost_usd_input_cache_write
+                )
+            if event.cost_usd_input_cache_read is not None:
+                span.set_attribute(
+                    "cp.cost_usd_input_cache_read", event.cost_usd_input_cache_read
+                )
+
+            # Group 5 — SDK Metadata
+            if event.sdk_language is not None:
+                span.set_attribute("cp.sdk_language", event.sdk_language)
+            if event.sdk_version is not None:
+                span.set_attribute("cp.sdk_version", event.sdk_version)
+
+            # Group 6 — Tool Usage
+            span.set_attribute("cp.tool_calls_total", event.tool_calls_total)
+            span.set_attribute("cp.tool_calls_web_search", event.tool_calls_web_search)
+            span.set_attribute("cp.tool_calls_code_exec", event.tool_calls_code_exec)
+            span.set_attribute("cp.tool_calls_detail", json.dumps(event.tool_calls_detail))
+
+            span.set_attribute("cp.event_timestamp", event.event_timestamp.isoformat())
+
+    def _emit_outcome_sync(self, event: OutcomeEvent) -> None:
+        if self._tracer is None:
+            return
+        with self._tracer.start_as_current_span("cost_platform.outcome") as span:
+            span.set_attribute("event_type", "outcome")
+            span.set_attribute("cp.org_id", event.org_id)
+            span.set_attribute("cp.workflow_id", event.workflow_id)
+            span.set_attribute("cp.agent_id", event.agent_id)
+            span.set_attribute("cp.outcome_status", event.outcome_status)
+            span.set_attribute("cp.started_at", event.started_at.isoformat())
+            span.set_attribute("cp.completed_at", event.completed_at.isoformat())
+            span.set_attribute("cp.duration_ms", event.duration_ms)
+            span.set_attribute("cp.human_review_required", event.human_review_required)
+            if event.error_code is not None:
+                span.set_attribute("cp.error_code", event.error_code)
+            if event.human_review_duration_mins is not None:
+                span.set_attribute(
+                    "cp.human_review_duration_mins", event.human_review_duration_mins
+                )
+            if event.session_id is not None:
+                span.set_attribute("cp.session_id", event.session_id)
+            if event.external_reference_id is not None:
+                span.set_attribute("cp.external_reference_id", event.external_reference_id)
+            if event.sdk_language is not None:
+                span.set_attribute("cp.sdk_language", event.sdk_language)
+            if event.sdk_version is not None:
+                span.set_attribute("cp.sdk_version", event.sdk_version)

cost_platform/event_assembler.py

@@ -0,0 +1,68 @@
+"""
+Assemble a TelemetryEvent from extracted token counts, trace context, and call metadata.
+
+Pure field assembly — no rate card, no cost computation. All cost_usd_* fields and
+rate_card_version are set to None; the transformation job is the sole owner of those fields.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from cost_platform.models import TelemetryEvent
+
+
+class EventAssembler:
+    def assemble(
+        self,
+        token_counts: dict[str, Any],
+        trace_fields: dict[str, Any],
+        call_metadata: dict[str, Any],
+    ) -> TelemetryEvent:
+        event_timestamp: datetime = call_metadata.get("event_timestamp") or datetime.now(UTC)
+
+        return TelemetryEvent(
+            trace_id=call_metadata.get("trace_id") or str(uuid.uuid4()),
+            span_id=call_metadata.get("span_id") or str(uuid.uuid4()),
+            workflow_id=trace_fields["workflow_id"],
+            agent_id=trace_fields["agent_id"],
+            agent_version=trace_fields["agent_version"],
+            environment=trace_fields["environment"],
+            provider=call_metadata["provider"],
+            model_id=call_metadata["model_id"],
+            request_id=call_metadata["request_id"],
+            latency_ms_total=int(call_metadata.get("latency_ms_total", 0)),
+            stop_reason=call_metadata.get("stop_reason", "end_turn"),
+            service_tier=call_metadata.get("service_tier", "standard"),
+            batch_mode=bool(call_metadata.get("batch_mode", False)),
+            retry_attempt=int(call_metadata.get("retry_attempt", 0)),
+            tokens_input_fresh=token_counts["tokens_input_fresh"],
+            tokens_input_total=token_counts["tokens_input_total"],
+            tokens_output_total=token_counts["tokens_output_total"],
+            cost_usd_input_fresh=None,
+            cost_usd_output=None,
+            cost_usd_tools=None,
+            cost_usd_total=None,
+            cost_usd_input_cache_write=None,
+            cost_usd_input_cache_read=None,
+            rate_card_version=None,
+            tool_calls_total=int(call_metadata.get("tool_calls_total", 0)),
+            tool_calls_web_search=int(call_metadata.get("tool_calls_web_search", 0)),
+            tool_calls_code_exec=int(call_metadata.get("tool_calls_code_exec", 0)),
+            tool_calls_detail=call_metadata.get("tool_calls_detail", []),
+            event_timestamp=event_timestamp,
+            parent_span_id=call_metadata.get("parent_span_id"),
+            step_name=trace_fields.get("step_name"),
+            step_index=trace_fields.get("step_index"),
+            latency_ms_ttfb=call_metadata.get("latency_ms_ttfb"),
+            error_code=call_metadata.get("error_code"),
+            tokens_input_cache_write_5m=token_counts.get("tokens_input_cache_write_5m"),
+            tokens_input_cache_write_1h=token_counts.get("tokens_input_cache_write_1h"),
+            tokens_input_cache_read=token_counts.get("tokens_input_cache_read"),
+            tokens_output_thinking_est=token_counts.get("tokens_output_thinking_est"),
+            cost_usd_runtime=None,
+            sdk_language=call_metadata.get("sdk_language"),
+            sdk_version=call_metadata.get("sdk_version"),
+        )

cost_platform/extractor.py

@@ -0,0 +1,148 @@
+"""
+Extract token counts and call metadata from an Anthropic Message response.
+
+Critical invariant (Technical Invariant #1):
+  Anthropic's `usage.input_tokens` = FRESH (uncached) tokens only.
+  It is NOT the total input. This is non-standard versus other providers.
+  Total = input_tokens + cache_creation_input_tokens + cache_read_input_tokens.
+  Never use input_tokens alone as total billable input for Anthropic calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_STOP_REASON_MAP: dict[str, str] = {
+    "end_turn": "end_turn",
+    "tool_use": "tool_use",
+    "max_tokens": "max_tokens",
+    "stop_sequence": "end_turn",  # normal completion via stop sequence
+    "error": "error",
+}
+
+_CODE_EXEC_TOOL_NAMES: frozenset[str] = frozenset({"bash", "computer"})
+
+
+def extract_token_counts(response: Any) -> dict[str, Any]:
+    """Return token counts, tool usage, and response metadata from an Anthropic Message."""
+    usage = response.usage
+
+    fresh = usage.input_tokens
+    cache_read = getattr(usage, "cache_read_input_tokens", None) or 0
+
+    cache_creation = getattr(usage, "cache_creation_input_tokens", None)
+    cache_write_5m, cache_write_1h = _split_cache_creation(cache_creation)
+
+    tokens_input_total = fresh + cache_write_5m + cache_write_1h + cache_read
+
+    thinking_est = _estimate_thinking_tokens(response)
+
+    tool_calls_total, tool_calls_web_search, tool_calls_code_exec, tool_calls_detail = (
+        _extract_tool_usage(response)
+    )
+
+    raw_stop = getattr(response, "stop_reason", None) or "end_turn"
+    stop_reason = _STOP_REASON_MAP.get(str(raw_stop), "end_turn")
+
+    return {
+        "tokens_input_fresh": fresh,
+        "tokens_input_cache_write_5m": cache_write_5m if cache_write_5m else None,
+        "tokens_input_cache_write_1h": cache_write_1h if cache_write_1h else None,
+        "tokens_input_cache_read": cache_read if cache_read else None,
+        "tokens_input_total": tokens_input_total,
+        "tokens_output_total": usage.output_tokens,
+        "tokens_output_thinking_est": thinking_est,
+        "stop_reason": stop_reason,
+        "model_id": response.model,
+        "request_id": response.id,
+        "tool_calls_total": tool_calls_total,
+        "tool_calls_web_search": tool_calls_web_search,
+        "tool_calls_code_exec": tool_calls_code_exec,
+        "tool_calls_detail": tool_calls_detail,
+    }
+
+
+def _split_cache_creation(cache_creation: Any) -> tuple[int, int]:
+    """Return (ephemeral_5m_tokens, ephemeral_1h_tokens) from cache_creation field.
+
+    Handles two API formats:
+    - Structured object with ephemeral_5m_input_tokens / ephemeral_1h_input_tokens attributes
+    - Legacy plain int (treated entirely as 5m write)
+    """
+    if cache_creation is None:
+        return 0, 0
+    if isinstance(cache_creation, int):
+        return cache_creation, 0
+    # Structured CacheCreation object
+    five_m = getattr(cache_creation, "ephemeral_5m_input_tokens", 0) or 0
+    one_h = getattr(cache_creation, "ephemeral_1h_input_tokens", 0) or 0
+    return int(five_m), int(one_h)
+
+
+def _estimate_thinking_tokens(response: Any) -> int | None:
+    """Estimate output thinking tokens from thinking content blocks (char_count // 4)."""
+    content = getattr(response, "content", None) or []
+    total = 0
+    found = False
+    for block in content:
+        if getattr(block, "type", None) == "thinking":
+            text = getattr(block, "thinking", "") or ""
+            total += len(text) // 4
+            found = True
+    return total if found else None
+
+
+def extract_token_counts_openai(response: Any) -> dict[str, Any]:
+    """Return token counts and call metadata from an OpenAI ChatCompletion response."""
+    usage = response.usage
+    prompt_tokens_details = getattr(usage, "prompt_tokens_details", None)
+    cache_read = (
+        getattr(prompt_tokens_details, "cached_tokens", None) or 0
+        if prompt_tokens_details is not None
+        else 0
+    )
+    fresh = usage.prompt_tokens - cache_read
+
+    choice = response.choices[0]
+    raw_stop = getattr(choice, "finish_reason", None) or "end_turn"
+    tool_calls = getattr(choice.message, "tool_calls", None) or []
+
+    return {
+        "tokens_input_fresh": fresh,
+        "tokens_input_cache_write_5m": None,
+        "tokens_input_cache_write_1h": None,
+        "tokens_input_cache_read": cache_read if cache_read else None,
+        "tokens_input_total": usage.prompt_tokens,
+        "tokens_output_total": usage.completion_tokens,
+        "tokens_output_thinking_est": None,
+        "stop_reason": raw_stop,
+        "model_id": response.model,
+        "request_id": response.id,
+        "tool_calls_total": len(tool_calls),
+        "tool_calls_web_search": 0,
+        "tool_calls_code_exec": 0,
+        "tool_calls_detail": [],
+    }
+
+
+def _extract_tool_usage(
+    response: Any,
+) -> tuple[int, int, int, list[dict[str, Any]]]:
+    """Return (total, web_search_count, code_exec_count, detail_list)."""
+    content = getattr(response, "content", None) or []
+    tool_blocks = [b for b in content if getattr(b, "type", None) == "tool_use"]
+
+    web_search = 0
+    code_exec = 0
+    name_counts: dict[str, int] = {}
+
+    for block in tool_blocks:
+        name = getattr(block, "name", "") or ""
+        name_counts[name] = name_counts.get(name, 0) + 1
+        if name == "web_search":
+            web_search += 1
+        elif name in _CODE_EXEC_TOOL_NAMES:
+            code_exec += 1
+
+    detail = [{"name": n, "count": c} for n, c in name_counts.items()]
+    return len(tool_blocks), web_search, code_exec, detail

cost_platform/models.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True)
+class TelemetryEvent:
+    # Group 1 — Trace Identity
+    trace_id: str
+    span_id: str
+    workflow_id: str
+    agent_id: str
+    agent_version: str
+    environment: str  # production | staging | development
+
+    # Group 2 — Call Metadata
+    provider: str  # anthropic | openai | google
+    model_id: str
+    request_id: str
+    latency_ms_total: int
+    stop_reason: str  # end_turn | tool_use | max_tokens | error
+    service_tier: str  # standard | priority
+    batch_mode: bool
+    retry_attempt: int
+
+    # Group 3 — Token Counts
+    tokens_input_fresh: int
+    tokens_input_total: int
+    tokens_output_total: int
+
+    # Group 6 — Tool Usage
+    tool_calls_total: int
+    tool_calls_web_search: int
+    tool_calls_code_exec: int
+    tool_calls_detail: list[dict[str, Any]]
+
+    # Timestamp — required for rate card resolution and event ordering
+    event_timestamp: datetime
+
+    # Optional fields (defaults last, per dataclass ordering rule)
+    # Group 1 — Trace Identity (optional)
+    org_id: str = ""  # resolved by OTel Collector from the ingest API key
+    parent_span_id: str | None = None
+    step_name: str | None = None
+    step_index: int | None = None
+
+    # Group 2 — Call Metadata (optional)
+    latency_ms_ttfb: int | None = None
+    error_code: str | None = None
+
+    # Group 3 — Token Counts (optional)
+    tokens_input_cache_write_5m: int | None = None
+    tokens_input_cache_write_1h: int | None = None
+    tokens_input_cache_read: int | None = None
+    tokens_output_thinking_est: int | None = None
+
+    # Group 4 — Cost Fields (set by transformation job; None from wrapper)
+    cost_usd_input_fresh: float | None = None
+    cost_usd_output: float | None = None
+    cost_usd_tools: float | None = None
+    cost_usd_total: float | None = None
+    cost_usd_input_cache_write: float | None = None
+    cost_usd_input_cache_read: float | None = None
+    cost_usd_runtime: float | None = None  # added at workflow level by transformation job
+    rate_card_version: str | None = None  # stamped by transformation job
+
+    # Group 5 — SDK Metadata
+    sdk_language: str | None = None
+    sdk_version: str | None = None
+
+
+@dataclass(frozen=True)
+class OutcomeEvent:
+    workflow_id: str
+    agent_id: str
+    outcome_status: str  # success | failure | partial
+    started_at: datetime
+    completed_at: datetime
+    duration_ms: int
+    human_review_required: bool
+
+    org_id: str = ""  # resolved by OTel Collector from the ingest API key
+    error_code: str | None = None
+    human_review_duration_mins: int | None = None
+    session_id: str | None = None
+    external_reference_id: str | None = None
+    sdk_language: str | None = None
+    sdk_version: str | None = None

cost_platform/rate_card.py

@@ -0,0 +1,127 @@
+"""
+Rate card loader for the AI Agent Cost Intelligence Platform.
+
+Resolves the correct LLM pricing entry for a given provider, model, and event timestamp,
+then applies any org-level discount to token rates.
+
+Batch discount note
+-------------------
+The 50% batch discount is NOT part of the rate card and is NOT applied here.
+It is applied by the transformation job after rates are resolved, so that the
+rate card always returns list (non-batch) prices.
+
+Tool-call flat fees
+-------------------
+`web_search_per_call`, `agent_runtime_per_hour`, and `code_exec_per_hour` are flat
+fees, not per-token rates. They are never discounted by `discount_pct` and are never
+subject to the batch multiplier. The caller must handle them separately.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class ResolvedRates:
+    provider: str
+    model_id: str
+    input_per_mtok: float
+    output_per_mtok: float
+    cache_write_5m_multiplier: float = 0.0
+    cache_write_1h_multiplier: float = 0.0
+    cache_read_multiplier: float = 0.0
+    web_search_per_call: float = 0.0
+    agent_runtime_per_hour: float = 0.0
+    code_exec_per_hour: float = 0.0
+    discount_pct: float = 0.0
+    rate_card_version: str = field(default="")
+
+
+class RateCardLoader:
+    def __init__(self, path: Path | str) -> None:
+        path = Path(path)
+        if path.is_dir():
+            files = sorted(path.glob("*_rate_card.yaml"))
+            combined = hashlib.sha256()
+            self._providers: dict[str, dict[str, list[dict[str, Any]]]] = {}
+            for f in files:
+                raw = f.read_bytes()
+                combined.update(raw)
+                data: dict[str, Any] = yaml.safe_load(raw)
+                self._providers[data["provider"]] = data["models"]
+            self._version: str = combined.hexdigest()
+        else:
+            raw = path.read_bytes()
+            self._version = hashlib.sha256(raw).hexdigest()
+            data = yaml.safe_load(raw)
+            self._providers = {
+                provider: provider_data["models"]
+                for provider, provider_data in data["providers"].items()
+            }
+
+    @property
+    def rate_card_version(self) -> str:
+        return self._version
+
+    def resolve(
+        self,
+        provider: str,
+        model_id: str,
+        event_timestamp: datetime | date,
+        discount_pct: float = 0.0,
+    ) -> ResolvedRates:
+        if provider not in self._providers:
+            raise ValueError(f"Unknown provider '{provider}'")
+        models = self._providers[provider]
+        if model_id not in models:
+            # Strip trailing date suffixes and retry:
+            # Anthropic format: claude-haiku-4-5-20251001  → claude-haiku-4-5
+            # OpenAI format:    gpt-4o-2024-11-20          → gpt-4o
+            base_id = re.sub(r"-\d{8}$", "", model_id)
+            base_id = re.sub(r"-\d{4}-\d{2}-\d{2}$", "", base_id)
+            if base_id != model_id and base_id in models:
+                model_id = base_id
+            else:
+                raise ValueError(f"Unknown model '{model_id}' for provider '{provider}'")
+
+        event_date = (
+            event_timestamp.date()
+            if isinstance(event_timestamp, datetime)
+            else event_timestamp
+        )
+
+        entries: list[dict[str, Any]] = models[model_id]
+        valid = [
+            e for e in entries if date.fromisoformat(str(e["effective_from"])) <= event_date
+        ]
+        if not valid:
+            raise ValueError(
+                f"No rate card entry for '{provider}/{model_id}' "
+                f"effective on or before {event_date}"
+            )
+
+        entry = max(valid, key=lambda e: date.fromisoformat(str(e["effective_from"])))
+        multiplier = 1.0 - discount_pct
+
+        return ResolvedRates(
+            provider=provider,
+            model_id=model_id,
+            input_per_mtok=entry["input_per_mtok"] * multiplier,
+            output_per_mtok=entry["output_per_mtok"] * multiplier,
+            cache_write_5m_multiplier=entry.get("cache_write_5m_multiplier", 0.0),
+            cache_write_1h_multiplier=entry.get("cache_write_1h_multiplier", 0.0),
+            cache_read_multiplier=entry.get("cache_read_multiplier", 0.0),
+            web_search_per_call=entry.get("web_search_per_call", 0.0),
+            agent_runtime_per_hour=entry.get("agent_runtime_per_hour", 0.0),
+            code_exec_per_hour=entry.get("code_exec_per_hour", 0.0),
+            discount_pct=discount_pct,
+            rate_card_version=self._version,
+        )

cost_platform/wrapper.py

@@ -0,0 +1,238 @@
+"""
+AgentTelemetry — the public interface imported by agent teams.
+
+Usage (from the handoff spec):
+
+    from cost_platform import AgentTelemetry
+    import anthropic, uuid
+
+    telemetry = AgentTelemetry(
+        agent_id="invoice-extractor",
+        agent_version="2.1.0",
+        workflow_id=str(uuid.uuid4()),
+        environment="production",
+    )
+    client = telemetry.wrap(anthropic.Anthropic())
+    response = client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": "..."}],
+        _step_name="extract_line_items",   # stripped before Anthropic call
+        _step_index=1,                     # stripped before Anthropic call
+    )
+    telemetry.complete(outcome_status="success", human_review_required=False)
+"""
+
+from __future__ import annotations
+
+import importlib.metadata as _importlib_metadata
+import sys
+import time
+from datetime import UTC, datetime
+from typing import Any
+
+from cost_platform.emitter import OTLPEmitter
+from cost_platform.event_assembler import EventAssembler
+from cost_platform.extractor import extract_token_counts, extract_token_counts_openai
+from cost_platform.models import OutcomeEvent
+
+try:
+    _SDK_VERSION = _importlib_metadata.version("elltri")
+except Exception:
+    try:
+        _SDK_VERSION = _importlib_metadata.version("cost-platform")
+    except Exception:
+        _SDK_VERSION = "unknown"
+
+_SDK_LANGUAGE = "python"
+
+
+class AgentTelemetry:
+    def __init__(
+        self,
+        agent_id: str,
+        agent_version: str,
+        workflow_id: str,
+        environment: str,
+    ) -> None:
+        self._agent_id = agent_id
+        self._agent_version = agent_version
+        self._workflow_id = workflow_id
+        self._environment = environment
+        self._started_at = datetime.now(UTC)
+
+        self._assembler = EventAssembler()
+        self._emitter = OTLPEmitter()
+
+    def wrap(self, client: Any) -> Any:
+        """Return a wrapped client with transparent telemetry. Supports Anthropic and OpenAI."""
+        if hasattr(client, "messages"):  # Anthropic
+            return _WrappedClient(client, self)
+        elif hasattr(client, "chat"):  # OpenAI
+            return _WrappedOpenAIClient(client, self)
+        raise ValueError(
+            f"cost_platform: unsupported client type {type(client).__name__}"
+        )
+
+    def complete(
+        self,
+        outcome_status: str,
+        human_review_required: bool = False,
+        human_review_duration_mins: int | None = None,
+        session_id: str | None = None,
+        external_reference_id: str | None = None,
+    ) -> None:
+        """Emit an OutcomeEvent. Call once at the end of each agent workflow run."""
+        completed_at = datetime.now(UTC)
+        duration_ms = int((completed_at - self._started_at).total_seconds() * 1000)
+        event = OutcomeEvent(
+            workflow_id=self._workflow_id,
+            agent_id=self._agent_id,
+            outcome_status=outcome_status,
+            started_at=self._started_at,
+            completed_at=completed_at,
+            duration_ms=duration_ms,
+            human_review_required=human_review_required,
+            human_review_duration_mins=human_review_duration_mins,
+            session_id=session_id,
+            external_reference_id=external_reference_id,
+            sdk_language=_SDK_LANGUAGE,
+            sdk_version=_SDK_VERSION,
+        )
+        self._emitter.emit_outcome_sync(event)
+
+
+class _WrappedClient:
+    def __init__(self, native: Any, telemetry: AgentTelemetry) -> None:
+        self._native = native
+        self.messages = _WrappedMessages(native.messages, telemetry)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._native, name)
+
+
+class _WrappedMessages:
+    def __init__(self, native_messages: Any, telemetry: AgentTelemetry) -> None:
+        self._native = native_messages
+        self._telemetry = telemetry
+
+    def create(self, **kwargs: Any) -> Any:
+        # Strip wrapper-only parameters before forwarding to Anthropic
+        step_name: str | None = kwargs.pop("_step_name", None)
+        step_index: int | None = kwargs.pop("_step_index", None)
+
+        t0 = time.monotonic()
+        response = self._native.create(**kwargs)
+        latency_ms = int((time.monotonic() - t0) * 1000)
+
+        try:
+            extracted = extract_token_counts(response)
+
+            trace_fields: dict[str, Any] = {
+                "workflow_id": self._telemetry._workflow_id,
+                "agent_id": self._telemetry._agent_id,
+                "agent_version": self._telemetry._agent_version,
+                "step_name": step_name,
+                "step_index": step_index,
+                "environment": self._telemetry._environment,
+            }
+
+            call_metadata: dict[str, Any] = {
+                "provider": "anthropic",
+                "model_id": extracted.pop("model_id"),
+                "request_id": extracted.pop("request_id"),
+                "event_timestamp": datetime.now(UTC),
+                "latency_ms_total": latency_ms,
+                "stop_reason": extracted.pop("stop_reason"),
+                "service_tier": "standard",
+                "batch_mode": False,
+                "retry_attempt": 0,
+                "tool_calls_total": extracted.pop("tool_calls_total"),
+                "tool_calls_web_search": extracted.pop("tool_calls_web_search"),
+                "tool_calls_code_exec": extracted.pop("tool_calls_code_exec"),
+                "tool_calls_detail": extracted.pop("tool_calls_detail"),
+                "sdk_language": _SDK_LANGUAGE,
+                "sdk_version": _SDK_VERSION,
+            }
+
+            event = self._telemetry._assembler.assemble(extracted, trace_fields, call_metadata)
+            self._telemetry._emitter.emit_event_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: telemetry failed: {exc}", file=sys.stderr)
+
+        return response
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._native, name)
+
+
+class _WrappedOpenAIClient:
+    def __init__(self, native: Any, telemetry: AgentTelemetry) -> None:
+        self._native = native
+        self.chat = _WrappedOpenAIChat(native.chat, telemetry)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._native, name)
+
+
+class _WrappedOpenAIChat:
+    def __init__(self, native_chat: Any, telemetry: AgentTelemetry) -> None:
+        self._native = native_chat
+        self.completions = _WrappedOpenAICompletions(native_chat.completions, telemetry)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._native, name)
+
+
+class _WrappedOpenAICompletions:
+    def __init__(self, native_completions: Any, telemetry: AgentTelemetry) -> None:
+        self._native = native_completions
+        self._telemetry = telemetry
+
+    def create(self, **kwargs: Any) -> Any:
+        step_name: str | None = kwargs.pop("_step_name", None)
+        step_index: int | None = kwargs.pop("_step_index", None)
+
+        t0 = time.monotonic()
+        response = self._native.create(**kwargs)
+        latency_ms = int((time.monotonic() - t0) * 1000)
+
+        try:
+            extracted = extract_token_counts_openai(response)
+
+            trace_fields: dict[str, Any] = {
+                "workflow_id": self._telemetry._workflow_id,
+                "agent_id": self._telemetry._agent_id,
+                "agent_version": self._telemetry._agent_version,
+                "step_name": step_name,
+                "step_index": step_index,
+                "environment": self._telemetry._environment,
+            }
+
+            call_metadata: dict[str, Any] = {
+                "provider": "openai",
+                "model_id": extracted.pop("model_id"),
+                "request_id": extracted.pop("request_id"),
+                "event_timestamp": datetime.now(UTC),
+                "latency_ms_total": latency_ms,
+                "stop_reason": extracted.pop("stop_reason"),
+                "service_tier": "standard",
+                "batch_mode": False,
+                "retry_attempt": 0,
+                "tool_calls_total": extracted.pop("tool_calls_total"),
+                "tool_calls_web_search": extracted.pop("tool_calls_web_search"),
+                "tool_calls_code_exec": extracted.pop("tool_calls_code_exec"),
+                "tool_calls_detail": extracted.pop("tool_calls_detail"),
+                "sdk_language": _SDK_LANGUAGE,
+                "sdk_version": _SDK_VERSION,
+            }
+
+            event = self._telemetry._assembler.assemble(extracted, trace_fields, call_metadata)
+            self._telemetry._emitter.emit_event_sync(event)
+        except Exception as exc:
+            print(f"cost_platform: telemetry failed: {exc}", file=sys.stderr)
+
+        return response
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._native, name)

elltri-0.1.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: elltri
+Version: 0.1.0
+Summary: AI Total Cost of Ownership — instrumented agent metering and first-party Claude usage
+License: MIT
+Project-URL: Homepage, https://github.com/Elltri/Cost-Explorer
+Project-URL: Repository, https://github.com/Elltri/Cost-Explorer
+Keywords: llm,cost,observability,opentelemetry,anthropic,openai
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: alembic>=1.13
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: cachetools>=5.3
+Requires-Dist: opentelemetry-sdk>=1.24
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24
+Requires-Dist: opentelemetry-proto>=1.24
+Requires-Dist: httpx>=0.27
+Requires-Dist: anthropic>=0.26
+Requires-Dist: pyiceberg[glue,pyiceberg-core,s3fs]>=0.7
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: psycopg2-binary>=2.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: httpx2>=2.0; extra == "dev"
+Requires-Dist: boto3>=1.34; extra == "dev"
+Requires-Dist: botocore>=1.34; extra == "dev"

elltri-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+cost_platform/__init__.py,sha256=0b4cW-8k66zEQuLWg8-iaGeaeIMx6jLPrIFfbCwQSEA,79
+cost_platform/emitter.py,sha256=NFYcIDXhV6KdHrh6uMFUaN54U1CY2C2P1EtiHWxGVIs,10366
+cost_platform/event_assembler.py,sha256=pABOxbzBy07QTrOwsdHbWHdS6jkW1NLjGIKpEGX4EWg,3248
+cost_platform/extractor.py,sha256=Q4TvBQ99OyzvaymH6iHRyqMg3OYQpK9aK2ELjKW10Ys,5555
+cost_platform/models.py,sha256=KSMHQINkLP7RsvCkQApPHHr1BQgIx7ieSWjg13mcwSc,2864
+cost_platform/rate_card.py,sha256=hBVTCS--LEOOwTktFO0Vr9J6j6XysplzSY4YySe0eao,4693
+cost_platform/wrapper.py,sha256=uAjmhkwz6ePaRoMQapSWIWnE9BhydVMV9CBKLWWJOXk,8867
+cost_platform/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cost_platform/db/engine.py,sha256=b3AUjyAhLlfypPQzabuXG0ssvs4zlhb4mGESG6J8w3w,1348
+cost_platform/db/models.py,sha256=ulefy965lLFcqkZ15L2wLjW2kcu957evVm5REIZaP7Y,6119
+elltri-0.1.0.dist-info/METADATA,sha256=MUvH9cbmOs9bmijLno0MMPEq0yQf6TINQtaLG_UTlFM,1711
+elltri-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+elltri-0.1.0.dist-info/top_level.txt,sha256=5IuorqrMkRIDumJjUr_jI5JSsfJid8B7OwnejgenM_E,14
+elltri-0.1.0.dist-info/RECORD,,

elltri-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

elltri-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cost_platform