SERA Vault OS

Self-Evolving Research Architecture — a local-first, Obsidian-integrated operating system for running structured research.

SERA turns a research brief into a structured vault of hypotheses, experiments, logged results, a selected winner, and a client-ready report — from the command line or a local web UI. Every artifact is a plain Markdown file in an Obsidian-compatible vault. You own all the data; nothing leaves your machine unless you choose to share it.

Brief → Hypotheses → Experiments → Results → Winner → Report

• Overview
• Features
• Installation
• Quick Start
• Web UI
• CLI Reference
• Vault Structure
• Use Cases
• Limitations
• Roadmap
• Project Layout
• Contributing
• License

Most research tooling is either too heavy (enterprise platforms with vendor lock-in) or too light (a notes app with no workflow). SERA fills the gap for founders, consultants, and product teams who run research regularly and need a structured, repeatable process — without a SaaS subscription or a data scientist on retainer.

The research workflow is the same every time:

1. Write a brief.
2. Generate testable hypotheses.
3. Design and run experiments.
4. Log what you measured.
5. Pick the winner.
6. Ship a client-ready report.

SERA automates the scaffolding and report generation so you focus on the research, not the paperwork. Optional Claude integration writes hypotheses and report prose; without an API key, SERA falls back to built-in templated generators so the system always works — even offline.

• Full research lifecycle — brief to report in one toolchain, including real experiment execution: attach a Python script to an experiment, run it, and SERA logs the per-condition results and selects the winner automatically.
• Local-first & private — every artifact is Markdown on your disk. No cloud, no lock-in.
• Obsidian-native — vaults open directly in Obsidian with wiki-links between artifacts.
• Two interfaces — a Click-based CLI and a Streamlit web UI that share the same vault.
• Per-client isolation — each client gets an independent vault tree.
• Optional AI generation — set ANTHROPIC_API_KEY for Claude-authored hypotheses and reports; graceful fallback without it.
• Tested — an automated test suite covers the shared foundation, CLI, engine, and reports.

Requirements: Python 3.10+ and pip.

# Clone the repository
git clone https://github.com/SukinShetty/sera.git
cd sera

# (Recommended) create and activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify the CLI
python -m cli.main --version

Hypothesis and report prose can be authored by Claude. This requires the anthropic package and an API key:

pip install anthropic

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."
# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."

Without a key, SERA uses built-in templated generators — every command still produces complete output.

python -m pytest tests/ -v

The fastest way to use SERA is one command (requires ANTHROPIC_API_KEY). sera ask turns your question into a brief, generates testable hypotheses, has Claude write and execute a validated experiment script for each one, and answers with the best-performing condition — every artifact saved to the client vault as evidence.

python -m cli.main ask "Which caching strategy has the best hit rate?"

OK Brief written: brief-001
OK 3 hypotheses generated
[1/3] Testing: Audience Alignment: ...
    done winner=treatment (hit_rate=0.9)
...
+---------------- ANSWER ----------------+
| treatment performed best:              |
| hit_rate = 0.9                         |
|                                        |
| Question: Which caching strategy ...   |
+----------------------------------------+
        Evidence: 3/3 experiments succeeded
| Hypothesis | Winner | Metric | Value | Mode | Attempts | Status |
| ...        | ...    | ...    | ...   | ...  | ...      | ok     |
Evidence:
  Vault:    vault/clients/ask-caching-strategy-best-hit
  Run logs: engine/logs/ask-caching-strategy-best-hit
Note: results include simulated experiments -- they measure real algorithms on synthetic data.
  Report: reports/output/.../report-brief-001-001.md

Prefer to drive each stage yourself? The same pipeline is available as individual commands — a complete research cycle for a new client:

# 1. Create an isolated client vault
python -m cli.main vault init --client acme-corp

# 2. Write a brief (or create it in the Web UI)
#    → vault/clients/acme-corp/briefs/brief-001.md

# 3. Generate three hypotheses from the brief
python -m cli.main hypothesis generate --client acme-corp --brief brief-001

# 4. Create an experiment from a hypothesis
python -m cli.main experiment create --client acme-corp --hypothesis hyp-001

# 5. Log measured results (Python API or Web UI)
python - <<'PY'
from engine.results import log_result
log_result("acme-corp", "exp-001", "A", "conversion_rate", 0.09, notes="Control")
log_result("acme-corp", "exp-001", "B", "conversion_rate", 0.17, notes="Treatment")
PY

# 6. Select the winning condition (Python API or Web UI)
python -c "from engine.winner import select_winner; print(select_winner('acme-corp','exp-001'))"

# 7. Generate the client-ready report
python -m cli.main report generate --client acme-corp --brief brief-001
#    → reports/output/acme-corp/report-brief-001-001.md

