From ef772ce5dabd1ae9904d8b1989bf6bfb72121fb9 Mon Sep 17 00:00:00 2001 From: Khemchand Joshi Date: Sat, 20 Jun 2026 13:28:10 +0530 Subject: [PATCH] docs(release): add v0.1.0 release notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/releases/v0.1.md — highlights, what's-included (core/backends/integrations/ governance/accountability), the 17 packages, end-to-end validation against real backends (Bedrock + Jaeger/Prometheus/Grafana + Langfuse Cloud), quality bar, and known limitations. Sourced for the GitHub Release when v0.1.0 is cut. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/releases/v0.1.md | 117 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/releases/v0.1.md diff --git a/docs/releases/v0.1.md b/docs/releases/v0.1.md new file mode 100644 index 0000000..40b56bd --- /dev/null +++ b/docs/releases/v0.1.md @@ -0,0 +1,117 @@ +# ForgeSight v0.1.0 + +_First public release — 2026-06-20._ + +**Instrument any AI agent in a few lines — then ship traces, cost, metrics, evals, budgets, +and a tamper-evident audit trail to any backend by changing one line of config. +OpenTelemetry-first. Vendor-neutral. Never an agent-code change.** + +```bash +pip install "forgesight[otel]" +``` + +```python +import forgesight +from forgesight import telemetry + +forgesight.configure(exporters=["otel"]) # pick a backend by name — that's it + +with telemetry.agent_run("pr-reviewer", version="2.1.0", metadata={"team": "platform"}) as run: + with run.llm_call("anthropic", "claude-sonnet-4-5") as call: + resp = await client.messages.create(...) + call.record_usage(input=resp.usage.input_tokens, output=resp.usage.output_tokens) + with run.tool_call("github_get_diff"): + diff = gh.get_diff(pr) +``` + +--- + +## Highlights + +- **Vendor-neutral by design.** The core depends on *no* backend or model-provider SDK. + Backends are packages you install and select by config — swap `otel` → `langfuse`, + `datadog`, `clickhouse`, `prometheus` with zero agent-code change. +- **OpenTelemetry-first.** The wire format is the OTel GenAI semantic conventions, so any + OTLP backend (Honeycomb, Jaeger, Tempo, New Relic, Phoenix, …) works with no dedicated + package. +- **Cost built in.** Token usage → USD via a pluggable, refreshable pricing table — the same + number on every backend. +- **Non-blocking & fault-isolated.** Export runs on a background worker; a backend outage is + counted and invisible to your agent. `export()` returns failure, never raises. +- **Secure by default.** Prompt/response content is never captured unless you opt in, with a + redaction interceptor before export. +- **Accountability, not just observability.** Live cost attribution by team/owner, pre-call + budget projection (deny *before* the spend), and a **tamper-evident, hash-chained audit + trail** with a compliance query/export surface. + +## What's included + +**Core (the vendor-neutral heart)** +- Immutable domain model + four locked `Protocol` SPIs (exporter, interceptor, event + listener, pricing) — each with a conformance suite. +- Instrumentation runtime: context propagation, span tree, `agent_run`/`workflow_run`/ + `step`/`llm_call`/`tool_call`/`mcp_call`, and an `@instrument` decorator. +- Async, bounded, fault-isolated export pipeline (batching, sampling, flush/shutdown). +- OpenTelemetry exporter + GenAI semantic-convention mapping (OTLP traces & metrics, W3C + propagation), with version pinning. +- Metrics & instruments, cost model + pricing registry, event bus, PII-redaction & + content-capture interceptors, error/exception tracking, zero-config + file/env config. + +**Backends & exporters** — `otel`, `prometheus`, `langfuse`, `clickhouse`, `datadog`. + +**Integrations** — `mcp` (client/server + W3C), `fastapi` (request↔run correlation + +flush-on-deploy), `github` (CI run↔commit/PR/job + cost summary), framework adapters +(`adapters-langgraph`, `adapters-crewai` — zero agent-code change). + +**Governance & accountability** +- Cost budgets, declarative policy, and a kill-switch (`governance`) — plus **pre-call + budget projection** that denies an over-budget call before it spends. +- **Live attributed-cost metrics** (`forgesight.cost.attributed_usd` by team/owner) and a + budget-utilization gauge. +- Eval scores & human feedback (`eval`); agent registry, ownership & chargeback (`registry`). +- **Tamper-evident audit trail** (`audit`): hash-chained, complete-capture (records every + run even when the trace is sampled out), with `verify()` + a compliance query/export + surface. + +## Verified end-to-end + +This release was validated against **real backends**: live AWS Bedrock agents instrumented +with ForgeSight, exporting traces to Jaeger (OTLP), metrics to Prometheus → Grafana, and a +verified audit chain — plus the Langfuse exporter confirmed against Langfuse Cloud. See +[`examples/agents/`](../../examples/agents/) (ReAct / RAG / multi-agent), +[`examples/bedrock-e2e/`](../../examples/bedrock-e2e/), and the offline +[`examples/demo.py`](../../examples/demo.py). + +## The 17 packages + +`forgesight-api` · `forgesight-core` · `forgesight` · `forgesight-otel` · +`forgesight-prometheus` · `forgesight-langfuse` · `forgesight-clickhouse` · +`forgesight-datadog` · `forgesight-mcp` · `forgesight-fastapi` · `forgesight-github` · +`forgesight-governance` · `forgesight-eval` · `forgesight-registry` · `forgesight-audit` · +`forgesight-adapters-langgraph` · `forgesight-adapters-crewai` + +A `uv` workspace, three-tier model (contracts → runtime → integrations), Apache-2.0, +Python 3.11–3.13. `pip install forgesight` gives the facade; add backends/integrations as +extras (`pip install "forgesight[otel,governance,audit]"`). + +## Quality bar + +`ruff format` + `ruff check` + `mypy --strict` + `pytest` (coverage ≥ 90%, with a +per-PR patch-coverage gate) across Python 3.11/3.12/3.13, plus full-history secret scanning — +all enforced in CI on a protected `main`. + +## Known limitations / what's next + +- **TypeScript parity** is planned (Python first). +- **Bedrock pricing** isn't in the built-in pricing table yet — use `set_cost()` or a pricing + override for Bedrock model ids (auto-derived cost is a tracked follow-up). +- The 0.5 accountability roadmap continues: agent identity attribution (feat-024), a + declarative runtime policy DSL (feat-025), and GenAI-semconv conformance (feat-027). +- Pre-call budget projection is process-local; a cross-process budget store is a follow-up. + +## Links + +- [README](../../README.md) · [Playbooks](../playbooks/) · [Runbooks](../runbooks/) +- [Feature catalogue](../features/README.md) · [Architecture](../design/architecture.md) · + [ADRs](../adr/) +- [Contributing](../../CONTRIBUTING.md) · [Security policy](../../SECURITY.md)