Architecture

enoki is a Bolt for Python Slack app wrapping a Pydantic AI agent, with inference on Gemini via Vertex AI. This page walks the path a message takes and where each identity and safeguard sits.

The pieces

• Slack listeners (Bolt) — handle @mention, DM, and assistant-thread events. Each handler sets a status, loads history, runs the agent, streams the reply, and stores history.
• The agent (Pydantic AI) — a typed-tool agent. The model is built at runtime, not import time, so no provider client is created until first use.
• Inference (Vertex AI) — a GoogleModel on a Vertex GoogleProvider, authenticated by enoki’s own Application Default Credentials. Configured by GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and VERTEX_MODEL.
• GCP tools — one module per service (BigQuery, Storage, Compute, Pub/Sub, Logging, Resource Manager / IAM, Billing). Each builds its client with the requesting user’s OAuth credentials.
• OAuth + token store — a Flask blueprint runs the Google consent flow and persists a Fernet-encrypted refresh token per user.
• Stores — conversation context (keyed by channel + thread, 24h TTL), a pending-approval store for paused writes, an event-idempotency guard, and the audit log. These are in-memory for a single instance, or Firestore-backed (ENOKI_STORE=firestore) so a scaled deployment can resolve an approval on any instance. See State & Storage.
• Audit log — a structured, append-only record of every GCP tool call.

Request flow

1. A user @mentions enoki or DMs it. The listener sets a thinking status and loads the thread’s history.
2. enoki loads the user’s Google credentials, if connected, into the agent’s dependencies.
3. The agent runs on Vertex. The model may call read tools directly, or propose write tools.
4. Read → the tool runs under the user’s identity and the reply streams back.
5. Write → the run pauses; enoki posts per-call Approve/Deny buttons and stashes the run.
6. On approval, enoki resumes the run, executes the approved calls under freshly loaded user credentials, and posts the result.
7. Every GCP call is written to the audit log.

Two run modes

• Socket Mode (app.py) — single workspace, uses bot + app tokens. Simplest for development. The Google OAuth web routes are not served here.
• OAuth / HTTP mode (app_oauth.py) — a Flask server carrying Slack OAuth and the Google account-linking routes. This is the mode that supports per-user Google connect and multi-workspace install.

Where identity lives

Inference auth (Vertex ADC) is the runtime’s own service account — in production, the service account attached to the host. Data-access auth is per-user and refreshed at the point of use: the stored refresh token mints a fresh access token on each call, so nothing stale is reused, and gRPC and HTTP clients alike authenticate cleanly. The two identities never cross.

Next: State & Storage — what enoki keeps, and for how long.