Assumption Zero

Evidence-first startup validation for founders who would rather learn than guess.

Discover real competitors, challenge the riskiest assumptions, score the opportunity, and leave with experiments you can run before building.

Quick start · How it works · CLI · Scoring · Contribute

_{The real web and CLI interfaces. Both use the same analysis engine and shared history.}

Important

Assumption Zero is decision support—not a prediction, investment recommendation, or substitute for speaking with customers. Claims are grounded in collected evidence and uncertainty remains visible.

Why Assumption Zero?

Most idea validators turn a polished prompt into a polished opinion. Assumption Zero separates the jobs:

• Research providers collect evidence from the live web, news, arXiv, GitHub, Hacker News, Reddit, and Wikipedia.
• Up to five perspectives interpret the evidence as a market analyst, regional strategist, skeptical investor, customer researcher, and practical builder.
• Python computes the score with explicit weights instead of asking a model to invent one.
• Citation validation rejects unsupported claims and competitor candidates that are not backed by their cited evidence.
• Experiments turn uncertainty into action with success criteria, failure criteria, cost, and time estimates.
• The founder toolkit turns the verdict into an operating plan with positioning, a beachhead customer, acquisition channels, metrics, interview questions, decision rules, and a 30-day roadmap.

What you get

Output	What it answers
Evidence-backed competitor map	Who already solves this problem, and how directly?
Regional market reality	Is demand, pricing, regulation, and distribution actually evidenced in the selected geography?
Opportunity Score	How strong is the opportunity across seven inspectable dimensions?
Three to five independent perspectives	What would market, regional, investor, customer-research, and builder specialists challenge?
Unit-economics stress test	What happens when price, CAC, cost, or churn changes?
Founder action plan	Who should I reach first, what should I measure, and when should I stop or proceed?
Validation experiments	What is the cheapest useful test to run next?
Exportable report	How can the evidence and decision be shared with a team?

How it works

flowchart LR
    A[Describe the idea] --> B[Collect live evidence]
    B --> C[Verify competitors and citations]
    C --> D[Run 3-5 independent perspectives]
    D --> E[Compute deterministic score]
    E --> F[Generate validation experiments]
    F --> G[Build a 30-day founder action plan]

Loading

The engine preserves the evidence trail throughout the report, so a reader can distinguish a sourced claim from an inference and an inference from a missing signal.

Quick start

Requirements

• Python 3.12+
• Node.js 20+ for the web interface
• An AI-provider key is optional; without one, Assumption Zero runs its labeled deterministic baseline over collected evidence

1. Install the engine

git clone https://github.com/ramizz1/assumption-zero.git
cd assumption-zero/backend
python -m venv .venv

Activate the environment:

# Windows 
.venv\Scripts\activate.bat && pip install -e ".[dev]"

# macOS / Linux
source .venv/bin/activate
pip install -e ".[dev]"

2. Run your first analysis

azero config
azero demo

Or start with your own idea:

azero prompt "A privacy-first AI meeting summarizer for small law firms"

Use --depth standard, --depth deep, or --depth exhaustive. Deep is the default. Exhaustive runs the broadest query set and five analysis perspectives, so it takes longer and uses more provider/API capacity.

3. Launch the web interface

Terminal one:

cd backend
.venv/Scripts/uvicorn assumption_zero.main:app --reload --port 8000

On macOS or Linux, use .venv/bin/uvicorn instead.

Terminal two:

cd frontend
npm ci
npm run dev

Open http://localhost:5173.

The in-app founder guide and CLI/API reference are available at http://localhost:5173/docs. The detailed web brief supports industry, stage, solution, team, runway, timeline, revenue goal, acquisition channels, competitors, moat, assumptions, and regulatory constraints.

Tip

If Windows reports WinError 10013 on port 8000, another process or Windows port reservation is blocking it. Try --port 8010, then set VITE_API_BASE_URL=http://localhost:8010 for the frontend.

AI providers

Use azero config for the interactive setup. Supported configurations include OpenRouter, Groq, OpenAI-compatible endpoints, OpenCode, Ollama, and the no-key deterministic baseline.

azero verify-provider openrouter --api-key sk-or-v1-your-key
azero analyze --provider ollama --model llama3.1

Keep secrets in your local .env; never commit API keys. See .env.example for available settings.

Keys entered in the web settings are intentionally stored only in that browser and sent with each analysis request. They do not modify the backend .env. Use .env for a server-wide or CLI key; use the web settings for a per-browser key. In Auto mode, a key supplied by the browser takes priority, starting with Groq.

