Metadata-Version: 2.4
Name: aperio-agent
Version: 0.1.2
Summary: Aperio local agent backend, CLI, and web UI
Author: Aperio contributors
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deepagents>=0.6.10
Requires-Dist: fastapi>=0.110
Requires-Dist: langchain>=0.3
Requires-Dist: langchain-openai>=0.2
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: uvicorn>=0.29
Provides-Extra: web
Requires-Dist: uvicorn>=0.29; extra == "web"
Provides-Extra: mcp
Requires-Dist: ddgs>=9.0; extra == "mcp"
Requires-Dist: fastmcp>=2.0; extra == "mcp"
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "mcp"
Provides-Extra: sandbox
Requires-Dist: docker>=7.0; extra == "sandbox"
Provides-Extra: integrations
Requires-Dist: lark-oapi<2.0.0,>=1.5.0; extra == "integrations"
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# Aperio Agent

Aperio Agent is a local Python agent package with:

- terminal chat via `aperio`
- one-shot execution via `aperio run ...`
- local Web UI via `aperio serve`
- backend APIs used by the Web UI

The default CLI behavior matches tools like Codex or Claude Code: run `aperio` and keep chatting in the terminal.

## Install From GitHub

```powershell
pip install git+https://github.com/sinxy-sai/aperio.git
```

For local development:

```powershell
pip install -e .
```

## Configure

```powershell
aperio init
```

Edit `~/.aperio/.env`:

```env
DEEPSEEK_API_KEY=your-key
OPENROUTER_API_KEY=
DASHSCOPE_API_KEY=
MOONSHOT_API_KEY=
APERIO_ENGINE=deepagents
APERIO_PROVIDER=
APERIO_MODEL=
APERIO_FALLBACK_MODEL=
APERIO_BASE_URL=
APERIO_MODEL_CALL_LIMIT=100
APERIO_TOOL_CALL_LIMIT=160
APERIO_MODEL_MAX_RETRIES=3
APERIO_TOOL_MAX_RETRIES=2
APERIO_INSTALL_PROJECT_DEPS=0
APERIO_SCAN_SANDBOX=auto
APERIO_ENABLE_MCP=0
APERIO_KNOWLEDGE_ENABLED=1
APERIO_KNOWLEDGE_DB=
APERIO_SAFE_EXECUTION_ENABLED=1
APERIO_EXTENSIONS_ENABLED=1
AMAP_API_KEY=
FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_ENCRYPT_KEY=
FEISHU_VERIFICATION_TOKEN=
```

`aperio init` also creates `~/.aperio/config.json`. This file follows the nanobot-style split between runtime defaults, model providers, and software channels:

```json
{
  "agents": {
    "defaults": {
      "model": "deepseek-v4-flash",
      "provider": "deepseek",
      "fallbackModel": ""
    }
  },
  "providers": {
    "deepseek": {
      "apiKey": "${DEEPSEEK_API_KEY}",
      "apiBase": "https://api.deepseek.com"
    },
    "openrouter": {
      "apiKey": "${OPENROUTER_API_KEY}",
      "apiBase": "https://openrouter.ai/api/v1"
    },
    "dashscope": {
      "apiKey": "${DASHSCOPE_API_KEY}",
      "apiBase": "https://dashscope.aliyuncs.com/compatible-mode/v1"
    },
    "custom": {
      "apiKey": "",
      "apiBase": ""
    }
  },
  "channels": {
    "feishu": {
      "enabled": false,
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "encryptKey": "${FEISHU_ENCRYPT_KEY}",
      "verificationToken": "${FEISHU_VERIFICATION_TOKEN}",
      "allowFrom": [],
      "groupPolicy": "mention",
      "streaming": true,
      "domain": "feishu",
      "maxMediaBytes": 26214400
    }
  }
}
```

Use `provider: "auto"` to let Aperio infer the provider from the model name and configured keys. Use `provider: "custom"` with `providers.custom.apiBase` for local OpenAI-compatible servers such as vLLM, Ollama, LM Studio, or other gateways. `APERIO_MODEL` and `APERIO_BASE_URL` still work as legacy overrides; leave them empty when you want `config.json` to control provider routing.

## CLI

Start interactive chat:

```powershell
aperio
```

The interactive CLI shows a short welcome panel with the active workspace, model, approval mode, and packaged skills. With `prompt-toolkit` installed, typing `/` opens command completion and typing `$` opens skill completion. Keyboard navigation with arrow keys, Tab, and Enter works everywhere. If you want clickable completion menus and your terminal supports mouse events, set `APERIO_CLI_MOUSE=1`; this may make terminal scrollback follow the prompt in some shells.

