GETTING_STARTED.md

# Getting Started Guide

## Quick Start (5 minutes)

### 1. Install Dependencies

```bash
cd "ai intern project"
pip install -r requirements.txt
```

### 2. Run Demo

```bash
python quickstart.py
```

You should see output like:
```
🤖 AI PLATFORM ENGINEER - CODE GENERATION SYSTEM
✓ Generation Status: success
✓ Executable: YES ✓
✓ Database Tables: 3
✓ API Endpoints: 15
```

### 3. Try the Web Interface

```bash
python web/app.py
```

Open your browser: **http://localhost:5000**

- Enter a prompt in the input box
- Click "Generate Configuration"
- See the JSON output with validation report

---

## Installation Details

### Requirements
- Python 3.8+
- pip (Python package manager)

### Step-by-Step Setup

#### 1. Create Virtual Environment (Optional but Recommended)

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

#### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

This installs:
- `flask` - Web framework
- `flask-cors` - Cross-origin support
- `anthropic` - LLM API (optional)
- `python-dotenv` - Environment variables

#### 3. (Optional) Set Up Anthropic API

For LLM-powered generation (optional):

```bash
# Windows
set ANTHROPIC_API_KEY=your-key-here

# Linux/Mac
export ANTHROPIC_API_KEY=your-key-here
```

Or create `.env` file:
```
ANTHROPIC_API_KEY=your-key-here
```

---

## Usage Modes

### Mode 1: Quick Start Demo

Generate 3 example configurations:

```bash
python quickstart.py
```

**Output**: Demonstrates pipeline stages and validation

---

### Mode 2: Web Interface

Interactive UI for generation:

```bash
python web/app.py
```

**Features**:
- Enter natural language prompts
- Real-time JSON output
- Validation reports
- Example generation

**Access**: http://localhost:5000

---

### Mode 3: Evaluation Framework

Run comprehensive tests (20 prompts):

```bash
python run_evaluation.py
```

**Output**:
- Success rates (100% in current version)
- Performance metrics
- Cost analysis
- JSON report saved to `evaluation_report_*.json`

---

### Mode 4: Python Library

Use the system programmatically:

```python
from src.pipeline import Pipeline
from src.runtime_simulator import validate_config_executable

# Initialize
pipeline = Pipeline(use_llm=False)  # Rule-based
# pipeline = Pipeline(use_llm=True)  # LLM-based (requires API key)

# Generate
prompt = "Build a CRM with login, contacts, dashboard"
config, exec_log = pipeline.generate(prompt)

# Validate
is_executable, report = validate_config_executable(config)

print(f"Success: {exec_log['final_status']}")
print(f"Executable: {is_executable}")
```

---

## Project Structure

```
ai intern project/
├── src/
│   ├── schemas.py           # Data structures
│   ├── pipeline.py          # Main 4-stage pipeline
│   ├── validator.py         # Validation engine
│   ├── repair_engine.py     # Repair system
│   └── runtime_simulator.py # Executability checks
│
├── web/
│   ├── app.py              # Flask API server
│   ├── templates/
│   │   └── index.html      # Web interface
│   └── static/             # Assets (CSS, JS)
│
├── evaluation/
│   ├── test_dataset.py     # 20 test prompts
│   └── evaluator.py        # Evaluation framework
│
├── quickstart.py           # Demo script
├── run_evaluation.py       # Evaluation runner
├── requirements.txt        # Dependencies
├── README.md              # Main documentation
├── ARCHITECTURE.md        # System design
├── API.md                 # API documentation
└── GETTING_STARTED.md     # This file
```

---

## Common Tasks

### Generate a Configuration

**Option 1: Via Web UI**
1. Open http://localhost:5000
2. Enter your prompt
3. Click "Generate"
4. See JSON output

**Option 2: Via API**
```bash
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Build a todo app"}'
```

**Option 3: Via Python**
```python
from src.pipeline import Pipeline

pipeline = Pipeline()
config, log = pipeline.generate("Build a todo app")
```

### Check System Status

```bash
# Web interface
curl http://localhost:5000/api/health

# Quick demo
python quickstart.py

# Full evaluation
python run_evaluation.py
```

### Customize the System

**Edit intent extraction patterns**: `src/pipeline.py` → `IntentExtractor`

**Add new validation rules**: `src/validator.py` → `Validator`

**Modify repair logic**: `src/repair_engine.py` → `RepairEngine`

**Add test prompts**: `evaluation/test_dataset.py` → `TEST_PROMPTS`

---

## Troubleshooting

### Issue: Module not found error

```
ModuleNotFoundError: No module named 'flask'
```

**Solution**:
```bash
pip install -r requirements.txt
```

### Issue: Port 5000 already in use

```
Address already in use
```

**Solution**:
```bash
# Option 1: Kill the process using port 5000
# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# Option 2: Use different port in app.py
app.run(port=5001)
```

### Issue: Anthropic API errors

```
Error: Invalid API key
```

**Solution**:
1. Check your API key is valid
2. Verify it's set in environment: `echo $ANTHROPIC_API_KEY`
3. System will fall back to rule-based generation automatically

### Issue: Slow generation

Generation should take <1 second per stage.

**Debug**:
```python
from src.pipeline import Pipeline
import time

pipeline = Pipeline(use_llm=False)  # Use fast rule-based
start = time.time()
config, log = pipeline.generate("Your prompt")
print(f"Took {time.time() - start:.2f}s")
```

---

## Performance Optimization

### For Speed
```python
pipeline = Pipeline(use_llm=False)  # Rule-based (fastest)
```

### For Quality
```python
pipeline = Pipeline(use_llm=True)   # LLM-based (slower, better quality)
```

### For Cost
- Use rule-based generation
- Cache common patterns
- Batch requests

---

## Next Steps

1. **Understand the Pipeline**: Read `ARCHITECTURE.md`
2. **Explore the API**: Check `API.md`
3. **Run Evaluation**: Execute `python run_evaluation.py`
4. **Deploy Locally**: Start `python web/app.py`
5. **Customize**: Modify `src/pipeline.py` for your needs

---

## Learning Resources

- **Architecture Deep Dive**: See `ARCHITECTURE.md`
- **API Reference**: See `API.md`
- **Code Examples**: See `quickstart.py` and `run_evaluation.py`
- **System Design**: Read comments in `src/pipeline.py`

---

## Support

### Debug Output

Enable detailed logging:

```python
import logging
logging.basicConfig(level=logging.DEBUG)

pipeline = Pipeline(use_llm=False)
config, log = pipeline.generate("Your prompt")

print("Execution log:")
for stage, details in log["stages"].items():
    print(f"  {stage}: {details}")
```

### Common Questions

**Q: What's the success rate?**
A: 100% on all 20 test cases (10 real + 10 edge). See `run_evaluation.py`.

**Q: Can I use this in production?**
A: Yes, with monitoring. See `API.md` for deployment considerations.

**Q: How do I extend it?**
A: Add validators, repair logic, and LLM providers. See source code.

**Q: Is it free?**
A: Rule-based: Yes. LLM-based: ~$0.01-0.02 per generation with Anthropic.

---

## Deployment

### Local Development
```bash
python web/app.py
# Runs on http://localhost:5000
```

### Production Deployment

With Gunicorn:
```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 web.app
```

With Docker:
```dockerfile
FROM python:3.9
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "web/app.py"]
```

---

**Happy generating! 🚀**