Metadata-Version: 2.5
Name: agentevo-sdk
Version: 0.1.8
Summary: Agentevo client SDK, CLI, and agent adapters with conformance fixtures.
Project-URL: Homepage, https://agentevo.sh
Project-URL: Documentation, https://agentevo.sh/#setup
Author: Agentevo
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-memory,ai-agents,guardrails,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: agentevo-core==0.1.4
Requires-Dist: agentevo-local==0.1.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.7.0
Description-Content-Type: text/markdown

# agentevo-sdk

Client SDK, `agentevo` CLI, and agent adapters (Claude Code, Codex) for
[Agentevo](https://agentevo.sh) — CI/CD for agent intelligence.

Run this in a project where you have used Claude Code. The first line installs
the agentevo CLI; `pipx install agentevo-sdk` works too (Python 3.10+). A bare
`pip install` is refused by macOS Homebrew and Debian/Ubuntu system Pythons
(PEP 668), so use it only inside a virtualenv. Every line is copy-safe (no ids to
paste between commands), and nothing below talks to the cloud:

```sh
uv tool install agentevo-sdk
agentevo capture --latest
agentevo compile --latest --tenant your-org --project web
agentevo verify --latest --local
agentevo promote --latest --to Verified --local
agentevo recall "fix flaky test" --capabilities Bash,Edit,Read
```

- `capture --latest` captures the newest Claude Code session for the current
  directory. It reads `$CLAUDE_CONFIG_DIR/projects`, else `~/.claude/projects`.
  If no session exists for this directory, the error lists every folder it looked
  in. You can also pass files, one or many: `agentevo capture <file.jsonl>`, or
  `--adapter codex` for Codex transcripts.
- `compile --latest` compiles the session captured last. `verify --latest` and
  `promote --latest --to <Verified|Trusted>` act on every object version that
  compile created, and each result lists them under `acted_on`. Re-running is
  safe: versions already in the requested state are listed under `unchanged`. The
  explicit forms keep working: `agentevo verify <object-id> <version> --local` and
  `agentevo promote <object-id> <version> Verified --local`.
- Everything lands in the workspace `default` (the one every console account
  starts with), in `~/.agentevo/workspaces/default/vault.db`. `--workspace` (or
  `AGENTEVO_WORKSPACE`) picks another workspace, with its own vault. A vault an
  earlier release kept at `~/.agentevo/vault.db` keeps working for the workspace
  it was created with (`demo` was the old default: pass `--workspace demo`).
- Vault keys live in your OS keychain. On a machine without one (SSH boxes,
  containers, CI), set `AGENTEVO_VAULT_KEY` first, for example
  `export AGENTEVO_VAULT_KEY=$(openssl rand -hex 32)`, and keep it: the vault opens
  only with that key. Without either, `capture` stops and says so; no vault is
  written.
- `recall` returns Verified and Trusted objects that share at least half of the
  query's words. It checks the object and the prompt of the session it came from.
  An unrelated query returns nothing plus a hint. `--capabilities` must cover the
  tools a skill uses (recall reports `filtered_by_capabilities` and a hint
  otherwise).
- Trusted needs 3 independent passing runs (5 for destructive skills). One run is
  never enough, however often it is re-verified.
- Global flags (`--workspace`, `--vault`, `--base-url`, `--key-provider`,
  `--device-id`) go before the subcommand: `agentevo --workspace acme capture
  --latest`. Put one after it and the usage error prints the corrected command.

## See what it saved you

```sh
agentevo report --json
```

`report --json` prints one JSON object (`schema: agentevo.report/v1`) built from
this workspace's vault audit log; plain `agentevo report` writes the same numbers
to an HTML file. Every number is labelled:

- `measured`: counts Agentevo recorded. Sessions captured, secrets redacted
  before storage (`redactions_stored`, by detector), objects by state and type,
  time from the first capture to the first Verified skill, recalls served and the
  recall hit rate, sessions that reused a skill, guard decisions and repeat
  mistakes caught (a learned guard stopped the change it was learned from). A
  recall hit only means recall returned something; whether it helped shows in
  `reuse.after_recall`. `definitions` spells out each measured number.
- `estimated`: a stated formula applied to measured counts, never presented as
  measured. Tool calls saved is, over reuse sessions that succeeded,
  max(0, tool calls of the session the skill was learned from minus tool calls of
  the reuse session). Active minutes saved is the same difference over active time
  (gaps of at most 10 minutes between events). Guard tool calls avoided is, per
  catch, the tool calls the guard's source session spent from the guarded change
  to the failure it caused. Each formula is repeated under `estimated.formula`.

`compile` records reuse and lists it under `reused`. A session reuses a skill
when it repeats the skill's edits and test runs in order (at least 2 of them,
covering at least 60%) after the skill reached Verified or a recall returned it,
or when it names the skill. To name it, run
`agentevo recall "<task>" --use <object-id>` before or during the session (up to
30 minutes before its first event), or put `agentevo:use <object-id>` in the
prompt. A skill never counts as reused by the session it was learned from.

