verdict-ai 0.2.1

AI-powered meta-decision system with dual constrained agents

Verdict

AI-powered meta-decision system with dual constrained agents

English | 简体中文

---

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) ⭐

# 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)

# 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:

brew install pipx
pipx install verdict-ai

Windows:

pip install pipx
pipx install verdict-ai

Linux:

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 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) - Default
  • OpenAI (Platform)
  • Gemini (Google AI Studio)
• Internet connection for API calls

Usage Examples

Example 1: Side Project Decision

$ 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

$ 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

$ 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

$ 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

# 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:

# 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

# 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:

# 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:

# 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:

# 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:

{
  "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:

# 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:

{
  "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:

# 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

# 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

# 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 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:

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:

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:

pipx upgrade verdict-ai
# Or reinstall
pipx uninstall verdict-ai && pipx install verdict-ai

Roadmap

• MVP: Core decision pipeline
• Context management
• Integration tests
• Rich terminal output
• Documentation
• PyPI package distribution
• 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 file for details.

Acknowledgments

• Supports multiple LLM providers:
  • Anthropic Claude (default)
  • OpenAI GPT
  • Google Gemini
• Uses Rich for beautiful terminal output
• Follows CCPM workflow for development

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs/ directory

---

Made with Claude Code 🤖