Metadata-Version: 2.4
Name: stoa-agent
Version: 0.14.6
Summary: STOA Agent — a chamber of six personas + one dispatcher. Local-first, bring-your-own-key, no subscription, no lock-in. See ATTRIBUTION.md for upstream lineage.
Author-email: STOA <hi@stoax.xyz>
License: MIT
Project-URL: Homepage, https://stoax.xyz
Project-URL: Documentation, https://stoax.xyz/docs
Project-URL: Repository, https://github.com/STOAGENT/stoa-agent
Project-URL: Issues, https://github.com/STOAGENT/stoa-agent/issues
Project-URL: Source, https://github.com/STOAGENT/stoa-agent
Keywords: ai,agent,llm,council,monad,erc-8004,on-chain,cli,stoa
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Communications :: Chat
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==2.24.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: fire==0.7.1
Requires-Dist: httpx[socks]==0.28.1
Requires-Dist: rich==14.3.3
Requires-Dist: tenacity==9.1.4
Requires-Dist: pyyaml==6.0.3
Requires-Dist: ruamel.yaml==0.18.17
Requires-Dist: requests==2.33.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: pydantic==2.13.4
Requires-Dist: prompt_toolkit==3.0.52
Requires-Dist: croniter==6.0.0
Requires-Dist: PyJWT[crypto]==2.12.1
Requires-Dist: tzdata==2025.3; sys_platform == "win32"
Requires-Dist: psutil==7.2.2
Requires-Dist: eth-account==0.13.7
Requires-Dist: defusedxml==0.7.1
Provides-Extra: anthropic
Requires-Dist: anthropic==0.87.0; extra == "anthropic"
Provides-Extra: exa
Requires-Dist: exa-py==2.10.2; extra == "exa"
Provides-Extra: firecrawl
Requires-Dist: firecrawl-py==4.17.0; extra == "firecrawl"
Provides-Extra: parallel-web
Requires-Dist: parallel-web==0.4.2; extra == "parallel-web"
Provides-Extra: fal
Requires-Dist: fal-client==0.13.1; extra == "fal"
Provides-Extra: edge-tts
Requires-Dist: edge-tts==7.2.7; extra == "edge-tts"
Provides-Extra: modal
Requires-Dist: modal==1.3.4; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona==0.155.0; extra == "daytona"
Provides-Extra: vercel
Requires-Dist: vercel==0.5.7; extra == "vercel"
Provides-Extra: hindsight
Requires-Dist: hindsight-client==0.6.1; extra == "hindsight"
Provides-Extra: dev
Requires-Dist: debugpy==1.8.20; extra == "dev"
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: pytest-timeout==2.4.0; extra == "dev"
Requires-Dist: mcp==1.26.0; extra == "dev"
Requires-Dist: ty==0.0.21; extra == "dev"
Requires-Dist: ruff==0.15.10; extra == "dev"
Provides-Extra: messaging
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "messaging"
Requires-Dist: discord.py[voice]==2.7.1; extra == "messaging"
Requires-Dist: aiohttp==3.13.3; extra == "messaging"
Requires-Dist: brotlicffi==1.2.0.1; extra == "messaging"
Requires-Dist: slack-bolt==1.27.0; extra == "messaging"
Requires-Dist: slack-sdk==3.40.1; extra == "messaging"
Requires-Dist: qrcode==7.4.2; extra == "messaging"
Provides-Extra: cron
Provides-Extra: slack
Requires-Dist: slack-bolt==1.27.0; extra == "slack"
Requires-Dist: slack-sdk==3.40.1; extra == "slack"
Requires-Dist: aiohttp==3.13.3; extra == "slack"
Provides-Extra: matrix
Requires-Dist: mautrix[encryption]==0.21.0; extra == "matrix"
Requires-Dist: Markdown==3.10.2; extra == "matrix"
Requires-Dist: aiosqlite==0.22.1; extra == "matrix"
Requires-Dist: asyncpg==0.31.0; extra == "matrix"
Requires-Dist: aiohttp-socks==0.11.0; extra == "matrix"
Provides-Extra: cli
Requires-Dist: simple-term-menu==1.6.6; extra == "cli"
Provides-Extra: tts-premium
Requires-Dist: elevenlabs==1.59.0; extra == "tts-premium"
Provides-Extra: voice
Requires-Dist: faster-whisper==1.2.1; extra == "voice"
Requires-Dist: sounddevice==0.5.5; extra == "voice"
Requires-Dist: numpy==2.4.3; extra == "voice"
Provides-Extra: pty
Requires-Dist: ptyprocess==0.7.0; sys_platform != "win32" and extra == "pty"
Requires-Dist: pywinpty==2.0.15; sys_platform == "win32" and extra == "pty"
Provides-Extra: honcho
Requires-Dist: honcho-ai==2.0.1; extra == "honcho"
Provides-Extra: mcp
Requires-Dist: mcp==1.26.0; extra == "mcp"
Provides-Extra: homeassistant
Requires-Dist: aiohttp==3.13.3; extra == "homeassistant"
Provides-Extra: sms
Requires-Dist: aiohttp==3.13.3; extra == "sms"
Provides-Extra: computer-use
Requires-Dist: mcp==1.26.0; extra == "computer-use"
Provides-Extra: acp
Requires-Dist: agent-client-protocol==0.9.0; extra == "acp"
Provides-Extra: bedrock
Requires-Dist: boto3==1.42.89; extra == "bedrock"
Provides-Extra: azure-identity
Requires-Dist: azure-identity==1.25.3; extra == "azure-identity"
Provides-Extra: termux
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "termux"
Requires-Dist: stoa-agent[cron]; extra == "termux"
Requires-Dist: stoa-agent[cli]; extra == "termux"
Requires-Dist: stoa-agent[pty]; extra == "termux"
Requires-Dist: stoa-agent[mcp]; extra == "termux"
Requires-Dist: stoa-agent[honcho]; extra == "termux"
Requires-Dist: stoa-agent[acp]; extra == "termux"
Provides-Extra: termux-all
Requires-Dist: stoa-agent[termux]; extra == "termux-all"
Requires-Dist: stoa-agent[google]; extra == "termux-all"
Requires-Dist: stoa-agent[homeassistant]; extra == "termux-all"
Requires-Dist: stoa-agent[sms]; extra == "termux-all"
Requires-Dist: stoa-agent[web]; extra == "termux-all"
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream==0.24.3; extra == "dingtalk"
Requires-Dist: alibabacloud-dingtalk==2.2.42; extra == "dingtalk"
Requires-Dist: qrcode==7.4.2; extra == "dingtalk"
Provides-Extra: feishu
Requires-Dist: lark-oapi==1.5.3; extra == "feishu"
Requires-Dist: qrcode==7.4.2; extra == "feishu"
Provides-Extra: google
Requires-Dist: google-api-python-client==2.194.0; extra == "google"
Requires-Dist: google-auth-oauthlib==1.3.1; extra == "google"
Requires-Dist: google-auth-httplib2==0.3.1; extra == "google"
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api==1.2.4; extra == "youtube"
Provides-Extra: web
Requires-Dist: fastapi==0.133.1; extra == "web"
Requires-Dist: uvicorn[standard]==0.41.0; extra == "web"
Provides-Extra: all
Requires-Dist: stoa-agent[cron]; extra == "all"
Requires-Dist: stoa-agent[cli]; extra == "all"
Requires-Dist: stoa-agent[dev]; extra == "all"
Requires-Dist: stoa-agent[pty]; extra == "all"
Requires-Dist: stoa-agent[mcp]; extra == "all"
Requires-Dist: stoa-agent[homeassistant]; extra == "all"
Requires-Dist: stoa-agent[sms]; extra == "all"
Requires-Dist: stoa-agent[acp]; extra == "all"
Requires-Dist: stoa-agent[google]; extra == "all"
Requires-Dist: stoa-agent[web]; extra == "all"
Requires-Dist: stoa-agent[youtube]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="assets/banner.svg" alt="STOA Agent — six personas, one chamber, on your machine" width="100%">
</p>

