AgentMargin v0.3.0-alpha

AgentMargin v0.3.0-alpha

Experimental open-source alpha, source-first and localhost-only. Not production-certified.

Do not expose the API/dashboard to the public internet or ingest real customer data without an independent deployment and security review.

This release advances AgentMargin from its v0.2 local accounting demo to workspace-specific, auditable AI model pricing and a redesigned compact dark analytics workspace, while preserving the existing source-first SDK and customer-level inference contribution calculations.

Highlights

1. Auditable model prices for each workspace

• Authenticated GET /v1/prices and POST /v1/prices; the server determines the workspace from the bearer key, not client input.
• Exact nonnegative USD microdollar rates per million input, output, and optional cached-input tokens; the dashboard accepts familiar USD prices and converts without floating-point accounting.
• Explicit UTC effective-from and optional effective-to timestamps, source/verification notes, server-generated price version IDs, creation timestamps, and creator-key digests (not raw keys).
• Append-only PostgreSQL history (updates and deletes blocked) and workspace-bound foreign keys for usage events referencing a price version.
• New prices are used for subsequent ingestion at matching event timestamps. Already-persisted inference costs do not change when a price is added or superseded.
• Missing prices, including missing cached-input rates when needed, mean unknown cost, never an implicit $0.
• Legacy global price versions remain as read-only fallback for earlier timestamps; validate any rates before relying on them.

See workspace pricing semantics and limitations.

2. Compact dark analytics dashboard

• React 19/Vite replacing the inline HTML preview when the frontend is built.
• Genuine free MIT-licensed Arc UI source components for controls; upstream license is included in apps/web/ARC_LICENSE.txt. The dashboard's neutral dark layout is original AgentMargin code, informed by developer SaaS dashboard references.
• Functional workspace access, period selection, customer search/status filters, revenue and known AI-cost comparison, coverage summary, loss-making customer signals, and unknown-cost model diagnostics.
• Model Pricing view to create workspace-specific price versions and inspect a bounded version history.
• No fabricated time series, growth deltas, pricing amounts, or phantom actions. Unknown customer costs are marked unverified and partial.
• Responsive desktop/mobile, accessible labels and keyboard controls, and reduced-motion styles.

3. Verification

GitHub Actions exercises:

• npm ci, Vite build, TypeScript typecheck, source SDK/core/API tests.
• PostgreSQL 16 tenant isolation, ingestion idempotency, immutable pricing history and effective-date behavior.
• Dependency audit and heuristic source secret scan.
• Real Chromium desktop/mobile tests for the dashboard, pricing form and validation, including a live synthetic Docker PostgreSQL → local API → SDK → analytics → browser flow.

The source release is validated against disposable, synthetic data; a passing CI run does not establish production security.

Quickstart

Requirements: Node.js 22.18+ (24 recommended), npm, OrbStack or Docker with Compose, and ports 55432/8787 available.

git clone https://github.com/rzkarsyad/agentmargin.git
cd agentmargin
npm ci
npm run demo

The command builds the React dashboard, boots localhost-only PostgreSQL, migrates the schema, seeds three fictional customers and prints a newly generated AgentMargin workspace API key. Open http://127.0.0.1:8787/dashboard and enter the key. Choose a period including the current UTC date.

The optional synthetic OpenAI-shaped event/revenue example is documented in the demo guide. No actual OpenAI credentials or network calls are required for the demo.

Use Ctrl+C to stop the API and npm run demo:stop to stop the demo container without deleting its database volume. The destructive npm run demo:reset requires explicit confirmation; read the demo guide before resetting.

Migrating an existing v0.2 development database

Only for a disposable development database previously migrated through 003:

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/004_workspace_pricing.sql
npm ci
npm run build:web

Migration 004 adds workspace price version records and a new optional price link on usage events. Existing records remain intact. No automatic down-migration or production upgrade procedure is shipped. Use the one-command demo for the safest synthetic evaluation path.

Known limitations and safety

• Local-only experimental alpha. Not suitable for unreviewed public deployments or actual customer financial data.
• AI contribution here means revenue minus tracked inference cost, not gross margin or full net profit; other costs and provider billing reconciliation are not included.
• No official provider pricing catalog, automatic instrumentation, stable npm SDK release, or hosted service.
• Price versions are append-only, but any valid workspace key can add pricing versions; this is not a multi-user RBAC or approval system.
• No PostgreSQL RLS, audited TLS ingress, distributed rate limiting, production backup/restore, privacy lifecycle, or independent penetration test.
• Dashboard analytics and price history are bounded; truncation is surfaced, and displayed results must not be confused with complete organization totals.

Read SECURITY.md before running the API, local setup, roadmap, and contributing guidelines.

Previous release

v0.2.0-alpha — one-command local demo, OpenAI post-call helpers and unknown-cost model diagnostics.

AgentMargin v0.2.0-alpha

AgentMargin v0.2.0-alpha

Experimental open-source release — localhost-only, not production-ready.