Useful interactive commands:

```text
/help       Show commands
/skills     List packaged skills
/doctor     Check environment and config
/runs       List recent runs
/artifacts  List artifacts for the last run
/channels   Show software channel config status
/commands   List project/user extension commands
/knowledge  Sync or search local project knowledge
/safe       Run a conservative read-only allowlisted command
/exit       Quit
```

Run one prompt:

```powershell
aperio run "为智慧校园导航助手写一份 PRD 并评审"
```

Start Web UI:

```powershell
aperio serve --host 127.0.0.1 --port 8088
```

Start Feishu/Lark gateway:

```powershell
pip install "aperio-agent[integrations]"
aperio gateway feishu
```

Check config:

```powershell
aperio doctor
```

## Notes

The default engine is `deepagents`, which runs a package-native DeepAgents router with PRD, code-health, and general-purpose subagents. Set `APERIO_ENGINE=lite` for the simpler fallback engine.

Code-health mode now packages the migrated demo skills and deterministic `code-health-toolkit`. By default it tries the packaged Docker sandbox first and falls back to host scanning if Docker is unavailable. Set `APERIO_SCAN_SANDBOX=host` to force host-only scanning, or `APERIO_SCAN_SANDBOX=docker` to require Docker.

DeepAgents runs on a routed workspace backend. Inputs, outputs, local policy files, packaged skills, per-agent skill views, memory, and temp state are separated by virtual paths, and each subagent receives only its assigned read-only skill source.

Local project knowledge is indexed with SQLite FTS, not a heavy vector database. Aperio indexes README files, `docs/**/*.md`, and selected project notes into `~/.aperio/knowledge.sqlite3` by default, then writes matching snippets for each run to `/inputs/project_context.md`. Use `/knowledge sync`, `/knowledge search <query>`, and `/knowledge path` in the CLI for manual inspection.

A conservative safe-execution wrapper is available for single-user local workflows. It rejects shell metacharacters, keeps the working directory inside `APERIO_PROJECT_ROOT`, enforces timeouts, and only allows a small read-only command set such as `git status`, `git diff`, `git log`, `rg`, and `python -m py_compile`/`compileall`. Use `/safe <command>` in the CLI to test the policy.

Project and user extensions are enabled by default. Put project commands in `.aperio/commands/*.md` and user commands in `~/.aperio/commands/*.md`; the filename registers the slash command, for example `.aperio/commands/review.md` becomes `/review`. Command files are Markdown prompt templates, not executable scripts. Optional frontmatter supports `name`, `description`, `approval_mode`, and `timeout_seconds`; use `{{args}}` or `$ARGUMENTS` where command arguments should be inserted.

Project skills live under `.aperio/skills/<skill>/SKILL.md`; user skills live under `~/.aperio/skills/<skill>/SKILL.md`. At runtime they are copied read-only into `/skills/project/...` and `/skills/user/...`, listed by `/skills`, and attached to the general-purpose agent. Set `APERIO_EXTENSIONS_ENABLED=0` to disable local extensions.

Optional MCP tools are disabled by default. Install `aperio-agent[mcp]`, set `APERIO_ENABLE_MCP=1`, and optionally set `AMAP_API_KEY` to enable public web search and Amap tools for agent workflows.

Software channel configuration is now represented in `~/.aperio/config.json`. Feishu/Lark uses `channels.feishu` with App ID, App Secret, Encrypt Key, Verification Token, `allowFrom`, `groupPolicy`, `streaming`, and `domain`. Install optional dependencies with `pip install "aperio-agent[integrations]"`, then run `aperio gateway feishu`.

Feishu setup notes:

- Enable bot capability and event subscription for `im.message.receive_v1`.
- Add required app credentials to `.env` or directly to `config.json`.
- Set `channels.feishu.enabled` to `true`.
- Set `allowFrom` to specific sender open IDs, or `["*"]` for local testing.
- `groupPolicy: "mention"` responds only when the bot is mentioned in groups; `open` responds to all group messages.
- Images, files, audio, and video are downloaded from Feishu and passed to Aperio as run uploads. `maxMediaBytes` limits each downloaded file.
- `streaming: true` uses Feishu CardKit to show progress events while the agent runs. The app needs CardKit card write permission such as `cardkit:card:write`; if CardKit is unavailable, Aperio falls back to sending the final text answer.

DeepAgents runtime guards are enabled by default: model calls are capped, tool calls are capped, model calls retry before failing, and read/search tools retry transient failures. Use `APERIO_FALLBACK_MODEL` to enable model fallback.
