sophia-code/README.md

Production-ready agentic CLI code editor with AI-powered coding assistance, planning, and multi-agent delegation. Enterprise-grade security and reliability.

# Sophosic-Coder

<p align="center">
    <img src="https://img.shields.io/badge/Python-3.9%20to%203.12-blue" alt="Python Version">
    <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
    <img src="https://img.shields.io/badge/Code%20Style-Black-black" alt="Code Style">
</p>

A comprehensive codebase for working with various AI coding models and evaluation benchmarks, with seamless integration to the Groq API for powerful code generation and analysis.

## ✨ Features

- 🤖 **Sophia Interactive CLI**: ChatGPT-like terminal interface for coding assistance
- 🚀 **Modern Python Environment**: Virtual environment setup with comprehensive tooling
- 🔐 **Secure API Management**: Environment variable-based configuration for API keys
- ⚡ **Groq API Integration**: Lightning-fast inference with GPT-OSS-120B and other models
- 💬 **Conversation History**: Persistent chat history, resumable sessions, and history compression
- 🔎 **External Info Tools**: Fetch URLs, perform web searches, and pull GitHub issues
- 🧠 **Goal Tracking & Planning**: Maintain session goals and generate step-by-step plans
- 📊 **Comprehensive Evaluation**: Multiple benchmarks and evaluation frameworks
- 🎯 **Model Agnostic**: Clean abstractions that work across different AI providers
- 🛠️ **Developer Tools**: Automated setup, linting, formatting, and testing
- ✍️ **AI-driven File Editing**: Apply code changes with the `/edit` command
- 🧪 **Test Runner**: Run project tests with `/run_tests` and get AI suggestions on failures
- 🌿 **Advanced Git Workflows**: Create and switch branches with `/branch`, merge with `/merge`, and resolve conflicts with AI assistance
- 🛡️ **Permission Controls & Safe Mode**: Configurable policies for file access,
  network calls, and git operations
- 📚 **Extensive Examples**: Ready-to-use examples for various coding tasks

## 🚀 Quick Start

### Option A: Install from NPM (Recommended)

```bash
# Install Sophia globally
npm install -g sophia-code

# Start interactive session
sophia
```

