diff --git a/CHANGELOG.md b/CHANGELOG.md index e886888..ae4f360 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ trace, study, receipt, API and database schema versions. ## [Unreleased] +### Documentation + +- The README has an Install section covering the PyPI package, the npm + TypeScript SDK and standalone executables, an npm badge, and a JavaScript + tracing example verified against the published npm package. The + installation guide documents `npm install agentloop-profiler` instead of + saying npm publication is pending. +- The README integrations table lists the TypeScript SDK and the Codex and + Claude Code runners. The API, upgrade and installation guides cover the + npm package's client, upgrades and version check. +- The TypeScript SDK README says how to install the `agentloop` CLI that + analyzes its traces. + ## [0.2.6] - 2026-11-19 ### Added diff --git a/README.md b/README.md index db2eb66..b5299d0 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@
Documentation · + Install · Quickstart · Improve an agent · Trace your code · @@ -37,13 +39,24 @@ The core Python SDK and CLI work with JSON files. You can trace and analyze your code without a hosted account or database. A dashboard, HTTP API, and shared storage are available as optional components. -For Node.js and browser applications, the source checkout includes a -[TypeScript SDK](https://github.com/dipeshbabu/agentloop/blob/main/sdk/typescript/README.md) with native tracing and an API v1 client. -It has no runtime dependencies and installs with `npm install agentloop-profiler`. +## Install + +AgentLoop is published as `agentloop-profiler` on PyPI and on npm. + +| Install | For | Requires | +| --- | --- | --- | +| `python -m pip install agentloop-profiler` | Python SDK and the `agentloop` CLI, which analyzes traces, writes reports and runs the guided workflow | Python 3.11+ | +| `npm install agentloop-profiler` | [TypeScript SDK](https://github.com/dipeshbabu/agentloop/blob/main/sdk/typescript/README.md) for Node.js and browser code: native tracing and an API v1 client, with no runtime dependencies | Node.js 22+ | +| [Standalone executable](#standalone-cli) | The `agentloop` CLI without installing Python | Linux, macOS or Windows | + +The two packages are versioned separately and share the trace format, so traces +recorded with the TypeScript SDK are analyzed with the `agentloop` CLI. See the +[installation guide](https://dipeshbabu.github.io/agentloop/installation/) for +virtual environments, optional extras and installing from source. ## Quickstart -Install with Python 3.11 or newer: +Install the Python package and record an example trace: ```bash python -m pip install agentloop-profiler @@ -54,9 +67,9 @@ agentloop analyze runs/agentloop_quickstart.json --html runs/report.html --json- Open `runs/report.html` in your browser to inspect the timeline and findings. `runs/analysis.json` contains the trace, metrics, diagnosis, and optimization plan. -The package name is `agentloop-profiler`; the Python import and CLI command are -both `agentloop`. `quickstart` creates a labeled synthetic trace and makes no model -API calls. It tests your installation, not your application's performance. +The Python import and CLI command are both `agentloop`. `quickstart` creates a +labeled synthetic trace and makes no model API calls. It tests your installation, +not your application's performance. If your shell cannot find `agentloop`, activate the Python environment where you installed it. Run `agentloop doctor` to check the installation and available adapters. @@ -178,6 +191,40 @@ Saving `metadata["output"]` is an explicit choice in this example. Review the inputs, outputs, errors, and metadata you retain before sharing real traces. See [trace retention](https://dipeshbabu.github.io/agentloop/TRACE_RETENTION/) for capture controls. +### From TypeScript or JavaScript + +After `npm install agentloop-profiler`, save this as `example_agent.mjs`: + +```javascript +import { writeFile } from "node:fs/promises"; +import { AgentTrace } from "agentloop-profiler"; + +const NOTES = { + tracing: "Record the steps in a workflow.", + optimization: "Investigate repeated or expensive work.", +}; + +const trace = new AgentTrace("research_agent", { metadata: { synthetic: true } }); +const notes = []; +for (const topic of Object.keys(NOTES)) { + notes.push(await trace.tool("lookup_note", async () => NOTES[topic])); +} +trace.setOutput({ notes }); +trace.finish(); +await writeFile("research_agent_js.json", trace.toJSONString()); +``` + +Run it and analyze the trace with the `agentloop` CLI: + +```bash +node example_agent.mjs +agentloop analyze research_agent_js.json --html research_agent_js.html +``` + +The SDK also records model calls with provider token usage, retries and nested +spans, and can send traces to the HTTP API. See the +[TypeScript SDK guide](https://dipeshbabu.github.io/agentloop/reference/typescript/). + ## Inspect findings For a fixed task set, use the [guided workflow](#guided-optimization) to capture @@ -307,6 +354,8 @@ gate. Run `agentloop COMMAND --help` to see its output options and thresholds. | Source | Integration path | | --- | --- | | Custom Python agents and pipelines | Decorators, context managers, and [workflow annotations](https://dipeshbabu.github.io/agentloop/WORKFLOW_TRACING/). | +| TypeScript and JavaScript applications | `npm install agentloop-profiler`, then record model, tool and retry spans with the [TypeScript SDK](https://dipeshbabu.github.io/agentloop/reference/typescript/). | +| OpenAI Codex CLI and Claude Code | Built-in [Codex](https://dipeshbabu.github.io/agentloop/CODEX/) and [Claude Code](https://dipeshbabu.github.io/agentloop/CLAUDE_CODE/) runners for the guided workflow. | | OpenAI SDK | Wrap a client or callable to capture calls, streams, and reported usage. | | OpenAI Agents SDK | Attach an AgentLoop tracing processor. | | LangGraph | Instrument the builder before adding nodes, then wrap the compiled runnable. | @@ -372,7 +421,9 @@ uv run --frozen --all-extras streamlit run dashboard/app.py Open Streamlit's printed URL and leave the sidebar's Project field set to `default`. Use `store-trace` to load your own files. Storage uses SQLite by default and also supports Postgres. The optional HTTP API serves project-scoped traces and reports -through `/v1` endpoints. +through `/v1` endpoints. Python applications use `agentloop.AgentLoopClient`; +TypeScript applications use `AgentLoopClient` from the npm package to upload +traces and read reports. See [dashboard setup](https://dipeshbabu.github.io/agentloop/DASHBOARD/), [API versioning](https://dipeshbabu.github.io/agentloop/API_VERSIONING/), and [production deployment](https://dipeshbabu.github.io/agentloop/PRODUCTION/) for configuration and authentication. diff --git a/docs/API_VERSIONING.md b/docs/API_VERSIONING.md index 3666c53..ec035a9 100644 --- a/docs/API_VERSIONING.md +++ b/docs/API_VERSIONING.md @@ -16,6 +16,10 @@ This sends `GET /v1/traces?page_size=20`. A mount such as requires a server with v1 support; upgrade the server before upgrading clients. Older clients can continue using the deprecated unversioned aliases during 0.x. +The TypeScript SDK's `AgentLoopClient`, installed with +`npm install agentloop-profiler`, uses the same `/v1` routes. See the +[TypeScript SDK guide](../sdk/typescript/README.md#use-the-api). + The Python client rejects redirects so project and admin keys cannot be forwarded to another endpoint. Credentials are omitted from its representation, and HTTP errors report the status without copying response bodies. Responses must be JSON diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 3b071a3..1f3afa0 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -1,5 +1,10 @@ # Existing installations and stored data +The TypeScript SDK is published on npm as `agentloop-profiler` and is versioned +separately from the Python package. Upgrade it in your application with +`npm install agentloop-profiler@latest`. Native trace schema 1.1 and API v1, +not package versions, determine compatibility with the Python CLI and server. + Version `0.2.0` adds the guided `improve init`, `capture`, `start` and `finish` workflow. Python 3.11 remains the minimum. Existing explicit `--tasks FILE` commands and runner argv remain valid; `agentloop.toml` is optional data-only @@ -27,8 +32,8 @@ Version `0.1.1` requires **Python 3.11 or newer** so supported installations can use patched dependencies. It adds Hermes tracing and fixes CLI output collisions, retry/error reporting, and API client credential handling. Native trace schema 1.1, API v1, and database migration IDs continue unchanged; retain existing data. -The TypeScript SDK remains a separately versioned source package, with npm -publication pending. +The TypeScript SDK was then a separately versioned source package; it has since +been published on npm. Version `0.1.0` includes the evidence workflow: canonical findings and estimator provenance, intervention records, paired studies, offline HTML reports, telemetry diff --git a/docs/index.md b/docs/index.md index a044eec..9e09df9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,6 +33,9 @@ agentloop analyze runs/agentloop_quickstart.json --html runs/report.html Open `runs/report.html` to inspect the timeline and findings. This example runs locally with synthetic data. +For Node.js or browser code, `npm install agentloop-profiler` installs the +[TypeScript SDK](../sdk/typescript/README.md); analyze its traces with the same CLI. + ## How AgentLoop fits your workflow diff --git a/docs/installation.md b/docs/installation.md index e9f4a71..58808e2 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -5,8 +5,14 @@ search: # Installation -AgentLoop requires Python 3.11 or newer. The package is `agentloop-profiler` and -the Python import and CLI command are `agentloop`. +AgentLoop is published as `agentloop-profiler` on PyPI and on npm: + +- the Python package (Python 3.11 or newer) provides the Python SDK and the + `agentloop` CLI, which analyzes traces, writes reports and runs the guided + workflow. The Python import and CLI command are `agentloop`; +- the npm package (Node.js 22 or newer) provides the + [TypeScript SDK](#typescript) for recording traces from Node.js and browser + code. Analyze its traces with the `agentloop` CLI. ## Published package @@ -86,6 +92,21 @@ client compatibility and optional dependency updates. ## TypeScript -The separately versioned TypeScript SDK supports Node.js 22 and newer. Follow -its [source installation instructions](../sdk/typescript/README.md). -Its initial npm publication is pending. +The TypeScript SDK is versioned separately from the Python package and supports +Node.js 22 and newer. Install it in your application: + +```bash +npm install agentloop-profiler +``` + +Upgrade an existing install with `npm install agentloop-profiler@latest` and check +the installed version with `npm ls agentloop-profiler`. + +It is an ESM package with TypeScript declarations and no runtime dependencies. +Import from `agentloop-profiler` for tracing and `agentloop-profiler/client` for +the HTTP API client. Published versions are listed on +[npm](https://www.npmjs.com/package/agentloop-profiler), with provenance linking +each version to the workflow that built it. + +The [TypeScript SDK guide](../sdk/typescript/README.md) covers tracing, model usage, +the API client and building the SDK from source. diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md index ddf92a4..a5bd078 100644 --- a/sdk/typescript/README.md +++ b/sdk/typescript/README.md @@ -61,9 +61,13 @@ trace.finish(); await writeFile("trace.json", trace.toJSONString()); ``` -Analyze this local example with the Python CLI: +Analyze this local example with the `agentloop` CLI. It comes from the Python +package (Python 3.11 or newer), or use a +[standalone executable](https://github.com/dipeshbabu/agentloop#standalone-cli) +that needs no Python: ```bash +python -m pip install agentloop-profiler agentloop analyze trace.json --html report.html ```