aideator 1.0

Local-first FastAPI service for idea validation and markdown reports

AIdeator

AIdeator: From raw idea to build decision.

AIdeator is a complete idea validation system that takes you from raw idea to build decision — with scored desk research, structured user interviews, and behavioral experiments. Stop overthinking. Start validating.

Architecture · Configuration · Quick Start · Security & Privacy · Issues

What is AIdeator?

AIdeator is a local-first idea validation engine that turns raw product ideas into structured validation reports with demand, competition, and risk scoring. It combines:

• LLM-powered analysis via Ollama (local), OpenAI, Anthropic, or Mistral
• Search-backed signals via built-in web fetch, Tavily, or Exa
• Benchmark scoring with 0–100 scores and percentile comparisons
• Privacy modes that control what data leaves your machine

Think of it as your AI research analyst for product ideas — run it locally with zero external calls, or connect cloud providers for deeper insights.

Key Features

Feature	Description
🪄 Premium UI	Score interpolations, staggered reveals, and glassmorphic aesthetics
⚡ Real-time SSE	Live engine telemetry with status pulses and progress bars
⌨️ Cmd+K Palette	Pro-tier keyboard navigation for rapid system access
📄 HTML Export	Self-contained HTML reports with embedded animation engines
🔒 Privacy modes	local-only, hybrid, cloud-enabled — you control data egress
🤖 LLM providers	Ollama (local), OpenAI-compatible, Anthropic, Mistral
🔍 Search providers	Built-in (free), Tavily (AI search), Exa (semantic search)
📊 0–100 scoring	Demand, competition, risk with score-counting animations
📈 Benchmarks	Compare scores against 12 reference SaaS products
🖥️ Web dashboard	Server-rendered UI with status badges and kinetic pulses
⚙️ Config wizard	aideator config init for interactive setup
📚 Desk Research	Deep analysis of market signals with citations and source mapping
🎤 User Interviews	Automated generation of structured interview kits and recruitment plans
🧪 Experiments	Practical behavioral validation blueprints and success metrics

Quick Start

# Clone and install
git clone https://github.com/ARCHITECTURA-AI/AIdeator
cd AIdeator
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

# Configure (interactive wizard)
aideator config init

# Start the server
aideator serve

Default URL: http://localhost:8000

Architecture

aideator/          # Core package: CLI, paths, LLM & search providers
├── llm/           # LLM provider abstraction (Ollama, OpenAI, Anthropic, Mistral)
├── search/        # Search providers (DuckDuckGo, SearXNG, Tavily, Exa, Builtin)
api/               # FastAPI app, routes, config, middleware
engine/            # Run orchestrator, card synthesizer, benchmark
db/                # In-memory repositories (ideas, runs, reports)
models/            # Data classes (Idea, Run, Report)
templates/         # Jinja2 HTML templates (dashboard, reports, settings)
docs/              # Generated markdown reports & project documentation

Detailed overview: docs/architecture.md

Search Providers

AIdeator supports a fully-tiered search abstraction, bringing context to the LLM's idea validation:

Tier	Provider	Cost	Setup Needed	Best For
🟢 Free	duckduckgo	$0	None	General testing, personal use
🟡 Mid	tavily	Paid	API Key	AI-optimized context gathering
🔵 High	exa	Paid	API Key	Deep semantic research
⚙️ Self-hosted	searxng	$0 (your infra)	SearXNG Instance	Power users, maximum privacy
⬜ Offline	builtin	$0	None	URL extraction only (no search)

Configure via aideator config init or set SEARCH_PROVIDER env var.

LLM Providers

Provider	Local?	API Key?	Notes
Ollama	✅	No	Default, runs any GGUF model
OpenAI-compatible	❌	Yes	GPT-4o, Groq, etc.
Anthropic-compatible	❌	Yes	Claude models
Mistral-compatible	❌	Yes	Mistral models

Scoring System

Every validation run produces cards with 0–100 scores and automatic bands:

Score Range	Band	Meaning
70–100	🟢 High	Strong signal
40–69	🟡 Medium	Moderate signal, needs investigation
0–39	🔴 Low	Weak signal, high risk area

Scores are compared against an internal benchmark corpus of 12 known SaaS products to provide percentile rankings.

Privacy Modes

Mode	External calls	Use case
local-only	None	Fully offline, maximum privacy
hybrid	Keyword-only queries (10 words max)	Balanced privacy + signals
cloud-enabled	Full idea context	Maximum insight quality

Set via APP_DEFAULT_MODE=local|hybrid|cloud environment variable.

Docker

# Build and run
docker build -t your-org/aideator:latest .
docker run --rm -p 8000:8000 --env-file .env your-org/aideator:latest

# Or with compose
docker compose up

CLI Commands

Command	Description
aideator serve	Start the web server
aideator config init	Interactive configuration wizard
aideator config show	Display current configuration
aideator rebuild-docs	Rebuild markdown report artifacts

Flags: --host, --port, --reload, --db, --docs

Development

pip install -e ".[dev]"
make lint      # Ruff linting
make test      # Pytest suite
make dev       # Dev server with reload

Seed test data:

python scripts/seed_example.py

Configuration

• Config file: aideator.toml (auto-created by config init)
• Environment variables: override config file values
• CLI flags: override everything

Key variables:

Variable	Default	Description
APP_DEFAULT_MODE	local	Privacy mode
LLM_PROVIDER	ollama	LLM backend
LLM_MODEL	mistral:7b	Model name
SEARCH_PROVIDER	builtin	Search backend
TAVILY_API_KEY	—	Tavily API key
EXA_API_KEY	—	Exa API key
LLM_API_KEY	—	LLM API key

Full reference: docs/config.md

Security

Local-only mode blocks all outbound HTTP by run-mode guardrails. See docs/security-privacy.md for:

• Data residency guarantees per mode
• API key handling and rotation guidance
• Container hardening recommendations

Version History

Version	Phase
0.9.9	Production Readiness — Type Safety, Stabilization & Full Workflow
0.9.8	Stability, Security & CLI Hardening
0.4.0	PH-D — Plugin & eval
0.3.0	PH-C — Runtime & migration
0.2.0	PH-B — Web UI
0.1.0	PH-A — Foundation

License

MIT. See LICENSE.