Instead of logging results by hand (step 5 above), you can attach an executable Python script to an experiment and let SERA run it. The script prints a final SERA_METRICS JSON line; SERA logs one result per condition, picks the winner, and writes a run log. Try it with the bundled reference experiment (a deterministic chunking-strategy retrieval benchmark):

# Attach the reference experiment script
python -m cli.main experiment attach acme-corp exp-001 engine/experiments/ref_chunking_retrieval.py

# Execute it — results are logged and the winner is selected automatically
python -m cli.main experiment run acme-corp exp-001

With ANTHROPIC_API_KEY set, SERA can also write the experiment script for you: Claude reads the brief, hypothesis, and experiment design, generates a standalone Python script, and SERA statically validates it (stdlib-only import allowlist, no file/network/exec access, correct SERA_METRICS output contract) before attaching and running it. Validation or runtime failures are fed back to Claude for repair, up to two rounds.

python -m cli.main experiment generate acme-corp exp-001            # generate + run
python -m cli.main experiment generate acme-corp exp-001 --no-run   # generate + attach only

Honest limitation: generated scripts are restricted to the Python standard library, so they usually cannot measure your real system — many are simulations of the hypothesized behavior. Scripts label themselves by printing MODE: simulation as their first output line, and the CLI surfaces this as Mode: simulation after the results table. Treat simulated results as a structured way to reason about a hypothesis, not as empirical evidence.

A brief is the only file you write by hand. Everything downstream is generated. Example brief:

---
title: Onboarding Conversion Study
client_id: acme-corp
status: active
created: 2026-05-12
---

# Research Brief: Onboarding Conversion Study

## Objective
Increase trial-to-paid conversion from 8% to 15% within 60 days.

## Research Questions
1. What are the top three friction points in the onboarding flow?
2. Which onboarding steps correlate most strongly with paid conversion?

SERA ships a local web UI that mirrors the full CLI workflow:

streamlit run frontend/app.py

Opens at http://localhost:8501. Use the sidebar to create or switch client vaults; each tab maps to one step of the workflow:

The CLI and Web UI share the same vault — work done in one is immediately visible in the other.

All commands follow python -m cli.main <group> <command> [OPTIONS].

Note: Result logging and winner selection are currently exposed via the Web UI and the Python API (engine.results.log_result, engine.winner.select_winner); dedicated CLI commands are on the roadmap.

Every client gets an isolated, Obsidian-compatible tree:

vault/
  clients/
    {client_id}/
      _meta.md             # Obsidian entry point for this client
      briefs/              # Research briefs (you write these)
      hypotheses/          # Generated by engine.hypothesis
      experiments/         # Created by engine.experiment
      results/             # Logged by engine.results

reports/
  output/
    {client_id}/
      report-brief-001-001.md   # Final client-ready report

All files are standard Markdown with YAML frontmatter — open them in Obsidian or any editor.

• Conversion rate optimisation — structured A/B tests on onboarding, pricing, or checkout, with a report showing which variant wins and by how much.
• Product-market fit research — test positioning hypotheses per segment, log scores, and report the strongest signal.
• Consulting engagements — one isolated vault per client, with a polished report at the end of each sprint.
• Startup validation sprints — run 5–10 experiments a week across pricing, messaging, and targeting; SERA tracks what's been tested and what's next.
• Internal strategy — force disciplined decisions before committing engineering resources.

• v0.2.0 — Streamlit frontend ✅ (shipped) — local web UI covering the full workflow; CLI unchanged.
• v0.3.0 — Report formats — PDF/HTML export, Slack/email delivery hooks.
• v0.4.0 — Obsidian integration — custom plugin, Dataview dashboards, graph-view links.
• v0.5.0 — Collaboration — optional cloud sync, shared vaults with access control.
• v1.0.0 — Self-evolving layer — SERA reads its own past results and proposes the next hypotheses automatically, closing the research loop.

sera-vault-os/
  shared/         # Config, file I/O, validators
  cli/            # Click CLI commands
  vault/          # Obsidian scaffold + templates
  engine/         # Hypothesis, experiment, results, winner
  reports/        # Compiler, formatter, exporter
  frontend/       # Streamlit web UI
  tests/          # Automated test suite
  requirements.txt
  sera_config.json

Contributions are welcome. Please:

1. Fork the repository and create a feature branch.
2. Add or update tests for your change.
3. Ensure python -m pytest tests/ -v passes.
4. Open a pull request describing the change and its motivation.

Released under the MIT License.

_{SERA Vault OS was built with Claude Code using a parallel multi-agent workflow: independent sessions on isolated git worktrees each owned one module (shared, cli, vault, engine, reports, frontend), coordinated through shared memory and integrated in a single verified pass. See DEMO.md for a full walkthrough.}