@hyperspaceai/eva-cli/README.md

A multi-provider conversational AI CLI tool with intelligent text editor capabilities and tool usage.

# EVA-CLI

AI-powered terminal assistant with intelligent text editing and comprehensive tool integration. Talk to AI, edit files, browse the web, and automate tasks directly from your terminal.

<img width="737" height="462" alt="EVA CLI Interface" src="https://github.com/user-attachments/assets/cb058a67-a213-49f4-9db2-c3b1cd16a0e4" />

## Quick Start

### 1. Install
```bash
npm install -g eva-prompt
```

### 2. Setup
```bash
eva setup
```
Follow the prompts to add your AI provider API key (Claude, GPT-4, Gemini, etc.)

### 3. Start Chatting
```bash
eva
```

That's it! EVA will automatically configure essential tools like file operations, git, web browsing, and more.

## Basic Usage

### Chat Commands
```bash
eva                          # Start interactive chat
eva -m claude-4-sonnet      # Use specific AI model
eva -d /path/to/project     # Set working directory
```

### In-Chat Commands
```bash
/models                     # Switch AI providers
/tools                      # View available tools  
/clear                      # Clear chat history
/help                       # Show all commands
```

## What's Included

EVA comes pre-configured with powerful tools:

- **File Operations** - Read, write, search, edit files
- **Git Integration** - Commit, push, branch, merge
- **Web Browsing** - **Playwright** browser automation (default), search, scrape, interact with websites  
- **Code Search** - Fast project-wide code search
- **Memory** - Remember conversation context
- **Desktop Automation** - Control your Mac/Windows desktop
- **Database Tools** - Query SQLite, PostgreSQL

## AI Providers

EVA supports all major AI providers:

- **Claude** (Anthropic) - Best for coding and analysis
- **GPT-4** (OpenAI) - General purpose excellence  
- **Gemini** (Google) - Multimodal capabilities
- **Grok** (X.AI) - Real-time web knowledge
- **Local Models** (Ollama) - Private, offline AI

Set your API key:
```bash
export ANTHROPIC_API_KEY="your-key"
# or use: eva setup
```

## Examples

### Analyze Code
```bash
> help me understand this codebase
> what are the main components?
> suggest improvements to the auth system
```

### Edit Files
```bash
> create a new React component for user profiles
> add error handling to the API calls
> refactor this function to be more readable
```

### Git Automation
```bash
> review my changes and commit with a good message
> /commit-and-push
```

### Web Research
```bash
> search for the latest React best practices
> summarize this documentation page
```

---

## 🧪 Testing Chain-of-Tools (REAL Implementation)

EVA now includes a **production-ready Chain-of-Tools system** that uses actual PyTorch weights from trained models. No more fake random numbers!

### Quick Test

```bash
# Test if your Chain-of-Tools is using REAL weights
npx tsx examples/test-cotools-real.ts
```

**Expected Results:**
- ✅ **PASSED** = Using real trained weights (production-ready!)
- ❌ **FAILED** = Need to train a model first  
- 💥 **CRASHED** = Environment setup issue

### Train Your Model First

```bash
# Train a Chain-of-Tools model
eva cotools train --model 4B --epochs-judge 3 --epochs-retriever 5

# Train different sizes
eva cotools train --model 8B --epochs-judge 5 --epochs-retriever 10
eva cotools train --model 14B --epochs-judge 3 --epochs-retriever 5
```

### Test Different Model Sizes

The system automatically tests multiple Qwen3 model configurations:
- **4B**: 2560 hidden dimensions, 512 intermediate  
- **8B**: 4096 hidden dimensions, 1024 intermediate
- **14B**: 5120 hidden dimensions, 1536 intermediate
- **32B**: 6144 hidden dimensions, 2048 intermediate

### What Gets Tested

1. **PyTorch Bridge** - Real model loading from checkpoints
2. **Weight Validation** - Architecture matches Qwen3 specs
3. **Tool Judge** - Equation 3 from CoTools paper (real neural inference)
4. **Tool Retriever** - Equations 6-8 from CoTools paper (real similarity)
5. **Hidden States** - Authentic Qwen3 representations (no simulation)

### Architecture Validation

The test verifies your model has the correct weight structure:
```
✅ judge.W_gate: 2560x512 validated
✅ judge.W_up: 2560x512 validated  
✅ judge.W_down: 512x1 validated
✅ query.W_gate: 2560x256 validated
✅ shared.W_dim: 2560 elements validated
```

### Troubleshooting

**No trained weights found:**
```bash
eva cotools train --model 4B --epochs-judge 3
```

**PyTorch/transformers missing:**
```bash
pip install torch transformers
```

**Architecture mismatch:**
- Check model was trained with correct Qwen3 configuration
- Verify hidden dimensions match your model size

Your Chain-of-Tools system will **only use real trained weights** - no fallbacks to random numbers!

## 🔧 Advanced Configuration

<details>
<summary>Click to expand advanced setup options</summary>

### Environment Variables
```bash
# AI Providers
export ANTHROPIC_API_KEY="sk-ant-your-key"
export OPENAI_API_KEY="sk-your-key"  
export GOOGLE_API_KEY="your-key"
export GROK_API_KEY="your-key"

# Optional Integrations
export GITHUB_TOKEN="ghp_your_token"      # GitHub integration
export BRAVE_API_KEY="your-key"           # Web search
export DATABASE_URL="postgresql://..."    # Database access
```

### Tool Management
```bash
# Add specific tools
eva mcp add github
eva mcp add brave_search
eva mcp add postgres

# View tool status  
eva mcp list
eva mcp test github

# Provider-optimized setup
eva mcp setup --provider anthropic
```

### Local AI with Ollama
```bash
# Install Ollama from ollama.ai
eva ollama download qwen3:8b
eva -m qwen3:8b
```

### Custom Instructions
Create `.eva/EVA.md` in your project:
```markdown
# Instructions for EVA

Use TypeScript for new files.
Follow the existing code style.
Add tests for new features.
```

### Hyperspace Network
Access distributed AI models:
```bash
eva setup --hyperspace-enable
```

</details>

## 🆘 Need Help?

- **Setup Issues**: Run `eva setup` again
- **Tool Problems**: Check `/tools` or `eva mcp list`  
- **API Errors**: Verify your API keys with `/api-keys`
- **Documentation**: See [MCP_SETUP_GUIDE.md](MCP_SETUP_GUIDE.md)

## 📚 Links

- [Full Documentation](docs/)
- [MCP Setup Guide](MCP_SETUP_GUIDE.md)
- [Examples](examples/)

---

**EVA-CLI: AI-powered productivity in your terminal** 🚀