Sophosic-Coder

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)

# 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
• That's it! Start coding with AI assistance

Option B: Clone Repository (Development)

# 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

# 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)

# 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:

# 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):

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)

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:

# 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:

from config import list_available_models
print(list_available_models())

Permissions & Safe Mode

Operations can be controlled through ~/.sophia/config.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 for providing fast inference infrastructure
• The open-source community for various evaluation frameworks and tools
• Contributors to the codebase evaluation benchmarks

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation