<div class="docs-content" data-render>
# Devii internals

Admin-only technical reference for the **Devii** module (`devplacepy/services/devii/`), the
implementation companion to the functional [Devii Assistant](/docs/devii.html) page members see. It
covers 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`) configured 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-and-channel; shared stores
  session/        DeviiSession (core.py) + prompts: 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, one module per
                  domain), dispatcher, and *_actions for each local handler
  agentic/        ReAct loop, AgenticController, LessonStore, state, compaction
  tasks/          TaskStore, Scheduler, TaskController (autonomous tasks)
  behavior/ virtual_tools/ customization/ notification/ email/ container/ rsearch/
  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>