Metadata-Version: 2.4
Name: aideator
Version: 0.9.7
Summary: Local-first FastAPI service for idea validation and markdown reports
Project-URL: Homepage, https://github.com/ARCHITECTURA-AI/AIdeator
Project-URL: Source, https://github.com/ARCHITECTURA-AI/AIdeator
Project-URL: Issues, https://github.com/ARCHITECTURA-AI/AIdeator/issues
Author-email: Richard Abishai <richard@richardabish.ai>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: ddgs>=7.0.0
Requires-Dist: fastapi>=0.116.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.5.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: reportlab>=4.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: uvicorn[standard]>=0.35.0
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Description-Content-Type: text/markdown

  AIdeator logo

  AIdeator

AIdeator

  AI-powered idea validation engine with pluggable LLM and search providers

  Validate product ideas with configurable privacy modes, search-backed signals, and benchmark scoring — all from a single local-first FastAPI service.

  Setup time
  License
  Python
  FastAPI
  Docker compose
  HTML+PDF reports

  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

| 🪄 **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 |

## Quick Start

```bash
# 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`](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

```bash
# 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

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

Seed test data:

```bash
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`](docs/config.md)

## Security

Local-only mode blocks all outbound HTTP by run-mode guardrails. See [`docs/security-privacy.md`](docs/security-privacy.md) for:
- Data residency guarantees per mode
- API key handling and rotation guidance
- Container hardening recommendations

## Version History

| Version | Phase |
|---------|-------|
| `1.1.0` | V1.1 — UI Polish & Command Palette |
| `1.0.0` | V1.0 — Full validation engine |
| `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`](LICENSE).