Metadata-Version: 2.4
Name: alpi-agent
Version: 0.15.3
Summary: A profile-based personal AI agent for terminal, desktop & mobile apps, and private ALP networks
Author: Satoshi Ltd.
License-Expression: BUSL-1.1
Project-URL: Homepage, https://alpi.satoshi.ltd
Project-URL: Repository, https://github.com/satoshi-ltd/alpi
Project-URL: Issues, https://github.com/satoshi-ltd/alpi/issues
Project-URL: Changelog, https://github.com/satoshi-ltd/alpi/blob/main/CHANGELOG.md
Keywords: agent,ai,cli,llm,personal-agent,privacy,agent-to-agent,email
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm<1.101,>=1.100.0
Requires-Dist: rich>=13.7.0
Requires-Dist: prompt_toolkit>=3.0.43
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx<0.29,>=0.27.0
Requires-Dist: httpcore<2,>=1.0
Requires-Dist: click>=8.1.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: textual>=0.86.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: croniter>=2.0.0
Requires-Dist: playwright>=1.44
Requires-Dist: playwright-stealth>=1.0.6
Requires-Dist: pillow>=10.0
Requires-Dist: edge-tts>=7.0
Requires-Dist: faster-whisper>=1.0
Requires-Dist: cryptography>=42.0
Requires-Dist: setproctitle>=1.3
Requires-Dist: python-gnupg>=0.5
Requires-Dist: qrcode>=7.4
Requires-Dist: websockets>=13.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: fastembed<1.0,>=0.3
Requires-Dist: pypdf>=4.0
Requires-Dist: python-docx>=1.1
Requires-Dist: ebooklib>=0.18
Requires-Dist: rapidocr-onnxruntime>=1.3
Requires-Dist: pypdfium2>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Dynamic: license-file

# alpi

**Your private agent network.**

alpi starts as the agent in your terminal, then grows with you:
profiles for work, cron, home servers, research, and workgroups with other
alpis. Each profile owns its memory, keys, model, skills, approvals,
and trust boundary. ALP links them across machines without
a registry, central account, or mandatory cloud.

Bring any model. Keep every key. Run one alpi, or a network that stays
yours.

## Why alpi exists

Most useful agents eventually become infrastructure: they hold memory,
touch files, run commands, answer from a phone, wake up on schedules,
and coordinate work across machines. alpi treats the **profile** as
the unit of that infrastructure, not the chat.

The design goal is sovereignty:

- **Local-first by default.** State lives under `~/.alpi/` or a named
  profile. Memory, sessions, skills, keys, logs, and peer lists are
  files on your machine.
- **User-owned models.** Fresh profiles ship with no default model.
  You pick the provider, model, API key, or Ollama server per profile.
- **Security as product shape.** Shell commands pass a three-tier
  approval system. Dangerous commands are blocked with no override.
  Web and email content is treated as hostile data. Skills and MCPs
  are scanned before install.
- **Operational UX.** One setup wizard, a live `doctor`, a single
  per-machine `alpi daemon` supervisor for every profile (scheduler +
  ALP + workgroups + host plane), merged logs, backup,
  and cleanup.
- **Private coordination.** ALP.1 links local profiles, ALP.2 links
  machines over Noise_XK, and ALP.3 adds shared workgroups. Peers are
  pinned by Ed25519 identity and governed by fail-closed capabilities.
  No discovery service, no shared account, no central broker.
- **Honest provider boundaries.** alpi does not reverse-engineer
  ChatGPT Plus, Claude Pro, Claude Code, or other first-party
  subscription clients. If a vendor publishes an official third-party
  OAuth flow, alpi can adopt it. Until then, users pay per-token API
  access through their own keys.

## What ships today

- **Chat surfaces.** A Textual TUI with streaming replies, slash commands,
  live tool cards, interrupt and session resume; a desktop app and a mobile
  app that pair with your own daemon over the host plane.
- **Attachments and knowledge.** Attach images, PDFs and source files to a
  turn. Ask alpi to learn a document and it synthesises durable Markdown
  knowledge in your workspace instead of storing the raw file. Semantic
  recall over past sessions and workgroup history is opt-in and forgettable.
- **Memory.** Three plain-Markdown files — `USER.md`, `MEMORY.md`,
  `AGENT.md` — updated inline during conversations.
- **Skills.** Reusable recipes under the profile's own `skills/`,
  scanner-gated and injected into the system prompt.
- **Models.** Any provider through LiteLLM, first-class Ollama, per-profile
  fast / deep tiers and fallbacks, and a daily USD cap enforced on every turn.
- **Sub-agents.** Read-only `research` with three depth tiers, write-capable
  `delegate`, and bounded tool workflows.
- **Automation.** Cron and one-shot schedules hosted by the daemon; an
  on-demand email tool (IMAP or Gmail) the agent reads and sends through — not
  an inbound channel; a client for local MCP servers.
- **ALP.** Same-machine links over Unix sockets, inter-machine links over
  Noise_XK with per-peer rate limits and budgets, and hub-anchored workgroups
  for teams of agents — see [docs/ALP.md](docs/ALP.md) and
  [docs/WORKGROUPS.md](docs/WORKGROUPS.md).
- **Operations.** `alpi doctor`, `alpi audit`, merged logs, an administrative
  audit trail, encrypted backups, one launchd / systemd unit per machine, and
  an official Docker image (`satoshiltd/alpi`) for always-on hosts.

## Quickstart

```bash
uv tool install alpi-agent
alpi setup
alpi
alpi doctor
```

During setup, pick a model, paste the relevant key, and pin a
workspace. For local-only inference, install Ollama first and add it in
`alpi setup -> Model`.

The browser tool downloads the Chromium headless shell (~340 MB) on
first use, cached under your platform's Playwright directory. No manual step.

