verdict-ai 0.2.4
AI-powered meta-decision system with dual constrained agents
License: MIT
Requires Python: >=3.10
Keywords: ai, decision-making, cli, anthropic, claude, openai, gemini, llm

# Verdict

**AI-powered meta-decision system with dual constrained agents**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/verdict-ai.svg)](https://pypi.org/project/verdict-ai/)

[English](README.md) | [简体中文](README_CN.md)

---

Verdict helps you escape decision paralysis by making definitive "should I do this?" and "how should I do this?" decisions for you.

## What is Verdict?

Verdict is a command-line tool that uses two AI agents to transform your fuzzy ideas into frozen decisions and actionable execution plans:

- **Verdict Agent**: Makes singular, decisive judgments (PROCEED/REJECT/ALTERNATIVE) - no "you could also..." suggestions
- **Execution Agent**: Designs minimal implementation plans based on the verdict

Unlike traditional AI assistants that offer endless possibilities, Verdict commits to ONE path and produces persistent artifacts you can execute.

## Core Philosophy

- **No vibe coding** - Every decision traces back to structured reasoning
- **Singular verdicts** - Agent makes ONE decision, no alternatives
- **Frozen decisions** - Decisions are immutable (like Git tags)
- **Persistent artifacts** - Outputs are `decision.json` + `todo.md`, not chat logs
- **Context-aware** - Remembers your goals and past decisions

## Quick Start (< 5 minutes)

### Install from PyPI (Recommended) ⭐

```bash
# Using pipx (recommended)
pipx install verdict-ai

# Or using pip
pip install verdict-ai

# Configure API key
verdict config --provider claude

# Make your first decision
verdict decide "I want to build a personal blog"
```

**That's it!** No need to clone the repository 🎉

### Install from Source (For Developers)

```bash
# Clone the repository
git clone https://github.com/1psychoQAQ/verdict.git
cd verdict

# Using Poetry
poetry install
poetry run verdict config
poetry run verdict decide "your idea"
```

## Installation

### Recommended: Install from PyPI

**macOS:**
```bash
brew install pipx
pipx install verdict-ai
```

**Windows:**
```powershell
pip install pipx
pipx install verdict-ai
```

**Linux:**
```bash
python3 -m pip install --user pipx
pipx install verdict-ai
```

### Installation Options

| Method | Command | Use Case |
|--------|---------|----------|
| **PyPI (pipx)** | `pipx install verdict-ai` | Production use (Recommended) ⭐ |
| **PyPI (pip)** | `pip install verdict-ai` | Simple testing |
| **Source (Poetry)** | `poetry install` | Development |
| **Source (pip)** | `pip install -e .` | Local development |

### Detailed Installation Guide

See **[INSTALL.md](INSTALL.md)** for:
- Windows / macOS / Linux detailed steps
- Troubleshooting common issues
- Environment variable configuration
- Advanced setup options

### Requirements

- Python 3.10 or higher
- API key for at least one of the supported providers:
  - **Claude** ([Anthropic](https://console.anthropic.com/account/keys)) - Default
  - **OpenAI** ([Platform](https://platform.openai.com/api-keys))
  - **Gemini** ([Google AI Studio](https://makersuite.google.com/app/apikey))
- Internet connection for API calls

## Usage Examples

### Example 1: Side Project Decision

```bash
$ verdict decide "I want to build a habit tracking app"

╭────────────────── Verdict ──────────────────╮
│ Decision    PROCEED                         │
│ Summary     Build a minimal habit tracker   │
│ Confidence  82%                             │
│ Included    Daily tracking, Simple UI      │
│ Excluded    Social features, Analytics     │
╰─────────────────────────────────────────────╯

╭──────────────── Execution Plan ─────────────╮
│ Phase 1: Core tracking (3 days)            │
│ Phase 2: Basic UI (2 days)                 │
│ Total: 5 days                              │
╰─────────────────────────────────────────────╯
```

### Example 2: Technical Architecture Choice

```bash
$ verdict decide "Should I use PostgreSQL or MongoDB for my app?"

╭────────────────── Verdict ──────────────────╮
│ Decision    ALTERNATIVE                     │
│ Summary     Use PostgreSQL with JSONB       │
│ Confidence  90%                             │
│ Reasoning   Get SQL reliability + JSON...  │
╰─────────────────────────────────────────────╯
```

### Example 3: Learning Path Decision

```bash
$ verdict decide "Should I learn Rust or Go next?" \
  -c "I'm a Python developer working on backend services"

╭────────────────── Verdict ──────────────────╮
│ Decision    PROCEED                         │
│ Summary     Learn Go for backend work       │
│ Confidence  85%                             │
│ Reasoning   Go is easier to learn coming   │
│             from Python and more common     │
│             in backend services...          │
╰─────────────────────────────────────────────╯
```

### Example 4: Feature Prioritization

```bash
$ verdict decide "Should I add dark mode to my app?"

╭────────────────── Verdict ──────────────────╮
│ Decision    REJECT                          │
│ Summary     Focus on core features first    │
│ Confidence  75%                             │
│ Reasoning   Dark mode is nice-to-have...   │
╰─────────────────────────────────────────────╯
```

### Example 5: Career Decision with Context

```bash
# First, set your context
$ verdict context add-goal "Find remote work opportunities"
$ verdict context set-constraint location "prefer remote"
$ verdict context set-preference risk_tolerance "low"

# Then make the decision
$ verdict decide "Should I accept this startup job offer?"
# Verdict considers your goals, constraints, and preferences
```

## How It Works

### Agent Architecture

```
┌─────────────────────────────────────────────────┐
│                   User Input                    │
│        "I want to build a blog platform"        │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│              Verdict Agent                      │
│  • Analyzes idea against goals & context       │
│  • Makes singular decision (PROCEED/REJECT)     │
│  • Defines scope (included/excluded)            │
│  • Provides reasoning & confidence              │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │    decision.json      │
         │  (Frozen verdict)     │
         └───────────┬───────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│            Execution Agent                      │
│  • Accepts verdict without questioning          │
│  • Designs minimal viable path                  │
│  • Breaks down into phases & tasks              │
│  • Estimates effort & identifies risks          │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │      todo.md          │
         │  (Action plan)        │
         └───────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│              Artifact Storage                   │
│         ~/.verdict/                             │
│         ├── decisions/  (decision.json)         │
│         ├── plans/      (todo.md)               │
│         └── state/      (state.json)            │
└─────────────────────────────────────────────────┘
```

### Decision Pipeline

1. **Context Loading**: Loads your goals, preferences, and past decisions
2. **Verdict Phase**: AI agent makes a singular decision with reasoning
3. **Validation**: Ensures output matches JSON schema
4. **Execution Phase**: AI agent creates implementation plan
5. **Validation**: Ensures plan is actionable and complete
6. **Artifact Generation**: Creates JSON and Markdown files
7. **Storage**: Saves to `~/.verdict/` with timestamps
8. **Context Update**: Records decision in your history

### Retry Logic

- Each phase has 3 retry attempts on failure
- Exponential backoff between retries
- Validation errors trigger automatic retry
- Clear error messages on final failure

## Configuration

### API Key Setup

Verdict supports multiple LLM providers. Configure the one you want to use:

```bash
# Claude (default)
$ verdict config --provider claude
API Key: [hidden]
✓ Configuration saved

# OpenAI
$ verdict config --provider openai
API Key: [hidden]
✓ Configuration saved

# Gemini
$ verdict config --provider gemini
API Key: [hidden]
✓ Configuration saved

# Or set environment variables
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AI..."
```

### Configuration File

Location: `~/.verdict/config.yaml`

```yaml
# Configure one or more providers
anthropic_api_key: sk-ant-...
openai_api_key: sk-...
google_api_key: AI...
```

### Selecting a Provider

Use the `--provider` flag to choose which LLM to use:

```bash
# Use Claude (default)
$ verdict decide "Build a blog" --provider claude

# Use OpenAI GPT-4
$ verdict decide "Build a blog" --provider openai

# Use Google Gemini
$ verdict decide "Build a blog" --provider gemini

# Specify a specific model
$ verdict decide "Build a blog" --provider openai --model gpt-4o
$ verdict decide "Build a blog" --provider gemini --model gemini-1.5-pro
```

**Available Models:**
- **Claude**: `claude-3-5-sonnet-20241022` (default), `claude-3-opus-20240229`, `claude-3-haiku-20240307`
- **OpenAI**: `gpt-4o` (default), `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`
- **Gemini**: `gemini-1.5-pro` (default), `gemini-1.5-flash`, `gemini-pro`

**Installing Provider Support:**

By default, only Claude is included. To use OpenAI or Gemini:

```bash
# Install with all providers (Note: Use quotes in zsh)
pipx install 'verdict-ai[all]'

# Or use pipx inject to add providers
pipx install verdict-ai
pipx inject verdict-ai openai
pipx inject verdict-ai google-generativeai
```

### Context Management

Verdict maintains context across sessions to make better decisions:

```bash
# View current context
$ verdict context show

# Add goals
$ verdict context add-goal "Ship MVP in 2 weeks"
$ verdict context add-goal "Learn by building"

# Set constraints
$ verdict context set-constraint time_budget "weekends only"
$ verdict context set-constraint skill_level "intermediate"

# Set preferences
$ verdict context set-preference risk_tolerance "low"
$ verdict context set-preference innovation_vs_proven "proven"

# Remove a goal
$ verdict context remove-goal "Old goal"

# Clear all context
$ verdict context clear
```

## Output Files

### decision.json

Immutable record of the verdict:

```json
{
  "decision": "proceed",
  "verdict_summary": "Build a minimal CLI tool",
  "reasoning": "This is achievable and valuable...",
  "confidence": 0.85,
  "scope": {
    "included": ["Core CLI", "Basic logic"],
    "excluded": ["Web UI", "Database"],
    "constraints": ["Keep it simple", "CLI only"]
  },
  "timestamp": "2025-12-20T10:00:00Z"
}
```

### todo.md

Actionable execution plan:

```markdown
# Execution Plan: Build a minimal CLI tool

**Decision:** PROCEED
**Estimated Effort:** 6 hours

---

## Phases

### Phase 1: Setup
**Goal:** Initialize project structure
**Tasks:**
- [ ] Create project with Poetry
- [ ] Setup dependencies
- [ ] Configure CLI framework

**Done Criteria:** Project runs with --help
**Estimated Effort:** 2 hours
```

### state.json

Progress tracking snapshot:

```json
{
  "decision_id": "abc123def456",
  "status": "planned",
  "verdict": {
    "decision": "proceed",
    "summary": "Build a minimal CLI tool"
  },
  "execution": {
    "phases_count": 2,
    "total_estimated_effort": "6 hours"
  }
}
```

## Advanced Features

### Decision History

All decisions are stored with timestamps:

```bash
# List recent decisions
ls ~/.verdict/decisions/

# View a specific decision
cat ~/.verdict/decisions/20251220-155518-abc123-decision.json

# Find your latest plan
cat $(ls -t ~/.verdict/plans/*.md | head -1)
```

### Combining with Other Tools

```bash
# Use with task managers
verdict decide "Feature X" && todoist add "$(cat ~/.verdict/plans/*.md | head -1)"

# Use with Git
verdict decide "Refactor auth" && git checkout -b feature/auth-refactor

# Use with project management
verdict decide "New API" && gh issue create --title "Implement API" --body-file ~/.verdict/plans/*.md
```

## Agent Design Rationale

### Why Singular Verdicts?

Traditional AI assistants hedge with multiple options:
> "You could use React, or Vue, or Svelte. Each has pros and cons..."

Verdict makes ONE decision:
> "Use React. Vue and Svelte are excluded from scope."

**Reasoning:**
- Decision paralysis comes from too many options
- Analysis without commitment wastes time
- You can always iterate after shipping

### Why Two Separate Agents?

**Verdict Agent** (What to do)
- Must be critical and skeptical
- Can say "don't do this"
- Considers opportunity cost

**Execution Agent** (How to do it)
- Must be optimistic and constructive
- Cannot question the verdict
- Focuses on minimal path

**Reasoning:**
- Separation prevents "but you could also..." hedging
- Forces commitment at decision boundary
- Execution agent can't re-litigate the verdict

### Why Persistent Artifacts?

Chat logs disappear. Files persist.

**Reasoning:**
- Decisions should be reviewable months later
- Plans should integrate with Git workflow
- State tracking enables project management tools

## Performance & Cost

### Speed
- **Single decision**: 5-30 seconds
- **API calls**: Exactly 2 per decision (fixed)
- **No continuous consumption**: Not a chatbot

### Cost Estimates

| Provider | Model | Cost per Decision |
|----------|-------|-------------------|
| Claude | Sonnet 3.5 | ~$0.02-0.05 |
| Claude | Haiku 3 | ~$0.001-0.003 |
| OpenAI | GPT-4o | ~$0.03-0.06 |
| OpenAI | GPT-3.5 | ~$0.002-0.005 |
| Gemini | 1.5 Pro | ~$0.01-0.03 |
| Gemini | 1.5 Flash | ~$0.0005-0.002 |

**Token Usage**: ~3,000-8,000 tokens per decision

## Development

### Running Tests

```bash
# Run all tests
poetry run pytest tests/

# Run with coverage
poetry run pytest tests/ --cov=verdict --cov-report=html

# Run specific test file
poetry run pytest tests/test_integration.py -v
```

### Project Structure

```
verdict/
├── src/verdict/          # Source code
│   ├── agents.py         # AI agent implementations
│   ├── llm_providers.py  # LLM provider abstraction
│   ├── artifacts.py      # Artifact generation
│   ├── cli.py           # Command-line interface
│   ├── config.py        # Configuration management
│   ├── context.py       # User context management
│   ├── pipeline.py      # Decision pipeline
│   ├── storage.py       # File storage
│   ├── validator.py     # JSON schema validation
│   ├── templates/       # Jinja2 agent prompts
│   └── schemas/         # JSON validation schemas
├── tests/              # Test suite
└── docs/              # Documentation
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution

- Additional LLM provider integrations (Cohere, Mistral, etc.)
- New artifact formats (GitHub Issues, Linear tasks, etc.)
- Integration with project management tools
- Improved agent prompts
- Documentation improvements
- Language translations

## Troubleshooting

### "Authentication error: invalid x-api-key"

**Solution:** Verify your API key:
```bash
verdict config --provider claude  # Re-enter your API key
# Or check environment variable
echo $ANTHROPIC_API_KEY
```

### "Pipeline failed after 3 attempts"

**Possible causes:**
- Network connectivity issues
- API rate limits
- Invalid API key
- Provider service outage

**Solution:**
- Check your internet connection
- Verify API key is correct
- Check provider status pages
- Try again after a few minutes

### "Files not saving to ~/.verdict/"

**Solution:** Check permissions:
```bash
ls -la ~/.verdict/
# If directory doesn't exist, Verdict will create it on first run
```

### "No such option: --provider" or outdated version

**Solution:** Upgrade to the latest version:
```bash
pipx upgrade verdict-ai
# Or reinstall
pipx uninstall verdict-ai && pipx install verdict-ai
```

## Roadmap

- [x] MVP: Core decision pipeline
- [x] Context management
- [x] Integration tests
- [x] Rich terminal output
- [x] Documentation
- [x] PyPI package distribution
- [x] Multi-LLM provider support (Claude, OpenAI, Gemini)
- [ ] GitHub Actions CI/CD integration
- [ ] Decision review/update workflow
- [ ] Team collaboration features
- [ ] Additional LLM providers (Cohere, Mistral, etc.)
- [ ] Web UI dashboard
- [ ] API server mode

## Philosophy

Verdict is inspired by:
- **Getting Things Done (GTD)**: Reduce open loops, make definitive commitments
- **Shape Up**: Fixed scope, flexible time approach
- **Unix Philosophy**: Do one thing well, compose with other tools
- **Git**: Immutable history, branching possibilities

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- Supports multiple LLM providers:
  - [Anthropic Claude](https://www.anthropic.com/) (default)
  - [OpenAI GPT](https://openai.com/)
  - [Google Gemini](https://deepmind.google/technologies/gemini/)
- Uses [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Follows [CCPM workflow](https://github.com/anthropics/claude-code) for development

## Support

- **Issues**: [GitHub Issues](https://github.com/1psychoQAQ/verdict/issues)
- **Discussions**: [GitHub Discussions](https://github.com/1psychoQAQ/verdict/discussions)
- **Documentation**: See `docs/` directory

---

**Made with [Claude Code](https://claude.com/claude-code)** 🤖