Development Guide

Complete guide for setting up a development environment and contributing to voria.

Quick Dev Setup


bash
# 1. Clone repo
git clone https://github.com/Srizdebnath/voria.git
cd voria

# 2. Set up Rust
rustup update

# 3. Build Rust
cd rust
cargo build
cargo test
cd ..

# 4. Set up Python
python3 -m venv venv
source venv/bin/activate

# 5. Install Python dev dependencies
cd python
pip install -e ".[dev]"
cd ..

# 6. Verify everything
./target/debug/voria --version
python3 -m voria.engine < /dev/null

Project Structure


terminal
voria/
├── rust/                         # Rust CLI
│   ├── Cargo.toml               # Rust dependencies
│   ├── src/
│   │   ├── main.rs              # Entry point
│   │   ├── cli/mod.rs           # Subcommands
│   │   ├── ipc/mod.rs           # NDJSON protocol
│   │   ├── orchestrator/mod.rs  # Workflow
│   │   ├── ui/mod.rs            # Terminal UI
│   │   └── config/mod.rs        # Config loading
│   └── target/                  # Build output
│
├── python/                       # Python engine
│   ├── setup.py                 # Python package config
│   ├── voria/
│   │   ├── __init__.py
│   │   ├── engine.py            # Main loop
│   │   ├── core/
│   │   │   ├── llm/             # LLM providers
│   │   │   ├── patcher/         # Patching logic
│   │   │   ├── executor/        # Test execution
│   │   │   ├── agent/           # Agent loop
│   │   │   ├── github/          # GitHub API
│   │   │   ├── token_manager/   # Cost tracking
│   │   │   └── setup.py         # Configuration
│   │   └── plugins/             # Language plugins
│   └── tests/                   # Python tests
│
├── docs/                         # Documentation ( New!)
│   ├── README.md
│   ├── QUICKSTART.md
│   ├── USER_GUIDE.md
│   ├── EXAMPLES.md
│   ├── ARCHITECTURE.md
│   ├── IPC_PROTOCOL.md
│   ├── DESIGN_DECISIONS.md
│   ├── MODULES.md
│   ├── DEVELOPMENT.md            # This file
│   ├── CONTRIBUTING.md
│   ├── PLUGINS.md
│   ├── LLM_INTEGRATION.md
│   ├── PERFORMANCE.md
│   ├── SECURITY.md
│   ├── TROUBLESHOOTING.md
│   └── ROADMAP.md
│
└── test_*.py                     # Integration tests

Development Workflow

Rust Development

Build & Test:


bash
cd rust
cargo build               # Debug binary
cargo build --release    # Optimized binary
cargo test              # Run tests
cargo check             # Quick type check

Code Quality:


bash
cargo fmt               # Format code
cargo clippy            # Linting
cargo doc --open        # Documentation

Debug Logging:


bash
RUST_LOG=debug cargo run -- plan 1
RUST_LOG=voria=trace cargo run -- plan 1  # Module-specific

Python Development

Activate Environment:


bash
source venv/bin/activate
cd python

Install & Test:


bash
pip install -e .         # Editable install (dev mode)
pip install -e ".[dev]"  # With dev dependencies
pytest -v               # Run tests with verbose
pytest --cov            # Generate coverage report

Code Quality:


bash
black .                 # Format code
black --check .         # Check without formatting
mypy .                  # Type checking
pylint voria/         # Linting

Manual Testing:


bash
# Test engine directly
python3 -m voria.engine

# Test specific module
python3 -c "from voria.core.llm import ModelDiscovery; print('Import OK')"

# Run single test
pytest tests/test_llm.py::test_discover_models -v

🔨 Making Changes

Adding a New Command

Step 1: Add Rust side (

terminal

rust/src/cli/mod.rs

)


rust
pub async fn handle_new_command(args: <Args>) -> Result<()> {
    let request = json!({
        "command": "new_command",
        "args": args
    });
    // Send request to Python...
}

Step 2: Add Python side (

terminal

python/voria/engine.py

)


python
async def on_new_command(data):
    # Handle the command
    result = await process_command(data)
    return {"status": "success", "result": result}

Step 3: Test


bash
./target/debug/voria new-command --args

Adding a New LLM Provider

Step 1: Create provider file (

terminal

python/voria/core/llm/kimi.py

)


python
from .base import BaseLLMProvider

class KimiProvider(BaseLLMProvider):
    async def plan(self, issue_desc: str) -> str:
        # Implementation
        pass

Step 2: Register in factory (

terminal

python/voria/core/llm/__init__.py

)


python
from .kimi import KimiProvider
LLMProviderFactory.register("kimi", KimiProvider)

Step 3: Test


python
provider = LLMProviderFactory.create("kimi", api_key, "model")
result = await provider.plan("Test issue")

Adding Plugin Support

Step 1: Create plugin (

terminal

python/voria/plugins/go/executor.py

)


python
class GoTestExecutor:
    async def run(self, path: str) -> TestSuiteResult:
        # Run go test ./...
        pass

Step 2: Register in detector (

terminal

python/voria/core/executor/executor.py

)


python
async def detect_framework(self):
    if Path("go.mod").exists():
        return "go"

Step 3: Test


python
executor = TestExecutor("/go-repo")
framework = await executor.detect_framework()  # Should be "go"

Testing

Running Tests


bash
# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_llm.py -v

# Specific test
pytest tests/test_llm.py::test_discover_models -v

# With coverage
pytest tests/ --cov=voria --cov-report=html

# Watch mode (needs pytest-watch)
ptw tests/

Integration Tests