Common commands:

```bash
alpi                         # interactive TUI
alpi -c                      # resume last session
alpi -p work                 # use named profile
alpi chat --once "status?"   # one-shot stdout turn

alpi setup                   # model, email, MCPs, sandbox, daemon
alpi doctor                  # live health checks
alpi update                  # check PyPI and upgrade alpi-agent
alpi logs                    # merged profile logs
alpi audit-log               # administrative activity, never chat content

alpi profile list
alpi profile create work
alpi profile remove work

alpi daemon start|stop|restart|status    # unified per-machine supervisor
alpi schedule run-once|fire <job-id>     # operational scheduler verbs

alpi peers key
alpi peers list
alpi peers add <id> <pubkey>
alpi peers ping <id>

alpi workgroup list
alpi workgroup create <name> --member <peer-id>
alpi workgroup join <hub-id> <wg_id>
```

For the first-day walkthrough, see [QUICKSTART.md](QUICKSTART.md).

## Core concepts

**Profiles** are the isolation primitive. A profile is one directory,
one identity, one model choice, one memory, one skill set, one schedule
surface, and one ALP peer list. The
default profile lives at `~/.alpi/`; named profiles live under
`~/.alpi/profiles/<name>/`.

**Memory** is plain Markdown. `USER.md` captures facts about the user,
`MEMORY.md` captures environment quirks and durable operational facts,
and `AGENT.md` shapes how alpi should respond. Memory is updated inline
during conversations; there is no post-session reflection loop.

**Skills** are reusable recipes with a strict directory contract. They
can include instructions, scripts, references, assets, secrets, and
state. Mutations go through validation and a security scanner; secrets
live in either `.env` or a per-skill `secrets/` directory.

**Workspace** is the default root for relative paths, not a fake
security wall. File tools and terminal can use absolute paths except
for a sensitive-path denylist. Real workspace-only isolation is the
opt-in OS sandbox.

**ALP** is the Alpi Link Protocol. Each profile owns an Ed25519 keypair.
Peers pin pubkeys out of band and grant explicit capabilities such as
`link.ping`, `link.ask`, and `workgroup.post`. ALP.1 handles same-machine
profiles over Unix sockets. ALP.2 handles inter-machine links with
Noise_XK over TCP plus budgets and rate limits. ALP.3 adds
hub-anchored workgroups.

**Host plane** is separate from ALP. It is the device-facing control
surface used by paired desktop and mobile clients to talk to their own
daemon (`host.*` over a local Unix socket or remote WebSocket). `Connections`
groups one operational identity, its profile access, sessions and usage with
one or more independently revocable device credentials. `Peer TCP listener`
configures ALP peer traffic.

## Security posture

alpi assumes the LLM is powerful, fallible, and sitting next to user
credentials. The guardrails are local and layered:

- safe / caution / dangerous command classification;
- dangerous commands blocked with no config escape hatch;
- caution commands require interactive approval or configured allowlist;
- sensitive-path denylist shared across file and terminal posture;
- SSRF protection on web tools;
- prompt-injection warnings on fetched web/email content;
- OSV malware checks before skill or MCP install;
- optional macOS/Linux OS sandbox per profile;
- `approval.log` and `agent.log` for audit.

See [docs/SECURITY.md](docs/SECURITY.md) for the full model.

## Documentation

- [QUICKSTART.md](QUICKSTART.md) — install, model, workspace, first chat,
  email, profiles, ALP, doctor.
- [docs/PROFILES.md](docs/PROFILES.md) — per-profile identity,
  isolation, state, memory, skills, peers, services, versioning.
- [docs/ALP.md](docs/ALP.md) — wire protocol, identity, signatures,
  transports, methods, errors, workgroups.
- [docs/WORKGROUPS.md](docs/WORKGROUPS.md) — workgroups in practice:
  briefings, task markers, recipes, pipelines with gates, human steering.
- [docs/SECURITY.md](docs/SECURITY.md) — threat model, approval gate,
  sandbox, injection/SSRF/path guards, dependency posture.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — implementation
  reference for contributors and agents reading the codebase.
- [docs/CONFIG.md](docs/CONFIG.md) — every YAML key and when it takes
  effect.
- [docs/SKILLS.md](docs/SKILLS.md) — skill directory contract,
  frontmatter, secrets, scanner, validation.
- [docs/MODELS.md](docs/MODELS.md) — model recommendations for
  tool-heavy agent use.
- [docs/DEPLOYMENTS.md](docs/DEPLOYMENTS.md) — laptop, home server,
  Docker/WSS, multi-profile, multi-device, family/team, enterprise shapes.
- [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) — talk to a profile or
  workgroup from your own code (device token, host-plane WebSocket,
  Node example).
- [docs/OPERATIONS.md](docs/OPERATIONS.md) — services, logs, upgrades,
  backup/restore, monitoring, disaster recovery.
- [docs/ROADMAP.md](docs/ROADMAP.md) — open work and rejected ideas.

## Tests

```bash
uv run --with pytest pytest -q
uv run --with pytest pytest --integration -q
uv run --with pytest pytest --llm
```

## License

alpi is source-available from day one. The agent core is published by
[Satoshi Ltd.](https://www.satoshi-ltd.com/) under the
[Business Source Licence 1.1](LICENSE), with a scheduled conversion to
Apache 2.0 on 2030-04-23, or four years after each version's first
public release, whichever comes first.

Individuals are free. A natural person running alpi on machines they
control may use it in production for any personal, research, or
non-commercial purpose. Legal entities are free for evaluation,
internal development, and experimentation; production deployment by a
company, or offering alpi as a hosted, embedded, or managed service,
needs a Satoshi Ltd. commercial licence.

Commercial enquiries: **info@satoshi-ltd.com**.