# STOA Agent ⁂

**Six personas in one chamber, running on your machine.**
Council-mode debate · Bring-your-own-key · No subscription, no lock-in.

> STOA is a Socratic chamber: six named personas — each with its own role,
> system prompt, and reasoning style — debate every non-trivial task in
> parallel, then a seventh dispatcher composes a verdict. STOA itself is
> free and open-source forever; you bind your own LLM API key (we
> recommend DeepSeek's free tier — 2-minute signup, no card) and STOA
> never sees, brokers, or proxies your key. Want one provider per persona
> (e.g. Sokrates → Anthropic, Veritas → Google, Drax → xAI)? Bind a
> different key per seat in `~/.stoa/cli-config.yaml`.

This is a fork of [NousResearch / hermes-agent](https://github.com/NousResearch/hermes-agent) v0.14.0 (MIT). The runtime, gateway, sandboxes, memory store, skill format, and provider plugin layer are inherited from upstream — see [ATTRIBUTION.md](ATTRIBUTION.md) for the full lineage. What STOA adds on top is the chamber: persona orchestration, an optional on-chain attestation preview, and a 6-agent skill-publication audit gate.

---

## Install

**macOS · Linux · WSL2 · Termux**
```sh
curl -fsSL https://stoax.xyz/install.sh | sh
```

**Windows · PowerShell**
```powershell
iex (irm https://stoax.xyz/install.ps1)
```

**PyPI**
```sh
pip install stoa-agent
stoa setup
```

**Homebrew**
```sh
brew tap stoagent/stoa
brew install stoa-agent
```

**Direct from source**
```sh
git clone https://github.com/STOAGENT/stoa-agent
cd stoa-agent
uv venv && uv pip install -e .
stoa setup
```

---

## What STOA adds

### 1. Council mode — six personas, one chamber

Each persona has its own system prompt, reasoning style, and tool affinity. They run in parallel against the same task, and a seventh dispatcher composes a verdict by surfacing agreement and dissent rather than collapsing the answer to a single voice.

```sh
stoa /council "audit this contract: $(cat MyToken.sol)"
# → 6 personas in parallel
# → Sokrates / Mira / Veritas / Drax / Lyra / Echo each respond
# → Verdict + per-persona dissent + response hash (local)
```

| Persona | Role |
|---|---|
| **Sokrates** | the question-maker — surfaces hidden assumptions |
| **Mira** | the builder — produces concrete artifacts |
| **Veritas** | the auditor — looks for incorrectness |
| **Drax** | the red team — looks for failure modes |
| **Lyra** | the designer — looks for clarity and form |
| **Echo** | the operator — looks for ops + lifecycle risk |
| **Hermes** | the dispatcher (the seventh) — composes the verdict |

### 2. Provider model — bring-your-own-key

STOA never bundles, brokers, or proxies anyone else's API key. There is no STOA cloud and no "free credits from us." Instead the first-run wizard walks you through the cheapest viable setup:

1. Go to https://platform.deepseek.com/api_keys (free signup, no card).
2. Create a key. DeepSeek's free tier covers typical solo use; a heavy session is a few cents.
3. Paste the key. STOA writes it to `~/.stoa/cli-config.yaml` on your machine and never sends it anywhere else.

Result: the chamber works end-to-end on your own DeepSeek free tier, with you in full control of the spend. Want one provider per persona (e.g. Sokrates → Anthropic, Veritas → Google, Drax → xAI)? Bind a different key per seat:

```yaml
# ~/.stoa/cli-config.yaml — produced by `stoa setup`, fully editable
personas:
  sokrates: { provider: deepseek, model: deepseek-reasoner }   # default
  mira:     { provider: deepseek, model: deepseek-chat }       # default
  # …or override per seat with a different key + provider:
  veritas:  { provider: anthropic, model: claude-opus-4-7, api_mode: anthropic }
```

> The persona names (Sokrates / Mira / Veritas / Drax / Lyra / Echo / Hermes) are role identifiers and are decoupled from any single model vendor — see `stoa /persona list` for the live binding on your machine.

### 3. Council-audited skill publication

The hardest problem in agent skill ecosystems is supply-chain trust. STOA's answer: **no skill publishes without a 6-persona audit + 5-of-6 quorum + a local audit hash**. Security, performance, prompt-injection, license, structure, attribution — six different lenses on every new skill.

```sh
stoa skill publish ./my-skill
# → 6 personas audit it independently
# → 5-of-6 quorum required
# → audit hash written locally; on-chain stamp behind --attest (preview)
```

### 4. On-chain attestation — preview

`stoa --attest` is currently a **preview feature** behind a flag.

When enabled, every council verdict optionally writes its response hash to **AuditAttestationV2** on Monad mainnet, so months later anyone can verify a STOA agent ran exactly the action it claims it ran. The hashing + persistence are wired; the `eth_sendRawTransaction` submission and verifier client are under hardening for the next release. Until then, expect `--attest` to compute the hash, queue the request, and log `attestation_preview: pending_submit`.

If you have no need for on-chain verifiability, you can ignore `--attest` entirely — the chamber, the verdict, and the skill audit gate all work locally without it.

---

## Commands

| Command | What it does |
|---|---|
| `stoa` | Splash dashboard + interactive REPL |
| `stoa chat` | Direct chat mode |
| `stoa setup` | First-run wizard (writes `~/.stoa/cli-config.yaml`) |
| `stoa gateway` | Run the multi-platform daemon (Telegram, Discord, Slack, etc.) |
| `stoa /council "<task>"` | Six personas in parallel + verdict |
| `stoa /persona <name>` | Switch single-persona mode |
| `stoa /persona list` | Show the live persona ↔ provider binding |
| `stoa /verdict` | Show the last council verdict |
| `stoa /attest` | **preview** — stamp the last verdict on-chain |
| `stoa skill publish` | Runs the 6-persona audit gate before publishing |
| `stoa migrate xai` | Rewrite config to replace retired xAI models with current ones |

---

## Skills shipped under `skills/stoa/`

- `council-verdict` — orchestrate a 6-persona call from inside a skill
- `monad-attestation` — write a hash to AuditAttestationV2 (preview)
- `solidity-audit-pipeline` — Slither + Mythril + Echidna + manual review
- `erc8004-reputation` — read or write agent reputation events
- `stoa-skill-publish` — the publication audit gate itself
- `monad-mev-watchdog` — passive on-chain monitor
- `solana-anchor-audit` — Anchor-program review

---

## Security posture

STOA inherits the same primitive set as its upstream lineage: shell execution, browser automation, plugin marketplace, optional wallet binding. These are powerful tools and require operator literacy — STOA targets the same operator profile as Cursor, Claude Code, and Aider.

- **Default-OFF gates** (DB encryption, PII/IP redaction, skill ed25519 signature, mandatory sandbox) are being flipped to default-ON via a `STOA_SECURITY_PRESET` selector in the next release.
- **Bug bounty + coordinated disclosure**: see [SECURITY.md](SECURITY.md). Do **not** open public issues for security reports.
- **Audit reports** are not published to the master tree — coordinated disclosure first. We ship fixes, then summary write-ups.

---

## License

MIT for the STOA Agent codebase. See [LICENSE](LICENSE).
The upstream MIT license is preserved verbatim; this fork adds the attribution recorded in [ATTRIBUTION.md](ATTRIBUTION.md).

**Bundled assets carry their own licenses:**

- `web/public/fonts-terminal/JetBrainsMono-*.woff2` — SIL Open Font
  License 1.1, see [`web/public/fonts-terminal/OFL.txt`](web/public/fonts-terminal/OFL.txt).
- `optional-skills/productivity/powerpoint/` — **Proprietary, Anthropic**.
  Opt-in only (set `STOA_ENABLE_OPTIONAL_SKILLS=1` to discover it).
  Use is governed by your separate agreement with Anthropic; the file
  `optional-skills/productivity/powerpoint/LICENSE.txt` ships the full
  terms. NOT covered by MIT.
- `optional-skills/mlops/inference/obliteratus/` — AGPL-3.0. Opt-in via
  `STOA_ENABLE_REDTEAM=1`. AGPL §13 obligations apply if you ship a
  network-accessible service that incorporates this skill.

## Links

- Docs · https://stoax.xyz/cli
- Chamber · https://stoax.xyz
- PyPI · https://pypi.org/project/stoa-agent/
- Source · https://github.com/STOAGENT/stoa-agent
- Upstream lineage · [ATTRIBUTION.md](ATTRIBUTION.md)
