# mizcausevic-dev/agent-trace-normalizer architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/agent-trace-normalizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/agent-trace-normalizer
- Repository: https://github.com/mizcausevic-dev/agent-trace-normalizer

## Overview

agent-trace-normalizer is a small TypeScript library and CLI that turns raw OpenAI, Anthropic, Bedrock, and Gemini responses into a canonical usage record. The main workflow parses a single response or batch, selects or forces a provider adapter, extracts token and model data—including cache and reasoning details—and returns records for metering or tracing. The CLI adds file input/output and per-record errors. Adapter behavior and CLI flow are evidenced in sampled source; other README-described integrations are represented only where documented.

Main entry points: [`src/types.ts`](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/types.ts) (Usage record), [`src/normalize.ts`](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts) (Adapter selection), [`src/cli.ts`](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/cli.ts) (CLI), [`src/index.ts`](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/index.ts) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[cli.ts]"]
  node_public_api["Public API<br/>[index.ts]"]
end

subgraph group_normalization["Normalization"]
  node_normalize_many["Batch normalization<br/>[normalize.ts]"]
  node_normalize_one["Single normalization<br/>[normalize.ts]"]
  node_canonical_record["Usage record<br/>[types.ts]"]
  node_adapter_dispatch["Adapter selection<br/>[normalize.ts]"]
end

subgraph group_provider_adapters["Provider adapters"]
  node_openai["OpenAI adapter<br/>[adapters.ts]"]
  node_anthropic["Anthropic adapter<br/>[adapters.ts]"]
  node_bedrock["Bedrock adapter<br/>[adapters.ts]"]
  node_gemini["Gemini adapter<br/>[adapters.ts]"]
end

node_cli_user(("CLI user"))
node_library_user(("Library caller"))
node_raw_responses["Raw responses"]
node_usage_consumer(("Cost and tracing"))
node_output_file["Output file"]

node_cli_user -->|"invokes"| node_cli
node_raw_responses -->|"reads"| node_cli
node_cli -->|"normalizes batch"| node_normalize_many
node_cli -->|"writes"| node_output_file
node_cli -.->|"emits records"| node_usage_consumer
node_library_user -->|"calls"| node_public_api
node_public_api -->|"exports batch API"| node_normalize_many
node_public_api -->|"exports single API"| node_normalize_one
node_normalize_many -->|"normalizes each"| node_normalize_one
node_normalize_one -->|"selects adapter"| node_adapter_dispatch
node_adapter_dispatch -->|"detects or extracts"| node_openai
node_adapter_dispatch -->|"detects or extracts"| node_anthropic
node_adapter_dispatch -->|"detects or extracts"| node_bedrock
node_adapter_dispatch -->|"detects or extracts"| node_gemini
node_openai -->|"builds record"| node_canonical_record
node_anthropic -->|"builds record"| node_canonical_record
node_bedrock -->|"builds record"| node_canonical_record
node_gemini -->|"builds record"| node_canonical_record
node_normalize_one -->|"returns"| node_canonical_record
node_canonical_record -->|"returns"| node_library_user
node_canonical_record -.->|"feeds"| node_usage_consumer

click node_cli "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/cli.ts"
click node_public_api "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/index.ts"
click node_normalize_many "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts"
click node_normalize_one "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts"
click node_canonical_record "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/types.ts"
click node_adapter_dispatch "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts"
click node_openai "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts"
click node_anthropic "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts"
click node_bedrock "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts"
click node_gemini "https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_public_api,node_cli_user toneBlue
class node_normalize_many,node_normalize_one,node_canonical_record,node_adapter_dispatch toneAmber
class node_openai,node_anthropic,node_bedrock,node_gemini toneMint
class node_library_user,node_raw_responses,node_usage_consumer,node_output_file toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/cli.ts): `src/cli.ts`
- [Public API](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/index.ts): `src/index.ts`

### Normalization

- [Batch normalization](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts): `src/normalize.ts`
- [Single normalization](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts): `src/normalize.ts`
- [Usage record](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/types.ts): `src/types.ts`
- [Adapter selection](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/normalize.ts): `src/normalize.ts`

### Provider adapters

- [OpenAI adapter](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts): `src/adapters.ts`
- [Anthropic adapter](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts): `src/adapters.ts`
- [Bedrock adapter](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts): `src/adapters.ts`
- [Gemini adapter](https://github.com/mizcausevic-dev/agent-trace-normalizer/blob/main/src/adapters.ts): `src/adapters.ts`

### Other components

- **CLI user**
- **Library caller**
- **Raw responses**
- **Cost and tracing**
- **Output file**

## Connections

- CLI user → CLI: invokes
- Raw responses → CLI: reads
- CLI → Batch normalization: normalizes batch
- CLI → Output file: writes
- CLI → Cost and tracing: emits records
- Library caller → Public API: calls
- Public API → Batch normalization: exports batch API
- Public API → Single normalization: exports single API
- Batch normalization → Single normalization: normalizes each
- Single normalization → Adapter selection: selects adapter
- Adapter selection → OpenAI adapter: detects or extracts
- Adapter selection → Anthropic adapter: detects or extracts
- Adapter selection → Bedrock adapter: detects or extracts
- Adapter selection → Gemini adapter: detects or extracts
- OpenAI adapter → Usage record: builds record
- Anthropic adapter → Usage record: builds record
- Bedrock adapter → Usage record: builds record
- Gemini adapter → Usage record: builds record
- Single normalization → Usage record: returns
- Usage record → Library caller: returns
- Usage record → Cost and tracing: feeds