OVERVIEW

Verdaca docs

DESIGN PREVIEW

This page describes the planned verdaca Python package. That package is not built yet, so the code samples on this page will not run. For what runs today, see the real Getting started page and the recorded receipts in docs/receipts/.

This documentation covers Verdaca's deliberation platform — how it is architected, how to run your first session, and how to extend it with custom agents and adapter substrates. It is written for practitioners: consultants, engineers, and technical leads who need to understand the system well enough to configure and deploy it.

ADVISORY

Start with the Conceptual model before touching configuration — the two-axis pluggability diagram is the key to understanding every other section.

What's in these docs

Overview (this page) — What Verdaca is and how these docs are organized.
Getting started — Installation, first session, and the four-step channel onboarding flow.
Channels & onboarding — Drive Verdaca from Microsoft Teams or Slack through one gateway, behind an auth-first spine. See Getting started for the flow and Conceptual model for the front door.
Conceptual model — Two-axis architecture, the auth-first front door, the deliberation loop, and kernel responsibilities.
Agent catalog — Available personas, capabilities, and how to load them.
Build your own agent — Define a custom persona and bind it to a session.
Workflow recipes — Pre-built deliberation patterns ready to run or adapt.
Output review — Scoring and custom rubrics (design preview).

Quick start

Three lines to run a deliberation session. Install the package, initialize a Studio, and pass a workflow name.

# Install Verdaca
pip install verdaca

# Initialise a session
from verdaca import Studio
session = Studio.create()
result  = session.run("[workflow-placeholder]")

Architecture at a glance

Verdaca is organized on two independent axes: swap the agent personas horizontally, swap the substrate adapters vertically. Neither axis requires changing the other.

Every request reaches the kernel through one channel-neutral gateway, after an auth-first spine of four checks — signature, identity, replay, and budget. See the front door in the conceptual model.