bash
# Full CLI test
python3 test_voria_cli.py

# Phase 2 integration test
python3 test_phase2_integration.py

# End-to-end
./target/debug/voria plan 1

Writing Tests

Python test example:


python
import pytest
from voria.core.llm import ModelDiscovery

@pytest.mark.asyncio
async def test_discover_openai_models():
    """Test fetching OpenAI models"""
    models = await ModelDiscovery._get_openai_fallback()
    assert len(models) > 0
    assert any("gpt-" in m.name for m in models)

🔧 Debugging Tips

Enable Detailed Logging

Rust:


bash
RUST_LOG=debug ./target/debug/voria -v plan 1

Python:


bash
python3 -m voria.engine  # Logs go to stderr automatically

Inspect NDJSON Protocol

See what Rust sends:


bash
strace -e write ./target/debug/voria plan 1 2>&1 | grep '"command"'

See what Python receives/sends:


bash
python3 -c '
import sys, json
for line in sys.stdin:
    msg = json.loads(line)
    print("Received:", json.dumps(msg, indent=2))
' <<< '{"command":"plan","issue_id":1}'

Test Python Engine Directly


bash
(
  echo '{"command":"plan","issue_id":1}'
  sleep 0.5
  echo '{"command":"plan","issue_id":2}'
) | python3 -m voria.engine

Breakpoint Debugging

Python:


python
import pdb; pdb.set_trace()  # Stop here

Rust:


rust
dbg!(variable);  // Print variable

Running Specific Scenarios

Test LLM Discovery


bash
python3 << 'EOF'
import asyncio
from voria.core.llm import ModelDiscovery

async def test():
    models = await ModelDiscovery.discover_all("openai", "sk-test")
    for m in models:
        print(f"{m.name}: {m.display_name}")

asyncio.run(test())
EOF

Test Patching


bash
python3 << 'EOF'
import asyncio
import tempfile
from pathlib import Path
from voria.core.patcher import CodePatcher

async def test():
    with tempfile.TemporaryDirectory() as tmpdir:
        # Create test file
        test_file = Path(tmpdir) / "test.py"
        test_file.write_text("print('hello')")
        
        # Apply patch
        patcher = CodePatcher(tmpdir)
        patch = """--- a/test.py
+++ b/test.py
@@ -1 +1 @@
-print('hello')
+print('world')
"""
        result = await patcher.apply_patch(patch)
        print("Result:", result)
        print("Content:", test_file.read_text())

asyncio.run(test())
EOF

Test Agent Loop


bash
python3 << 'EOF'
import asyncio
from voria.core.agent import AgentLoop

async def test():
    loop = AgentLoop("modal", "test-key", "/repo")
    await loop.initialize("zai-org/GLM-5.1-FP8")
    result = await loop.run(42, "Fix the bug")
    print(result)

asyncio.run(test())
EOF

Code Style Guidelines

Python


python
# Type hints on all functions
def process_data(value: str) -> Dict[str, Any]:
    """Detailed docstring.
    
    Args:
        value: Description
        
    Returns:
        Description
        
    Raises:
        ValueError: When...
    """
    pass

# Use f-strings
message = f"Processing {value}"

# Use type hints in class
from typing import Optional

class MyClass:
    value: Optional[str] = None

Rust


rust
/// Document public APIs
/// 
/// # Errors
/// Returns error if...
pub async fn process() -> Result<()> {
    Ok(())
}

// Use meaningful variable names
let is_valid = check_validity();

// Comments for non-obvious logic
// This happens because of X (see issue #123)

Committing Code

Conventional Commits

Format:


terminal
<type>(<scope>): <subject>

<body>

Fixes #<issue>

Types:

▶
terminal
```
feat
```
- New feature
▶
terminal
```
fix
```
- Bug fix
▶
terminal
```
docs
```
- Documentation
▶
terminal
```
refactor
```
- Code restructuring
▶
terminal
```
perf
```
- Performance improvement
▶
terminal
```
test
```
- Test additions
▶
terminal
```
chore
```
- Build, dependencies

Examples:


terminal
feat(llm): add Kimi provider support
fix(patcher): handle multi-file diffs correctly
docs: update LLM integration guide
refactor(agent): simplify iteration logic
perf: optimize token counting
test: add test cases for edge cases

Pre-commit Checklist

▶
Code passes
terminal
```
cargo fmt
```
and
terminal
```
black
```
▶ Tests pass locally
▶
No new warnings from
terminal
```
cargo clippy
```
▶
Python types check with
terminal
```
mypy
```
▶ Updated docs if needed
▶ Commit message follows conventions

Release Process

Version Bumping


bash
# Update version in Cargo.toml and setup.py
# Tag release
git tag v0.2.0
git push origin v0.2.0

###Build Release Binary


bash
cd rust
cargo build --release
# Binary at: target/release/voria

Common Issues

"Cargo not found"


bash
curl --proto '=https' --tlsvv0.0.3 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

"Python import error"


bash
# Reinstall
cd python
pip uninstall voria
pip install -e .

"Test failures"


bash
# Run with verbose traceback
pytest tests/ -v -s --tb=long

Contributing Workflow

▶Fork repository
▶
Create feature branch:
terminal
```
git checkout -b feature/my-feature
```
▶Make changes and commit with conventional commits
▶
Run tests:
terminal
```
pytest && cargo test
```
▶
Push:
terminal
```
git push origin feature/my-feature
```
▶Create Pull Request
▶Address review feedback
▶Merge when approved

Need Help? Check TROUBLESHOOTING.md or ask in discussions.

Join our WhatsApp Support Group: Click Here