curo1305
cb390ad6af
Add daemon subcommands to README command table (Stage 6 stubs), add Multi-step Planning section, add chat/planner.py to CLAUDE.md architecture table, add TaskPlanner to internal classes inventory, and remove stale test count. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
# Pyra
|
|
|
|
A personal AI assistant CLI with vault-first security. Combines multi-provider AI chat,
|
|
long-term memory, and an extensible plugin system.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
pip install -e . # or: pipx install .
|
|
pyra setup # choose your AI provider
|
|
pyra chat # start talking
|
|
```
|
|
|
|
## Providers
|
|
|
|
**Local (no API key needed):**
|
|
- LM Studio — `http://localhost:1234`
|
|
- Ollama — `http://localhost:11434`
|
|
- llama.cpp server — `http://localhost:8080`
|
|
|
|
**Cloud:**
|
|
- Anthropic (Claude), OpenAI (GPT), Google (Gemini), DeepSeek, Qwen
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `pyra setup` | Run the provider setup wizard |
|
|
| `pyra chat` | Start interactive chat |
|
|
| `pyra memory list` | List memory files |
|
|
| `pyra memory read <name>` | Read a memory file |
|
|
| `pyra memory write <name> <content>` | Write a memory file |
|
|
| `pyra memory append <name> <content>` | Append to a memory file |
|
|
| `pyra plugin list` | List installed and available plugins |
|
|
| `pyra plugin install <name>` | Install a bundled plugin |
|
|
| `pyra plugin enable <name>` | Enable an installed plugin |
|
|
| `pyra plugin disable <name>` | Disable a plugin (keeps it installed) |
|
|
| `pyra plugin setup <name>` | Run a plugin's credential setup wizard |
|
|
| `pyra daemon start` | Start the background daemon *(Stage 6, not yet implemented)* |
|
|
| `pyra daemon stop` | Stop the running daemon *(Stage 6, not yet implemented)* |
|
|
| `pyra daemon status` | Show daemon status *(Stage 6, not yet implemented)* |
|
|
| `pyra daemon restart` | Restart the daemon *(Stage 6, not yet implemented)* |
|
|
| `pyra daemon install` | Register Pyra as a system service *(Stage 6, not yet implemented)* |
|
|
| `pyra daemon uninstall` | Remove the system service *(Stage 6, not yet implemented)* |
|
|
|
|
### In-chat slash commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/help` | Show available commands |
|
|
| `/memory list` | List memory files |
|
|
| `/config` | Open the configuration TUI |
|
|
| `/clear` | Clear conversation history |
|
|
| `/quit` or `/exit` | Exit Pyra |
|
|
|
|
## Security
|
|
|
|
- **API keys live in `~/.pyra/vault/`** — the AI cannot read this directory
|
|
- **`config.yaml` never contains credentials** — only provider ID, model name, and base URL
|
|
- **Prompt injection scanner** — warns on suspicious AI output, logs to `~/.pyra/security.log`
|
|
- **Path sandboxing** — the AI can only reference memory files by name; traversal is blocked
|
|
|
|
## Plugins
|
|
|
|
Pyra has an extensible plugin system. Bundled plugins are shipped with Pyra and installed on
|
|
demand; third-party plugins can be dropped into `~/.pyra/plugins/` directly.
|
|
|
|
Each plugin is a directory containing a `manifest.json` and a `plugin.py`. Plugin credentials
|
|
are stored in the vault under namespaced keys (`plugin:<name>:<key>`) — never in `config.yaml`.
|
|
|
|
```bash
|
|
pyra plugin list # see what's available
|
|
pyra plugin install <name> # copy a bundled plugin to ~/.pyra/plugins/
|
|
pyra plugin setup <name> # enter credentials (stored in vault)
|
|
pyra plugin enable <name> # activate for the next chat session
|
|
```
|
|
|
|
## Multi-step Planning
|
|
|
|
When given a complex task the AI can propose a **multi-step plan** using the built-in
|
|
`plan_and_execute` tool. Pyra prints the plan and asks for approval before executing
|
|
anything. Each step runs as a separate AI call with access to enabled plugin tools; each
|
|
result is verified before moving on to the next step. You can decline the plan or
|
|
interrupt at any point.
|
|
|
|
## Memory
|
|
|
|
Pyra reads your memory files at the start of each session and injects them as context.
|
|
Files are plain Markdown stored in `~/.pyra/memory/`, indexed by a SQLite full-text search
|
|
database (`memory.db`) for fast in-chat lookup.
|
|
|
|
```
|
|
~/.pyra/memory/
|
|
├── user/profile.md ← who you are
|
|
├── context/ ← ongoing projects
|
|
├── knowledge/ ← general notes
|
|
└── memory.db ← FTS5 search index (auto-managed)
|
|
```
|
|
|
|
## `~/.pyra/` Directory
|
|
|
|
```
|
|
~/.pyra/
|
|
├── config.yaml ← provider + model (no secrets)
|
|
├── security.log ← injection event log
|
|
├── memory/ ← AI-readable long-term memory
|
|
│ └── memory.db ← SQLite FTS5 search index
|
|
├── plugins/ ← installed plugins
|
|
│ └── <name>/
|
|
│ ├── manifest.json
|
|
│ └── plugin.py
|
|
├── logs/ ← execution logs
|
|
│ ├── tool_executions.log
|
|
│ └── plugin_errors.log
|
|
└── vault/ ← secure, AI-inaccessible storage
|
|
└── secrets/api_keys.json
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
- **Stage 1** ✅ Core CLI — multi-provider chat, memory, vault security
|
|
- **Stage 2** ✅ Plugin Framework — extensible tools, slash commands, approval gates
|
|
- **Stage 3** ✅ Memory Database — SQLite + FTS5 full-text search index
|
|
- **Stage 4** Vault Encryption — `age`-based encryption of `~/.pyra/vault/secrets/`
|
|
- **Stage 5** Skills System — YAML-defined multi-plugin workflows with event triggers
|
|
- **Stage 6** Daemon + Messaging Bots — always-on asyncio daemon, Matrix/Telegram/Signal bots
|
|
- **Stage 7** Security Audit Sub-agent — automated scanning for injection, CVEs, permission drift
|
|
- **Stage 8** Web UI — optional local interface, embedding-based memory search
|