Without a working generative-AI provider, the clearly labelled Assumption Zero Evidence Engine can still collect live public search results. It generates deterministic queries, runs the enabled research providers in parallel, normalizes and deduplicates their result snippets, assigns evidence IDs, and applies fixed scoring rules. It does not generate new facts or semantically reason over full sources like an LLM; its qualitative text is template-based and should be treated as a research baseline.

CLI + Web parity

Both interfaces use the same engine, founder-toolkit generator, and root azero_data history. An analysis started in either interface appears in both azero list and the web History view.

Goal	CLI
Configure AI providers	azero config
Run a guided example	azero demo
Analyze natural language	azero prompt "your idea"
Analyze structured input	azero analyze --file examples/sample-idea.json
Choose research depth	azero prompt "your idea" --depth exhaustive
Localize the market	azero analyze --geography Azerbaijan --language Azerbaijani --currency AZN
Choose research sources	azero analyze -r "Web Search" -r GitHub
Inspect saved work	azero list / azero show 1
Stress-test economics	azero simulate 1 --cac 120 --churn 4
Export a report	azero export 1 --format markdown --output report.md
Verify provider settings	azero verify-provider openrouter

Run azero --help or azero <command> --help for every option.

Opportunity Score

The Opportunity Score is deterministic and inspectable:

Dimension	Weight	Signal
Problem Evidence	20%	Customer pain and current workarounds
Demand Signals	20%	Market activity and purchase intent
Competitive Gap	15%	Differentiation and market saturation
Distribution Feasibility	15%	Reachability and likely acquisition efficiency
Unit Economics	15%	Margin, pricing, payback, and retention assumptions
Founder / Project Fit	10%	Skills, runway, and execution fit
Legal & Operational Risk	5%	Compliance, privacy, and operational exposure

AI does not directly choose the final score. It produces structured evidence-aware analysis; the scoring engine applies explicit rules and weights.

Research and accuracy model

Assumption Zero treats model output as a candidate—not a fact:

1. Research providers collect and normalize evidence.
2. AI responses cite evidence IDs from that collection.
3. Citation validation rejects missing or fabricated references.
4. Discovered competitors are accepted only when their cited evidence supports the name.
5. Conflicts, gaps, confidence, and missing information remain visible in the report.

Regional demand is calculated separately. Only evidence tied to the selected geography contributes to the regional evidence score; global category growth is never treated as proof of local demand. The report also separates local demand, pricing, regulatory, and distribution signals and lists the regional research gaps that remain.

Research depth

Depth	Query coverage	Perspectives	Best for
Standard	1 query per evidence category	3	Quick early screening
Deep (default)	2 queries per category	4	Serious validation with regional analysis
Exhaustive	Up to 4 queries per category	5	Maximum evidence collection and customer-research scrutiny

With an AI key, every selected perspective receives the evidence pack and full founder context. Without a key, the deterministic evidence engine still produces scoring, regional coverage, competitors, experiments, economics, and the 30-day founder toolkit; it labels missing evidence instead of inventing conclusions.

This design reduces hallucination risk, but it cannot eliminate incomplete search results, stale source material, provider errors, or ambiguous evidence.

Architecture

assumption-zero/
├── backend/
│   ├── assumption_zero/
│   │   ├── analysis/       # orchestration, scoring, citation validation
│   │   ├── api/            # FastAPI endpoints
│   │   ├── llm/            # model adapters and structured responses
│   │   ├── research/       # live evidence providers
│   │   └── cli.py          # Typer CLI
│   └── tests/
├── frontend/
│   └── src/                # React, TypeScript, reports, simulators
├── docs/assets/            # repository media
├── examples/
└── .github/workflows/      # continuous integration

Development

Run the backend suite:

cd backend
.venv/Scripts/python -m pytest -q

Run the frontend quality gate:

cd frontend
npm run check

Deploy safely

Before exposing Assumption Zero publicly:

• Serve it over HTTPS because users may supply their own provider keys.
• Set SSRF_PROTECTION_ENABLED=true for custom provider URLs.
• Restrict CORS_ORIGINS to the real frontend origin.
• Add rate limiting at the proxy or hosting layer.
• Persist azero_data on a protected volume and define a retention policy.
• Keep .env and generated private reports out of version control.

See SECURITY.md for vulnerability reporting.

Contributing

Contributions that improve evidence quality, research coverage, scoring transparency, provider support, accessibility, or founder workflows are welcome. Start with CONTRIBUTING.md, or open a feature request if you want to discuss an idea first.

License

Released under the MIT License.

If Assumption Zero helps you avoid building the wrong thing, consider starring the repository.

⭐ Star Assumption Zero