### Core Components

**`agent.py` - The Brain**

- Runs the ReAct loop
- Decides which tools to use
- Manages workflows
- Returns results

**`state.py` - The Memory**

- Tracks current directory
- Maintains file history
- Stores session state
- Records operations

**`tools.py` - The Hands**

- File I/O operations
- Git commands
- Web search
- Script execution

**`cli.py` - The Interface**

- Terminal UI with Rich
- Syntax highlighting
- Progress indicators
- Interactive prompts

---

## ⚙️ Configuration

### Environment Variables

Create `.env` with these options:

```env
# REQUIRED - Your OpenAI API key
OPENAI_API_KEY=sk-...

# OPTIONAL - Web search
EXA_API_KEY=your-key-here

# OPTIONAL - Fast inference
GROQ_API_KEY=your-key-here

# MODEL - Which AI model to use
# gpt-4o-mini (fast, cheap)
# gpt-4o (balanced)
# gpt-4 (powerful, expensive)
# gpt-3.5-turbo (fastest, cheapest)
CODEFORGE_MODEL=gpt-4o-mini

# TEMPERATURE - 0=deterministic, 1=creative
CODEFORGE_TEMPERATURE=0.1

# MAX STEPS - How many reasoning steps
CODEFORGE_MAX_STEPS=20

# DEBUG - Enable verbose logging
DEBUG=false

# LOG LEVEL - DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO
```

### Model Selection Guide

| Model         | Speed  | Cost   | Best For                 |
| ------------- | ------ | ------ | ------------------------ |
| gpt-4o-mini   | ⚡⚡⚡ | 💰     | Quick tasks, prototyping |
| gpt-4o        | ⚡⚡   | 💰💰   | Balanced, most tasks     |
| gpt-4         | ⚡     | 💰💰💰 | Complex reasoning        |
| gpt-3.5-turbo | ⚡⚡⚡ | 💰     | Budget-friendly tasks    |

### Temperature Guide

**0.0 - Deterministic (Best for code)**

- Consistent, predictable output
- Good for: Code generation, technical tasks
- Example: "Write a sorting algorithm"

**0.5 - Balanced (Default)**

- Mix of reliability and creativity
- Good for: General tasks, refactoring

**1.0 - Creative (Best for ideas)**

- More varied, creative output
- Good for: Brainstorming, naming
- Example: "Suggest 5 cool project ideas"

---

## 🎯 Use Cases

### 1. Web Development 🌐

```
"Create a Flask REST API with:
- GET /api/products - list products
- GET /api/products/<id> - get one product
- POST /api/products - create product
- DELETE /api/products/<id> - delete product

Include authentication, error handling, and logging"
```

**Output:** Production-ready API with middleware!

---

### 2. Data Science 📊

```
"Write a Python script that:
- Loads CSV file
- Performs exploratory data analysis
- Creates visualizations (histograms, scatter plots)
- Exports statistics to JSON"
```

**Output:** Complete analysis pipeline with plots!

---

### 3. DevOps 🚀

```
"Create a GitHub Actions workflow that:
- Runs on push to main
- Installs dependencies
- Runs tests
- Builds Docker image
- Pushes to registry"
```

**Output:** CI/CD pipeline ready to go!

---

### 4. Testing 🧪

```
"Generate unit tests for the fibonacci function including:
- Basic functionality tests
- Edge cases (n=0, n=1, negative)
- Performance tests
- Error handling"
```

**Output:** Comprehensive test suite with pytest!

---

### 5. Code Refactoring 🔧

```
"Refactor agent.py for:
- Better readability
- Lower complexity
- Improved error handling
- Added type hints
- Better documentation"
```

**Output:** Clean, maintainable code!

---

### 6. Documentation 📚

```
"Generate complete documentation:
- API endpoints with examples
- Setup instructions
- Troubleshooting guide
- Best practices"
```

**Output:** Professional documentation!

---

## 🔒 Security

CodeForge AI implements multiple security layers:

### Protection Mechanisms

1. **Path Traversal Prevention**

   - ❌ Blocks: `../../sensitive_files`
   - ✅ Allows: Only project directory access

2. **Safe Script Execution**

   - ❌ Blocks: `rm -rf`, network access
   - ✅ Runs: Safe scripts in isolated subprocess

3. **Destructive Operation Guards**

   - ❌ Refuses: Permanent file deletion
   - ✅ Requires: Explicit confirmation

4. **API Key Protection**

   - ❌ Never: Logs API keys
   - ✅ Uses: Environment variables securely

5. **Error Handling**
   - ❌ Doesn't: Expose system internals
   - ✅ Provides: Helpful error messages

### Safe Usage Practices

```python
# ✅ DO: Use environment variables
OPENAI_API_KEY=sk-...

# ❌ DON'T: Hardcode keys
api_key = "sk-..."

# ✅ DO: Review changes first
git diff

# ✅ DO: Use version control
git commit -am "Safe change"

# ❌ DON'T: Run untrusted code
:run untrusted_script.py
```

---

## 🤝 Contributing

We welcome contributions! Here's how:

### Contribution Steps

1. **Fork the Repository**

   - Click "Fork" on GitHub

2. **Create Feature Branch**

   ```bash
   git checkout -b feature/your-feature
   ```

3. **Make Changes**

   - Write clean code
   - Follow PEP 8
   - Add type hints
   - Document functions

4. **Test Changes**

   ```bash
   python -m pytest tests/
   ```

5. **Commit with Clear Messages**

   ```bash
   git commit -m "Add: description of changes"
   ```

6. **Push & Open PR**
   ```bash
   git push origin feature/your-feature
   ```

### Areas Needing Help

- 🐛 Bug fixes
- 📚 Documentation
- ✨ New features
- 🧪 Tests
- 🎨 UI improvements
- 🌍 Translations

### Development Setup

```bash
git clone https://github.com/YOUR_USERNAME/CodeForge-AI.git
cd CodeForge-AI

python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1

pip install -r requirements.txt
pip install pytest black flake8

# Format code
black ayuverse/

# Lint code
flake8 ayuverse/

# Run tests
pytest tests/
```

---

## 📝 License

Licensed under **MIT License** - see [LICENSE](LICENSE) file.

**You can:**

- ✅ Use for any purpose
- ✅ Modify and distribute
- ✅ Use commercially
- ✅ Sublicense

**You must:**

- 📋 Include license & copyright notice

---

## 📧 Contact

**Created by:** Ayus Singh
**Email:** ayusingh693@gmail.com
**GitHub:** [@ayusingh-54](https://github.com/ayusingh-54)

### Questions?

- 📖 **Documentation**: See README sections
- 🐛 **Bug Report**: Open GitHub issue
- 💡 **Feature Request**: Create issue with details
- 💬 **Questions**: Email me anytime

### Share Your Experience

I'd love to hear:

- How you're using CodeForge AI
- Feature ideas
- Bug reports
- Success stories
- Feedback

---

<div align="center">

### 🌟 Like CodeForge AI? Star us on GitHub! ⭐

**Built with ❤️ using OpenAI, LangChain, and Python**

**CodeForge AI — Your Intelligent Coding Companion**

_Transform your coding workflow with AI today!_

---

Made by **Ayus Singh** | [ayusingh693@gmail.com](mailto:ayusingh693@gmail.com)

</div>