|
<div class="docs-content" data-render>
|
|
# Devii internals
|
|
|
|
Admin-only technical reference for the **Devii** module (`devplacepy/services/devii/`). This is the
|
|
implementation companion to the functional [Devii Assistant](/docs/devii.html) page that members
|
|
see. It documents the module's structure, scopes, data model, security, and operations.
|
|
|
|
> Audience: administrators and maintainers. These pages are hidden from members and guests, in the
|
|
> sidebar, the search index, and the documentation export.
|
|
|
|
## What Devii is
|
|
|
|
Devii is an in-platform agentic assistant exposed as a WebSocket terminal at `/devii/ws` and as a
|
|
`devii` console script. It runs a ReAct loop (plan, act, verify, reflect) over a declarative tool
|
|
catalog. A signed-in user's Devii operates that user's own DevPlace account; guests get a sandbox.
|
|
It runs as a configurable background service (`DeviiService`) on `/admin/services`.
|
|
|
|
## Module map
|
|
|
|
```
|
|
devplacepy/services/devii/
|
|
service.py DeviiService (BaseService): config fields, limits, metrics, the hub
|
|
hub.py DeviiHub: one DeviiSession per owner; shared stores
|
|
session.py DeviiSession: websocket(s), turns, persistence, broadcast
|
|
agent.py Agent: the ReAct driver + system prompt + lesson recall
|
|
registry.py CATALOG: the full tool catalog (union of *_ACTIONS)
|
|
config.py Settings dataclass, ConfigField keys, build_settings()
|
|
llm.py LLMClient (OpenAI-compatible chat)
|
|
http_client.py PlatformClient (operates the account over the platform API)
|
|
store.py ConversationStore, UsageLedger, TurnAudit (main DB)
|
|
cli.py the `devii` console script
|
|
actions/ spec (Action/Param/Catalog), catalog (platform endpoints), dispatcher,
|
|
and *_actions for each local handler
|
|
agentic/ ReAct loop, AgenticController, LessonStore, state, compaction
|
|
tasks/ TaskStore, Scheduler, TaskController (autonomous tasks)
|
|
chunks/ cost/ fetch/ docs/ avatar/ client/ local tool controllers
|
|
```
|
|
|
|
## Request lifecycle
|
|
|
|
1. The browser terminal (or the CLI) sends `{"type":"input","text":...}` over `/devii/ws`.
|
|
2. The router resolves the owner `(owner_kind, owner_id)` and the per-owner `DeviiSession` from the
|
|
`DeviiHub`, enforces the 24h spend cap, then `session.spawn_turn(text)`.
|
|
3. The `Agent` runs the ReAct loop: it must `plan()` first, then calls tools. The `Dispatcher`
|
|
routes each tool to its handler (platform HTTP, or a local controller).
|
|
4. Trace frames stream live to every connected socket; the final reply is broadcast.
|
|
5. After the turn, the session persists the conversation, appends a usage-ledger row, and writes an
|
|
audit row.
|
|
|
|
## The subpages
|
|
|
|
- [Architecture and sessions](/docs/devii-architecture.html) - hub, sessions, websocket, persistence, workers.
|
|
- [Tools and scopes](/docs/devii-tools.html) - the catalog, handler categories, and auth scopes.
|
|
- [Data and persistence](/docs/devii-data.html) - the SQLite tables and the owner-scoping model.
|
|
- [Security and limits](/docs/devii-security.html) - isolation, spend caps, eval toggle, audit.
|
|
- [Configuration and CLI](/docs/devii-config.html) - service config fields, env vars, the `devii` CLI.
|
|
</div>
|