GET STARTED

Getting started

Getting Verdaca running takes under five minutes if you have Python 3.11 or later and credentials for at least one supported LLM provider. This guide covers installation, a first session, and the configuration file that controls adapter selection.

ADVISORY

Verdaca requires Python 3.11 or later. Virtual environment isolation is strongly recommended; the package pins its adapter dependencies and conflicts with unpinned versions of mem0 or letta in a shared environment.

Installation

Pull the package from PyPI. The install includes the kernel, all bundled ports, and the default Mem0 and Letta memory adapters.

pip install verdaca

First session

The Studio object is the entry point for every Verdaca session. Create one, pass a workflow name, and the kernel assembles the persona panel, routes calls through the configured adapters, and returns a structured result object with the full deliberation trail.

from verdaca import Studio

session = Studio.create()
result  = session.run("[workflow-placeholder]")
print(result.output)

Configuration

Adapter selection and model configuration live in verdaca.yaml at your project root. Override any key with an environment variable prefixed VERDACA_.

# verdaca.yaml
llm:
  provider: anthropic
  model: claude-opus-4-7

memory:
  adapter: mem0
  version: "1.0.11"

IMPORTANT

Your LLM provider credentials must be available as environment variables before the session runs — Verdaca does not store or proxy API keys.

Connect a channel

Beyond a local session, Verdaca can be driven from Microsoft Teams or Slack. Connecting a channel walks through four steps in sequence — each one halts on failure, so you fix one thing at a time — ending with your first message answered back in the channel.

Onboarding — four steps A four-step sequence: environment check, provision a per-user key, policy smoke test, and first message. Each step halts on failure. ONBOARDING — FOUR STEPS Env check Provision key Policy smoke First message EACH STEP HALTS ON FAILURE — FIX ONE THING AT A TIME
  1. Environment check — confirm the required variables are present: the OIDC issuer and audience, the channel signing secret, the LLM proxy URL and key, and the deploy profile.
  2. Provision a key — issue a per-user virtual key with a conservative budget cap; the step prints the key prefix and how to revoke it.
  3. Policy smoke test — build the gateway policy and run the startup health check; it fails closed if a production deployment is missing its virtual-key backing.
  4. First message — send a signed channel message through the auth-first spine and watch the deliberation result return to your thread.
# run the four checks in sequence, halting on the first failure
bash onboard.sh

ADVISORY

Design-partner preview. Channel identity is verified against a local OIDC validator today; connectors for commercial identity providers (Entra, Okta, Auth0) are configuration-level and not yet exercised. Per-tenant budget enforcement and durable nonce storage are wired but not live-exercised in this preview.

Next steps