**First Run Setup:**
- Sophia will guide you through API key setup interactively
- Get your free API key from [console.groq.com](https://console.groq.com/)
- That's it! Start coding with AI assistance

### Option B: Clone Repository (Development)

```bash
# Clone the repository
git clone <repository-url>
cd Sophosic-Coder

# Set up environment
./setup.sh

# Configure API key
export GROQ_API_KEY="your_groq_api_key_here"

# Start Sophia
./install.sh  # Install globally
sophia        # Or run locally: PYTHONPATH=src python src/cli.py

# Resume the most recent session
sophia --resume last
```

### Option C: Run Individual Examples
```bash
# Basic completion
python examples/groq-api-client.py

# Streaming completion
python examples/groq-api-streaming.py

# Using the CLI script
python scripts/run_example.py --prompt "write a quicksort algorithm"
```

## 📁 Project Structure

```
Sophosic-Coder/
├── .venv/                 # Virtual environment (gitignored)
├── src/                   # Main application code
│   ├── __init__.py
│   └── groq_client.py     # Groq API client wrapper
├── examples/              # Example scripts
│   ├── groq-api-client.py
│   ├── groq-api-streaming.py
│   └── Groq-API-Setup.md
├── scripts/               # Utility scripts
│   └── run_example.py     # CLI example runner
├── config/                # Configuration files
│   ├── __init__.py
│   └── model_configs.py   # Model configurations
├── demo/                  # Demo applications
├── finetuning/           # Model finetuning utilities
├── qwencoder-eval/       # Evaluation frameworks
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development dependencies
├── pyproject.toml        # Project configuration
├── .env.example          # Environment variables template
├── setup.sh              # Environment setup script
├── Makefile              # Development automation
└── README.md             # This file
```

## 🛠️ Development

### Available Commands (via Makefile)

```bash
# Environment setup
make setup              # Set up development environment
make install           # Install production dependencies  
make install-dev       # Install development dependencies

# Code quality
make format            # Format code with black and isort
make lint              # Run linting with flake8
make type-check        # Run type checking with mypy
make test              # Run tests
make pre-commit        # Run all pre-commit checks

# Examples
make run-example PROMPT="your prompt here"
make run-example-stream PROMPT="your prompt here"

# Utilities
make clean             # Clean temporary files
make help              # Show all available commands
```

### Using Sophia Interactive CLI

Sophia provides a ChatGPT-like experience in your terminal:

```bash
# Install from NPM
npm install -g sophia-code

# Start interactive session
sophia

# First run - Interactive setup:
🔑 Groq API Key Setup Required
===================================
Sophia needs a Groq API key to function.

Would you like to enter your API key now? (y/N): y
Enter your Groq API key: gsk_...
✅ API key saved successfully!

# Then start coding:
👤 You: write a Python function to calculate fibonacci numbers

🤖 Sophia: Here's an efficient Python function to calculate Fibonacci numbers:

def fibonacci(n):
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b
```

**Built-in Commands:**
- `/help` - Show help
- `/clear` - Clear conversation
- `/model` - Change AI model
- `/config` - Show settings
- `/edit` - Apply AI-generated patches to files
- `/exit` - Exit Sophia
- `/goal` - Manage session goals
- `/plan` - Generate or run a task plan

### Planning & Goals

Sophia can track your objectives and break down complex work:

- Use `/goal add <text>` to record a goal, `/goal list` to view all goals, and `/goal clear` to reset.
- Request a plan with `/plan <task>` and execute it step by step using `/plan run`.

These tools help Sophia stay focused on long-term tasks and not lose context.

### Subagents

Sophia can delegate tasks to specialized *subagents*. Define them with YAML
files inside `.sophia/agents` (project-level) or `~/.sophia/agents`
(user-level):

```yaml
name: code-reviewer
description: Provide detailed code reviews focusing on potential bugs.
system_prompt: |
  You are an expert code reviewer. Be concise and precise.
tools:
  - /read
  - /ls
```

Invoke a subagent explicitly:

```
/agent code-reviewer Please review utils.py
```

The subagent runs with its own system prompt and only the tools listed in its
configuration.

### Using the Groq Client (Programmatically)

```python
from src.groq_client import GroqClient

# Initialize client (uses GROQ_API_KEY env var)
client = GroqClient()

# Simple completion
response = client.simple_completion("Write a Python function to calculate fibonacci numbers")

# Streaming completion
for chunk in client.simple_completion("Explain Python decorators", stream=True):
    print(chunk, end="", flush=True)

# Custom configuration
client = GroqClient(
    model="openai/gpt-oss-120b",
    temperature=0.7,
    max_tokens=4096
)
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file from `.env.example`:

```bash
# Required
GROQ_API_KEY=your_groq_api_key_here

# Optional
DEFAULT_MODEL=openai/gpt-oss-120b
DEFAULT_TEMPERATURE=1.0
DEFAULT_MAX_TOKENS=8192
DEFAULT_TOP_P=1.0
DEFAULT_REASONING_EFFORT=medium
```

### Model Configuration

Models are configured in `config/model_configs.py`. You can:

- Add new model configurations
- Modify default parameters
- List available models:

```python
from config import list_available_models
print(list_available_models())
```

### Permissions & Safe Mode

Operations can be controlled through `~/.sophia/config.json`:

```json
{
  "permissions": {
    "write_file": "allow",
    "shell": "ask",
    "http": "deny"
  }
}
```

Permission values:

- `allow` – run without prompting
- `ask` – require confirmation before execution
- `deny` – block the operation

Enable safe mode with `/safe on` to apply a restrictive profile where file
writes and git operations require approval while network and shell commands are
denied. All permission decisions are appended to `~/.sophia/audit.log` for
auditing.

## 📊 Evaluation Frameworks

Sophosic-Coder includes comprehensive evaluation frameworks:

- **BigCodeBench**: Code generation benchmarks
- **HumanEval**: Programming problem solving
- **McEval**: Multi-language code evaluation  
- **CruxEval**: Code understanding and reasoning
- **Multiple language evaluation**: Support for 358+ programming languages

See the `qwencoder-eval/` directory for detailed evaluation tools and benchmarks.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Install development dependencies (`make install-dev`)
4. Make your changes
5. Run pre-commit checks (`make pre-commit`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- [Groq](https://groq.com/) for providing fast inference infrastructure
- The open-source community for various evaluation frameworks and tools
- Contributors to the codebase evaluation benchmarks

## 📞 Support

- 🐛 [Report Issues](https://github.com/sophosic-coder/sophosic-coder/issues)
- 💬 [Discussions](https://github.com/sophosic-coder/sophosic-coder/discussions)
- 📖 [Documentation](https://sophosic-coder.readthedocs.io/)

---

<p align="center">
    Made with ❤️ by the Sophosic-Coder Team
</p># sophia-code