urika 0.10.0

Multi-agent scientific analysis platform

Getting Started · Agent System · Models & Privacy · Notifications · CLI Reference · Interactive TUI · Dashboard

---

Early Development — Urika is under active development. Expect frequent updates, bug fixes, and new features. Check back regularly or run urika setup to see if a new version is available. Bug reports and feedback welcome at GitHub Issues.

Urika uses multiple AI agents to autonomously explore analytical approaches for your dataset and research question. It creates experiments, tries different methods, evaluates results, searches relevant literature, and builds custom tools when needed. Everything is documented automatically — experiment labbooks, project-level reports, key findings, and slide presentations you can view in any browser. Each experiment's methods, metrics, and observations are tracked in structured records that agents use to plan the next step.

As of v0.7.0, Urika supports the Claude Agent SDK (Anthropic), OpenAI Agents SDK, and Google Agent Development Kit (ADK) — see the Supported providers table below. Local models via Ollama / LM Studio / vLLM also work through the Anthropic adapter's private-endpoint mode. A PI adapter is planned for a future release.

Runs on Linux, macOS, and Windows 11. For local/private model setups (Ollama, vLLM, LiteLLM), see Models & Privacy.

Four interfaces

Urika has four first-class interfaces — TUI (default), classic REPL, CLI, and dashboard. They share the same project state on disk, so anything you do in one shows up in the others.

Interface	Command	When to use
TUI	urika	Exploratory orchestrator chat, watching a run with rich activity feedback, slash commands with tab completion
REPL	urika --classic	Plain prompt_toolkit fallback with the same slash commands — for terminals where the TUI misbehaves, SSH, or screen readers
CLI	urika <command>	Scripting, batch jobs, CI, remote sessions, --json output for tooling
Dashboard	urika dashboard [project]	Monitoring long runs, sharing results in a browser, settings forms, sessions tab

See Interfaces Overview for a full task-by-task cheat sheet across all four.

Supported providers

As of v0.7.0, Urika ships adapters for three model providers. Pick one for the whole project, or mix-and-match per agent role.

Provider	SDK	Reasoning default	Execution default	Auth
Anthropic	claude-agent-sdk	claude-opus-4-7	claude-sonnet-4-5	API key OR subscription
OpenAI	openai-agents	gpt-5.4	gpt-5.4-mini	API key
Google	google-adk	gemini-3.5-flash	gemini-3.5-flash	API key

Set model strings per agent in urika.toml -- Urika routes each call to the right adapter based on the model prefix (claude-* → Anthropic, gpt-* / o3-* / o4-* / o5-* → OpenAI, gemini-* → Google). Mix providers across agent roles for cost or quality trade-offs (e.g. Opus for the planner, GPT-5.4-mini for the task agent, Gemini Flash for the report). See Provider Guide for the full decision rubric and auth setup per provider.

Why Google has no Pro/Flash split. gemini-3.1-pro-preview requires a billing-enabled Google AI account (free-tier rate limit = 0), so v0.7.0 recommends gemini-3.5-flash for both reasoning and execution roles to keep onboarding friction-free for free-tier users. Users with billing can override per-agent to Pro and cost reporting works correctly (urika.agents.pricing.PRICES carries the row).

Installation

Prerequisites

1. Python 3.11+ (required) — see Getting Started → Step 1 for per-OS install commands.
2. Provider API key (required) — at least one of Anthropic, OpenAI, or Google (set up in step 3 below). For Anthropic, api_key auth mode (the default) requires an ANTHROPIC_API_KEY; subscription auth is also supported as an opt-in via urika config anthropic --mode subscription (since June 15 2026, Agent SDK workloads on Pro/Max draw from a separate monthly Agent credit pool). Default remains API-key auth across all three providers. See Supported providers for the full matrix.
3. Claude Code CLI on PATH (recommended, not required) — npm install -g @anthropic-ai/claude-code. The Claude Agent SDK ships its own bundled claude binary, so you can skip this and Urika will fall back to the bundled one. Install your own to use claude-opus-4-7 or any future Anthropic model — the bundled binary lags. See Getting Started → Claude Code CLI for the why.

Install Urika

From PyPI (v0.7.0 shipped 2026-06-08):

