Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

3.5 KB
Raw Blame
"""Trace events and envelopes for the tests of a run's usage statistics, built the way a run writes them."""

from datetime import UTC, datetime
from typing import Any

from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.graph.graphspec import NodeKind
from pipelex.system.job_metadata import JobCategory, JobMetadata, RunMetadata, UnitJobId
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.usage_stats.usage_stats_contract import UsageStatsArch, UsageStatsIntegration, UsageStatsOs, UsageStatsSurface
from pipelex.system.usage_stats.usage_stats_events import CommonProperties, UsageStatsEvent, make_envelope
from pipelex.tracing.trace_events import PipeStartEvent, UsageReportEvent

USAGE_STATS_RUN_ID = "run-usage-stats"
USAGE_STATS_INSTALLATION_ID = "0f8fad5b-d9cb-469f-a165-70867728950e"


def llm_usage_event(
    *,
    model_name: str,
    backend_name: str,
    input_tokens: int,
    output_tokens: int,
    cached_tokens: int = 0,
    is_rated: bool = True,
    sequence: int = 0,
    model_id: str | None = None,
) -> UsageReportEvent:
    """One inference call's usage, as the backend that served it reports it; an unrated call carries no rate table, so no cost."""
    tokens_usage = LLMTokensUsage(
        job_metadata=JobMetadata(
            run_metadata=RunMetadata(storage_scope="test/scope", read_scope=None, user_id="user_test", pipeline_run_id=USAGE_STATS_RUN_ID),
            pipe_code="secret_pipe_code",
            unit_job_id=UnitJobId.LLM_GEN_TEXT,
            job_category=JobCategory.LLM_JOB,
        ),
        inference_model_name=model_name,
        inference_model_id=model_id or f"{model_name}-provider-id",
        backend_name=backend_name,
        unit_costs={CostCategory.INPUT: 0.003, CostCategory.OUTPUT: 0.015} if is_rated else {},
        nb_tokens_by_category={
            TokenCategory.INPUT: input_tokens,
            TokenCategory.OUTPUT: output_tokens,
            TokenCategory.INPUT_CACHED: cached_tokens,
        },
    )
    return UsageReportEvent(
        attempt=1,
        lineage=[],
        path=None,
        pipeline_run_id=USAGE_STATS_RUN_ID,
        workflow_id="direct",
        timestamp=datetime.now(UTC),
        sequence=sequence,
        mode=PipeRunMode.LIVE,
        node_id=f"{USAGE_STATS_RUN_ID}:node_{sequence}",
        tokens_usage=tokens_usage,
    )


def pipe_start_event(*, pipe_type: str, sequence: int) -> PipeStartEvent:
    return PipeStartEvent(
        attempt=1,
        lineage=[],
        path=None,
        pipe_ref=None,
        pipeline_run_id=USAGE_STATS_RUN_ID,
        workflow_id="direct",
        timestamp=datetime.now(UTC),
        sequence=sequence,
        mode=PipeRunMode.LIVE,
        node_id=f"{USAGE_STATS_RUN_ID}:node_{sequence}",
        pipe_code=f"secret_pipe_{sequence}",
        pipe_type=pipe_type,
        node_kind=NodeKind.OPERATOR,
    )


def envelope_of(*, event: UsageStatsEvent) -> dict[str, Any]:
    """The event as a Python program running pipelex would post it."""
    common = CommonProperties(
        tool_version="0.83.0",
        surface=UsageStatsSurface.PYTHON,
        integration=UsageStatsIntegration.PYTHON,
        id_new=False,
        os=UsageStatsOs.LINUX,
        arch=UsageStatsArch.X86_64,
        language_runtime="python-3.13",
        ci=False,
        container=False,
        internal=False,
        notice_version=1,
    )
    return make_envelope(event=event, distinct_id=USAGE_STATS_INSTALLATION_ID, common=common)