AgentMargin helps developers attribute AI inference costs and revenue to customers so they can understand which customers create or consume AI contribution. This alpha focuses on developer experience, trusted accounting semantics and verifiable local testing.

Highlights

Run a local demo with one command

git clone https://github.com/rzkarsyad/agentmargin.git
cd agentmargin
npm ci
npm run demo

Requires Node.js 22.18+ and OrbStack/Docker Compose. The script starts a localhost-bound PostgreSQL container, applies migrations, seeds synthetic usage/revenue and prints a new local workspace API key. Open http://127.0.0.1:8787/dashboard and select a period covering today. The demo includes one profitable customer, one loss-making customer and one whose cost is unknown.

Stop the API with Ctrl+C; stop the demo container with npm run demo:stop. Demo reset requires explicit confirmation and deletes synthetic demo data. See docs/DEMO.md.

Track completed OpenAI requests

The source-first TypeScript SDK adds one-call post-response metering helpers for OpenAI Responses and Chat Completions:

await margin.trackOpenAIResponse(response, trustedCustomerId);

These map token/model metadata only and do not send prompts, outputs, or OpenAI credentials to AgentMargin. They reject missing usage rather than assuming zero cost. A Next.js integration recipe and a synthetic SDK example are included. The SDK is not yet published on npm and automatic instrumentation is not implemented.

Understand unknown costs

Authenticated analytics adds a per-model unknown-event count for the selected workspace and time range. The dashboard displays up to 20 affected models with a truncation notice. Model strings are safely rendered as text, not HTML. Adding a price later does not silently alter historical events. See docs/UNKNOWN_COSTS.md.

Stronger end-to-end checks

GitHub Actions now exercises a complete disposable Docker PostgreSQL → localhost authenticated API → SDK → real Chromium dashboard workflow on desktop and mobile, in addition to TypeScript, unit tests, PostgreSQL concurrency, npm audit, a heuristic credential scan and mocked-API browser tests.

The maintainer also confirmed the local demo in OrbStack and the synthetic SDK integration on October 22, 2026, including expected revenue/costs and unknown-cost diagnostics.

Compatibility

• Node.js 22.18+ (24 recommended), npm.
• PostgreSQL 15+ for the API; the one-command demo uses Docker PostgreSQL 16.
• This alpha remains a source-first monorepo. Core and SDK are not released as stable registry packages.
• Existing database migrations are unchanged; no production migration or deployment upgrade is offered.

Known limitations

• No automatic provider model price catalog or provider invoice reconciliation; do not infer missing costs as zero.
• Contribution includes tracked inference costs only, not full gross or net profit.
• No production reverse proxy/TLS, multi-instance rate limiting, PostgreSQL RLS, audited backup/restore, privacy lifecycle, or independent penetration test.
• Browser E2E covers local synthetic data; no real customer traffic or production service is certified.
• Current dashboard remains a localhost-oriented preview with bounded customer and model diagnostics.

Use synthetic data only. Do not deploy this alpha to the public internet. Review SECURITY.md.

Feedback and contributions

Feedback from AI SaaS developers, independent setup attempts, reproducible bugs and security reports are appreciated. See the contributing guide, roadmap, and early-adopter issue.

Prior release: v0.1.0-alpha.

AgentMargin v0.1.0-alpha

AgentMargin v0.1.0-alpha — Release Notes

Status: experimental open-source source preview, not production-ready.

What's included

• TypeScript cost engine with exact USD microdollar arithmetic.
• Historical model-pricing support for input, output and cached tokens.
• Reported / estimated / unknown inference cost states.
• Customer/workspace-scoped margin computation, where incomplete costs suppress final margin.
• PostgreSQL schema, authenticated API for usage/revenue ingestion and local analytics.
• Idempotent retries, tenant-scoped filtering and concurrency controls.
• Source-first TypeScript SDK and manual OpenAI Responses / Chat Completions usage helpers.
• Local browser analytics preview.
• CI with Node.js typecheck/tests, PostgreSQL concurrency, secret scanning, dependency audit and Chromium smoke testing using mocked API responses.

What this release is not

• Not an npm-published SDK or automatic OpenAI instrumentation.
• Not a hosted service or production deployment guide.
• No built-in current provider price catalog, Stripe import or automated revenue sync.
• No independent penetration test, database RLS or public TLS gateway.
• No completed real-server/browser end-to-end security verification for an internet-facing deployment.

Upgrade and start

There is no prior public release to upgrade from. See Quickstart for the example engine and optional local PostgreSQL API.

Known limitations

• Pricing must be trustworthy and manually supplied or reported; costs can be unknown.
• USD contribution excludes hosting, payment fees, support and other non-inference spend.
• Dashboard query range and response count are limited; truncated results are flagged.
• Rate limiting operates per process and should not be treated as public ingress protection.
• Do not use real customer data in an unreviewed environment.

Verification

A private staging workflow passed on commit ea46228: CI Run #2. The onboarding documentation update must pass its own CI before this alpha tag is published.

We welcome setup feedback and minimal reproducible issues (never attach secrets or real customer data).