python3 -m venv ~/.venvs/urika
source ~/.venvs/urika/bin/activate    # Windows PowerShell: ~\.venvs\urika\Scripts\Activate.ps1

pip install urika                     # core (Anthropic adapter only)
pip install 'urika[openai]'           # + OpenAI Agents SDK adapter (gpt-*/o3-o5)
pip install 'urika[google]'           # + Google ADK adapter (gemini-*)
pip install 'urika[all]'              # all three providers
urika setup                           # check install, detect hardware, optionally install DL

pipx, conda, and uv work too. Deep learning (torch, transformers) is optional: pip install 'urika[dl]'.

On Ubuntu 22.04+, Debian 12+, Fedora 38+, and recent macOS, system Python refuses pip install with error: externally-managed-environment (PEP 668), so the venv above is the simplest path. See Getting Started → Step 1 for per-OS install commands.

Upgrade from v0.6.x:

pip install --upgrade urika           # strict superset — no config changes required

Existing urika.toml and ~/.urika/settings.toml work unchanged. v0.7.0 adds optional new keys ([anthropic] auth, [runtime.models.<agent>] model) with safe defaults — see Provider Guide for mixing providers per agent role.

From source (for active development):

git clone https://github.com/xkiwilabs/Urika.git
cd Urika
pip install -e '.[dev,all]'

Set up API keys

Get keys from your provider(s):

• Anthropic — console.anthropic.com → Settings → API Keys (set a monthly spend limit in Settings → Billing)
• OpenAI — platform.openai.com/api-keys
• Google — aistudio.google.com/app/apikey (enable billing for production rate limits; free tier is 5 RPM / 20 RPD on gemini-3.5-flash)

Save them to the vault:

urika config api-key             # interactive Anthropic-specific wizard
urika config api-key --test      # verify against api.anthropic.com

urika config secret              # generic vault entry — enter OPENAI_API_KEY or GEMINI_API_KEY when prompted

Then pin the provider auth mode (post-June-15 2026, Anthropic supports subscription auth too):

urika config anthropic --mode api_key            # or --mode subscription
urika config openai --mode api_key
urika config google --mode api_key

See Getting Started for the full walkthrough including verification, troubleshooting, and per-OS notes. See Provider Guide for the cross-provider routing model. See Provider compliance for the Anthropic / OpenAI / Google policy rationale.

Quickstart

urika new my-study --data ./my_data.csv    # create a project (interactive)
urika run my-study --dry-run                # preview the planned pipeline first
urika run my-study                          # run experiments
urika finalize my-study                     # produce final report
urika                                       # launch the interactive TUI
urika --classic                             # or use the classic REPL

See the Getting Started guide for a full walkthrough. Agent-generated code runs as you — see Security Model before running unfamiliar projects.

How It Works

flowchart TD
    A["urika new\nProject Builder"] --> B["Scans data, profiles,\ningests knowledge"]
    B --> C{"How to run?"}

    C -- "Single experiment\n(guided)" --> D["urika run"]
    C -- "Multiple experiments\n(autonomous)" --> META["urika run --max-experiments N\nAutonomous Mode"]

    D --> LOOP
    META --> LOOP

    subgraph LOOP ["Experiment Loop (per experiment)"]
        direction TB
        P["Planning Agent\ndesigns method"] --> TA["Task Agent\nwrites code, runs tools"]
        TA --> EV["Evaluator\nscores against criteria"]
        EV --> Q{Criteria met?}
        Q -- No --> ADV["Advisor Agent\nanalyzes, proposes next"]
        ADV --> P
        Q -- "Yes\n(--review-criteria)" --> RC["Advisor reviews\ncriteria"]
        RC -- "raises bar" --> P
        RC -- "confirms" --> REPORT
        Q -- Yes --> REPORT["Generate Reports"]
    end

    D -- "after experiment" --> REVIEW["User reviews results\ndecides next step"]
    REVIEW -- "run again" --> D

    META -- "advisor decides\nnext experiment" --> LOOP

    REPORT --> FIN["urika finalize\nFinalizer Agent"]
    FIN --> OUT["Standalone methods\nFinal report & presentation\nReproduce scripts"]

    TA -. "needs tool" .-> TB["Tool Builder"]
    P -. "needs literature" .-> LIT["Literature Agent"]
    TB -.-> TA
    LIT -.-> P

