# Proxym Example: Multi-Project with Natural Language (NLP)

Demonstrates managing **2 projects simultaneously** using **only natural language commands** via `proxym chat`.

## Projects

| Project | Sprint | Tickets | Description |
|---------|--------|---------|-------------|
| calculator | Calculator MVP | 2 | Python calculator module + tests |
| greeter | Greeter MVP | 2 | Python greeter class + tests |

## What Makes This Different

Unlike `examples/multi-project/` which uses direct CLI commands like:
```bash
proxym project add ...
proxym sprint create ...
proxym ticket add ...
```

This example uses **Natural Language Processing** via `proxym chat`:
```bash
proxym chat "register project calculator at ..."
proxym chat "create sprint Calculator MVP ..."
proxym chat "create feature ticket in calculator project ..."
proxym chat "dispatch all tickets for calculator project" --cli-mode --execute
```

## Quick Start

```bash
# 1. Start proxym
proxym serve &

# 2. Ensure you have an API key configured
#    (for LLM to process NLP commands)
proxym chat  # Will prompt for API key if missing

# 3. Run the NLP example
bash examples/multi-project-nlp/run.sh

# 4. Check results
proxym board
proxym ticket list --project calculator
proxym sprint list
```

## How It Works

### 1. NLP Command Processing
Each step uses natural language that gets processed by LLM:

| Step | NLP Command | Action |
|------|-------------|--------|
| Register | `proxym chat "register project calculator at ..."` | Creates project |
| Sprint | `proxym chat "create sprint Calculator MVP ..."` | Creates sprint |
| Tickets | `proxym chat "create feature ticket ..."` | Creates tickets |
| Dispatch | `proxym chat "dispatch all tickets ..." --cli-mode` | Dispatches to AI tool |

### 2. CLI Generation Mode
For actions that need command execution, we use `--cli-mode --execute`:
```bash
proxym chat "dispatch all tickets for calculator project using aider" --cli-mode --execute
```

This:
1. Generates the appropriate CLI command from NLP
2. Shows it to the user
3. Executes it automatically

### 3. DSL Fallback
Simple queries (status, list, board) work via DSL without LLM:
```bash
proxym chat "show kanban board"
proxym chat "show all tickets for calculator project"
```

## Options

```bash
bash examples/multi-project-nlp/run.sh [OPTIONS]

  --tool NAME    AI tool (default: aider)
  --proxy URL    Proxym URL (default: http://localhost:4000)
  --dry-run      Show plan only
  --clean        Remove generated files from src/
```

## Requirements

1. **Proxym server running**
2. **LLM API key configured** - The NLP processing requires a valid API key:
   - Google AI Studio: https://aistudio.google.com/app/apikey
   - Or OpenAI/Anthropic key

The script will prompt for API key setup if not configured.

## Generated File Structure

```text
examples/multi-project-nlp/
├── run.sh
├── README.md
└── src/
    ├── calculator/
    │   ├── calculator.py       # AI-generated
    │   └── test_calculator.py  # AI-generated
    └── greeter/
        ├── greeter.py          # AI-generated
        └── test_greeter.py     # AI-generated
```

## NLP Commands Demonstrated

### Project Management
- "register project calculator at /path with tool aider"
- "show all projects"

### Sprint Management
- "create sprint Calculator MVP with goal to build Python calculator"
- "show sprint list"

### Ticket Management
- "create high priority feature ticket in calculator project to implement ..."
- "show all tickets for calculator project"
- "show kanban board"

### Task Execution
- "dispatch all tickets for calculator project using aider"
- "analyze all completed tickets for calculator project"

## Troubleshooting

### LLM not available
If you see "⚠ LLM not available: Invalid or missing API key":
```bash
proxym chat  # Interactive mode will prompt for API key
```

### Server not running
```bash
proxym serve &
```

### Commands not recognized
The NLP system may not always generate perfect commands. The example includes:
- Graceful fallbacks to DSL patterns
- Alternative command suggestions
- Manual verification steps

## Comparison: Traditional vs NLP

| Aspect | Traditional CLI | NLP Mode |
|--------|-----------------|----------|
| Commands | `proxym project add ...` | `proxym chat "register project ..."` |
| Learning Curve | Must know flags/options | Natural language |
| Flexibility | Exact syntax required | Handles variations |
| Requires LLM | No | Yes |

## See Also

- `examples/multi-project/` - Same workflow using direct CLI commands
- `examples/simple-3-tickets/` - Simpler example with 1 project
