elltri 0.1.0__tar.gz

elltri-0.1.0/PKG-INFO

@@ -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/cost_platform/__init__.py

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

elltri-0.1.0/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()))

elltri-0.1.0/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(),
+    )

elltri-0.1.0/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)

elltri-0.1.0/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"),
+        )