Twelve agents work together. Each experiment runs autonomously — agents plan, execute, evaluate, and iterate without intervention. You choose how to manage the between-experiment flow:

• Guided (urika run) — agents run one experiment autonomously, then you review results and decide what to try next. Best for exploratory work and complex domains where human judgment matters between experiments.
• Fully autonomous (urika run --max-experiments N) — the system runs multiple experiments back-to-back, with the advisor agent deciding what to try next. Best when you've provided detailed context (see Prompts and Context).

Within each experiment, the orchestrator cycles through planning -> task -> evaluator -> advisor each turn. When all experiments are complete, the Finalizer produces standalone deliverables.

See Agent System for details on each agent role.

Scriptable CLI

Every Urika command is fully scriptable -- pass arguments and flags directly, get structured JSON output with --json, and chain commands in shell scripts. No interactive prompts when flags are provided.

# Create and run a project in one script
urika new my-study --data ~/data/scores.csv --question "What predicts outcome?" --mode exploratory
urika run my-study --max-turns 5 --instructions "focus on tree-based models"
urika run my-study --max-experiments 3 --auto
urika finalize my-study --instructions "emphasize the best model"

# Get structured output for custom tooling
urika status my-study --json
urika results my-study --json
urika methods my-study --json

# Remote control via Telegram/Slack while experiments run
# See Notifications docs for setup

This makes it straightforward to build custom workflows, batch processing scripts, CI pipelines, or wrap Urika in your own research tools. See CLI Reference for the full command list.

Privacy and Model Configuration

Each project can configure which models and endpoints its agents use. Three privacy modes:

• Open (default) -- all agents use cloud models via API. No restrictions.
• Private -- all agents use private endpoints only. This can be local models (Ollama), a secure institutional server, or any combination -- whatever stays within your data governance boundary.
• Hybrid -- a private Data Agent reads raw data and outputs sanitized summaries; all other agents run on cloud models for maximum analytical power. Raw data never leaves your private environment. The default hybrid split covers most cases, but you can customize which agents use which endpoints to ensure what needs to be private stays private.

Per-agent model routing lets you optimize for cost (Haiku for simple tasks, Opus for complex reasoning) or compliance (institutional servers for data access, cloud for method design). Different projects can have completely different privacy and model settings.

See above for supported and upcoming SDK adapters.

See Models and Privacy for configuration details.

Documentation

Guide	Description
Getting Started	Installation, requirements, first project
Interfaces Overview	CLI, TUI, and dashboard as three peer interfaces — when to use which
Core Concepts	Projects, experiments, runs, methods, tools, agents
Creating Projects	urika new, data scanning, knowledge ingestion
Prompts and Context	Writing effective descriptions, instructions, knowledge ingestion
Running Experiments	Orchestrator loop, turns, auto mode, resume
Advisor Chat and Instructions	Standalone advisor conversations, steering agents, suggestion-to-run flow
Viewing Results	Reports, presentations, methods, leaderboard
Finalizing Projects	Finalization sequence, standalone methods, reproducibility
Knowledge Pipeline	Ingesting papers, PDFs, searching
Agent System	All 12 agent roles and how they interact
Tools Overview	Philosophy, ITool / ToolResult API, registry, project-specific tools
Tools Catalogue	Per-category reference for all 24 built-in tools
Models and Privacy	Privacy modes, hybrid architecture, per-agent endpoint assignment
Local Models	Ollama, LM Studio, vLLM/LiteLLM proxy setup, tested-models table
Project Configuration	Per-project urika.toml, criteria, methods, usage
Global Configuration	~/.urika/settings.toml, secrets vault, environment variables
Project Structure	File layout and what each file does
CLI Reference — Projects	urika new, list, delete, status, inspect, update
CLI Reference — Experiments	urika experiment group and urika run
CLI Reference — Results and Reports	dashboard, results, methods, logs, report, present, criteria, usage
CLI Reference — Agents	advisor, evaluate, plan, finalize, build-tool, summarize
CLI Reference — System	knowledge, venv, config, notifications, setup, tools, env vars
Interactive TUI	TUI interface, slash commands, tab completion, orchestrator chat
Dashboard — Pages	Pages, modals, live log, advisor chat, sessions, sidebar, theme
Dashboard — Operations	Lockfiles, idempotent spawn endpoints, completion CTAs, project deletion
Dashboard — Settings	Project + global settings, notification test-send, --auth-token
Dashboard — API	Cross-surface coordination, HTMX/fetch endpoint reference, tech stack
Notifications — Channels	Email, Slack, Telegram setup walkthroughs
Notifications — Remote	Remote /commands, what gets notified, troubleshooting, caveats
Security Model	Agent-generated code, permission boundaries, secrets, dashboard auth
GitHub Backup	urika github commands, pre-commit secret scanner, opt-in auto-push hook
Provider Guide	Choosing between Anthropic / OpenAI / Google, auth setup per provider, mixing providers per agent