Recall, guard, capture and compile write these audit entries locally and send
nothing anywhere. They hold object ids, versions, states, decisions, counts,
ranks and relevance scores, plus a keyed digest of the recall query. They never
hold the query, prompts, commands, paths or tool output.

Raw data stays local by default. The cloud is opt-in:

```sh
agentevo login
agentevo sync mode --set searchable --terms-version 2026-09-21 --yes
agentevo sync push
agentevo recall "fix flaky test" --capabilities Bash,Edit,Read --cloud
```

`login` asks for a key from the console (API keys) and checks it against the
cloud before storing it in your OS keychain; set `AGENTEVO_PAT` instead to skip
the prompt (on a machine without an OS keychain, such as CI, the variable is all
the CLI needs and `login` only checks it). `login` reports `"stored": true` only
when the key reads back from the keychain; a keyring that keeps nothing (the
`null` backend) gets `"stored": false` and a note that `AGENTEVO_PAT` is the
key's source. The CLI talks to the hosted API,
`https://api.agentevo.sh`; point `--base-url` (or `AGENTEVO_BASE_URL`) at a
self-hosted server instead. `sync push` queues locally, and says so, when the
cloud is unreachable. Pushing from a second or fresh vault lists versions the
cloud already holds under `already_present` (exit 0). In a `local_only`
workspace (the default, or after an owner downgrades it) `sync push` sends
nothing and exits 1 with `FORBIDDEN`. The message names the exact consent command
to run, and `details.consent_command` holds it too. Reading the workspace's sync
mode is a billable request, so `sync push` and `sync pull` read it at most once
every 10 minutes and remember it in the vault (a `local_only` workspace is read
on every sync). `sync mode --set` makes the next sync read it again. The cloud
checks the mode on every push: when an owner changed it elsewhere, the cloud
refuses the push and stores nothing, and `sync push` reads the mode again and
pushes once more.

Objects pulled onto another machine arrive as Candidates, because trust never
transfers between machines. `sync pull` says so. `recall` withholds them, but
counts matching ones under `withheld_pulled_candidates`, lists them under
`pulled_candidates`, and gives the commands to run from your checkout:
`agentevo verify <object-id> <version> --local --workdir .` replays the object's
test command there, then `agentevo promote <object-id> <version> --to Verified --local`.
Without `--workdir` the verify is inconclusive and says why: the evidence stays
on the machine that pushed it.

Searchable sync sends sanitized step templates and fingerprints only. File
contents, diffs, command output, prompts and absolute paths stay on your machine.
Opaque Relay sends the full steps, end-to-end encrypted under a workspace key
the cloud never sees: create it once, on the first machine, with
`agentevo sync key --init`, and carry it to each other machine with
`sync key --export FILE` there and `sync key --import FILE` (machines that
share `AGENTEVO_VAULT_KEY` already share it). Sync identifies your
machine by a random device id that the vault creates once; your username and
hostname are never sent. `--tenant your-org` is only a label while you work
offline: `sync push` sends a workspace's objects to the tenant you are logged in
to and lists the ones it relabeled. Cloud rows show `cloud_state`. The managed
copy reaches Trusted only with independent evidence from a device. One run is
never enough for Trusted. See [agentevo.sh](https://agentevo.sh) for more.

## License

Apache License 2.0 — see the `LICENSE` file shipped with this package.
