README

A standalone, zero-dependency PHP 8.3+ execution store for tracking AI pipeline runs with cost, latency and token metrics. Supports JSONL, SQLite and InMemory backends — usable in any framework or domain.

Why nexus-ai-tracking?

When building AI pipelines (content generation, code assistants, data processors…) you need to answer:

How much did that run cost?
Which model is slowest?
Which prompt version performs best?
What failed and when?

nexus-ai-tracking gives you append-only, immutable event recording with zero configuration and three backends that suit any environment — from a local script to a production cluster.

Features

Append-only event store — immutable audit trail, no updates ever
3 backends — JSONL files, SQLite, InMemory (testing)
Thread-safe writes — flock() file locking on JSONL, transactions on SQLite
Auto-schema — SQLite creates its own schema on first use
Daily file partitioning — JSONL files split by day, automatic date-range optimization
Flexible aggregate queries — filter by model, content type, language, date range, event type
Run projections — grouped RunSummary with status, cost, tokens, latency, step count
Extensible — add new backends by implementing one interface
Zero external dependencies — only ext-json required

Installation

composer require token27/nexus-ai-tracking

Requires: PHP 8.3+ · ext-json · ext-pdo_sqlite (SQLite backend only)

Quick Start

use Token27\NexusAI\Tracking\Engine\TrackingEngine;
use Token27\NexusAI\Tracking\Enum\ExecutionEventType;

// 1. Initialize tracker
$tracker = TrackingEngine::using('sqlite', '/var/data/tracking.sqlite');

// 2. Fluent Event Recording
$tracker
    ->track(ExecutionEventType::PROMPT_EXECUTED, 'run-abc123')
    ->withModel('gpt-4o')
    ->withTokens(1500)
    ->withCostUsd(0.045)
    ->withLatencyMs(850)        
    ->with('prompt', [
        'source' => 'seo/article',
        'version' => 'v2.1',
        'content' => 'Prompt content generated here',
    ])
    ->with('metadata', [        
        'title' => 'Article title seo optimized',
        'content' => 'Article content seo optimized',
        'created' => '2026-05-21'           
    ])
    ->record();

// 3. Fluent Querying
$metrics = $tracker->query()
    ->withData('model', 'gpt-4o')
    ->withLastPeriod('-7 days')
    ->metrics();

echo "Total cost last 7 days: \${$metrics->totalCostUsd}\n";
echo "Total tokens: {$metrics->totalTokens}\n";
echo "Avg latency: {$metrics->avgLatencyMs}ms\n";

Backends

Backend	Driver key	Best for
`JsonFileExecutionStore`	`jsonfile`	Default — zero config, portable, daily JSONL files
`SqliteExecutionStore`	`sqlite`	Aggregate queries, production apps
`InMemoryExecutionStore`	`memory`	Unit tests — zero I/O

Documentation

Full documentation is available in the docs/ directory:

Requirements

PHP 8.3 or higher
ext-json (bundled with PHP)
ext-pdo + ext-pdo_sqlite (only for SQLite backend)

Contributing

Please see docs/contributing.md for details on adding new backends, event types, and development standards.

License

MIT. Please see LICENSE for more information.

token27 / nexus-ai-tracking

Maintainers

Package info

Statistics

Security