Reporting bugs and requesting features

Found a bug? Got an idea for a feature? Open an issue at github.com/xkiwilabs/Urika/issues. Pick the 🐛 Bug report or ✨ Feature request template — it asks for the version, OS, and a few other details that make the issue much faster to act on.

Recently shipped

v0.8 — research scoping + output polish (current release)

• Project builder now scopes real research intent: feasibility check on your research question, analysis-approach / interpretability / constraints preferences, hypotheses decomposition, and co-drafted success criteria — all persisted in urika.toml and fed to the agents
• Dashboard interactive builder wizard: the New Project modal's "Run interactive setup" checkbox opens the same agent Q&A loop urika new runs in a terminal, streamed live in the browser
• Plain-language results: one-sentence interpretation per metric in the labbook, novice-audience method explainers, and run-id traceability (run-003-residuals.png-style figure names; every number in findings.json traces to its run record)
• Adapter hardening: OpenAI $0-usage accounting bug fixed, stream timeouts + error categorization now uniform across Anthropic / OpenAI / Google

v0.7 — multi-provider adapters

• OpenAI Agents SDK adapter + [openai] extra (pip install urika[openai])
• Google Agent Development Kit adapter + [google] extra (pip install urika[google])
• Model-prefix routing (claude-* → Anthropic, gpt-* / o3-* / o4-* / o5-* → OpenAI, gemini-* → Google) — mix providers per agent in the same project
• Anthropic subscription auth path (urika config anthropic --mode subscription), API-key path unchanged
• Setup: urika config anthropic|openai|google --mode api_key then urika config api-key (Anthropic) or urika config secret (OpenAI / Google) — see the Provider Guide for the full decision rubric.

v0.6 — GitHub backup

• One-command setup of a git repo per project + opt-in auto-push after every successful urika run / finalize / build-tool — see the GitHub Backup guide
• Pre-commit secret scanner (Anthropic, OpenAI, GitHub PAT/OAuth, AWS shapes) blocks leaks before they reach the remote
• Dashboard Git tab with remote URL, last push, recent commits
• Researcher-safe .gitignore template with managed-block markers

Coming next

Planned features on the road to v1.0.0. Bug-fix hotfixes (v0.x.y) ship in between as issues are reported.

v0.9 — publication-ready output

• Export reports as PDF or LaTeX
• Export the final pipeline as a runnable Jupyter notebook
• Auto-generated model cards (assumptions, data, intended use, limitations) per finalised method

v0.10 — pre-1.0 hardening

• urika upgrade: one-command, idempotent migration of older projects to the current file formats
• Dashboard builder-wizard sessions survive a server restart (resume scoping where you left off)
• Dashboard accessibility pass: keyboard navigation, focus states, ARIA labels, light/dark contrast audit

v1.0 — first stable release

• Auto-upgrade tool for v0.x projects → v1.0
• Comprehensive docs covering every command, agent, and config key

See CHANGELOG.md for everything already shipped.

Citation

If you use Urika in your research or analysis, please acknowledge its use in your publications:

Urika -- Multi-agent scientific analysis platform. Developed by Michael J. Richardson and colleagues at Macquarie University, Sydney, Australia. https://github.com/xkiwilabs/Urika

License

Apache 2.0 -- Free to use, modify, and distribute for any purpose, including commercial use. Includes patent protection for contributors. See the full license for details.