A growth-oriented assessment platform for candidates. Understand your strengths, track your progress, and get actionable feedback.
⚠️ Active Development: Sono-Eval is in active development. Features are being added and refined, APIs may change, and the system is not yet production-ready. Use at your own risk.
Quick Start • Documentation • Key Features • Usage Examples
Sono-Eval is an assessment system designed to help you understand and grow your skills. Unlike traditional tests that just give you a score, Sono-Eval:
- Explains every score with concrete evidence from your work
- Evaluates multiple dimensions - not just code, but design thinking, collaboration, and problem-solving
- Identifies your strengths and shows you exactly where to improve
- Tracks your growth over time with detailed history
- Provides actionable feedback you can use immediately
For Candidates: Think of it as a helpful coach, not just a grader! For Teams: Get deep insights into skills and growth potential, not just pass/fail.
Get Sono-Eval running in 5 minutes:
# Clone and start
git clone https://github.com/doronpers/sono-eval.git
cd sono-eval
./launcher.sh start
# Access services
# 📚 API Docs: http://localhost:8000/docs
# 📊 Dashboard: http://localhost:8088 (admin/admin)
# 📱 Mobile: http://localhost:8000/mobile# Setup
git clone https://github.com/doronpers/sono-eval.git
cd sono-eval
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .
# Run your first assessment
sono-eval assess run \
--candidate-id demo_user \
--content "def hello(): return 'world'" \
--paths technical- Quick Start Guide - Detailed 5-minute setup
- Installation Guide - All installation options
- API Reference - Complete API docs
- 📖 Clear Explanations - Understand exactly why you received each score
- 🎯 Multiple Paths - Evaluated on technical skills, design thinking, collaboration, and more
- 📈 Track Progress - See how you improve over time
- 💡 Actionable Feedback - Specific recommendations for growth
- 🏆 Identify Strengths - Understand what you're naturally good at
- 📱 Mobile Companion - Complete assessments on any device with guided, interactive experience
- 🔍 Deep Insights - Go beyond surface-level scores
- 📊 Analytics - Visualize candidate performance and cohorts
- ⚖️ Fair Assessment - Consistent, evidence-based evaluation
- 🤝 Better Experience - Candidates learn even if not hired
- 🚀 Easy Setup - Docker deployment in minutes
- 📱 Mobile-Friendly - Candidates can complete assessments anywhere
- Quick Start - 5-minute setup guide
- Installation - Detailed installation for all platforms
- For Candidates - Welcome guide for candidates 👋
- CLI Reference - Complete command-line guide
- API Reference - REST API documentation
- Configuration - Configure for your needs
- Configuration Presets
- Optimized presets for quick setup
- Architecture - System design and components
- Glossary - Comprehensive terminology
- Assessment Path Guide - Complete guide to all assessment paths
- FAQ - Frequently asked questions
- Troubleshooting - Solutions to common issues
- Learning Resources - Tutorials and guides
┌─────────────────────────────────────────────────────────────┐
│ Sono-Eval System │
├─────────────────────────────────────────────────────────────┤
│ Interfaces: CLI │ REST API │ Python SDK │
├─────────────────────────────────────────────────────────────┤
│ Core Engine: │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Assessment │ │ Semantic │ │ Memory │ │
│ │ Engine │ │ Tagging │ │ (MemU) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Storage: PostgreSQL │ Redis │ File System │
├─────────────────────────────────────────────────────────────┤
│ Analytics: Apache Superset Dashboards │
└─────────────────────────────────────────────────────────────┘
See Architecture Overview for details.
Current State (v0.1.0 - Active Development):
- ML Integration: Current "Hybrid" mode is primarily heuristic-driven. ML insights (T5/LoRA) are secondary and require high-compute environments (GPU) to be performant. The heuristic-first approach is currently the most reliable.
- Concurrency:
MemUStorageis currently filesystem-based. While thread-safe for reads, concurrent writes to the same candidate profile may result in data race conditions. Use Redis for high-concurrency needs. - Assessment Retrieval: The
GET /api/v1/assessments/{id}endpoint retrieves assessments from hierarchical memory storage. - Dark Horse Mode: The ML-based "Dark Horse" tracking and T5 tagging are primarily heuristic fallbacks. The documentation accurately reflects current capabilities.
Security Requirements:
SECRET_KEYmust be a 32-byte secure token (validated at startup).- Candidate IDs are strictly sanitized (alphanumeric/dash/underscore only).
- File uploads enforce path traversal protection and content-type verification.
Recommended Configuration:
- Maintain
DARK_HORSE_MODEas "enabled" to track micro-motives (Mastery vs. Efficiency), which reveal more about character than raw scores. - The Heuristic-First approach is currently the most reliable for production use.
# Create a candidate
sono-eval candidate create --id candidate_001
# Run assessment
sono-eval assess run \
--candidate-id candidate_001 \
--file solution.py \
--paths technical design collaboration
# Generate code tags
sono-eval tag generate --file mycode.js --max-tags 5
# Start API server
sono-eval server start --reloadfrom sono_eval.assessment import AssessmentEngine, AssessmentInput, PathType
# Initialize engine
engine = AssessmentEngine()
# Run assessment
result = await engine.assess(AssessmentInput(
candidate_id="candidate_001",
submission_type="code",
content={"code": your_code},
paths_to_evaluate=[PathType.TECHNICAL, PathType.DESIGN]
))
# View results
print(f"Score: {result.overall_score}/100")
print(f"Summary: {result.summary}")
for finding in result.key_findings:
print(f"• {finding}")# Create assessment
curl -X POST http://localhost:8000/api/v1/assessments \
-H "Content-Type: application/json" \
-d '{
"candidate_id": "candidate_001",
"submission_type": "code",
"content": {"code": "def hello(): return \"world\""},
"paths_to_evaluate": ["TECHNICAL"]
}'# Start all services
./launcher.sh start
# View status
./launcher.sh status
# View logs
./launcher.sh logs
# Stop services
./launcher.sh stop# Setup environment
./launcher.sh dev
# Activate virtual environment
source venv/bin/activate
# Run directly
sono-eval assess run --candidate-id test --file test.pySee Installation Guide for detailed instructions.
# Clone repository
git clone https://github.com/doronpers/sono-eval.git
cd sono-eval
# Setup dev environment
./launcher.sh dev
source venv/bin/activate
# Install with dev dependencies
pip install -e ".[dev]"# Run tests
pytest
# With coverage
pytest --cov=src/sono_eval --cov-report=html
# Specific test file
pytest tests/test_assessment.py# Format code
black src/ tests/
# Lint
flake8 src/ tests/
# Type check
mypy src/See Contributing Guide for more details.
We welcome contributions! Whether you're:
- 🐛 Reporting bugs
- 💡 Suggesting features
- 📝 Improving documentation
- 🔧 Submitting code
Read our Contributing Guide to get started.
Sono-Eval is licensed under the MIT License.
You're free to use, modify, and distribute it. See the LICENSE file for details.
- 📚 Documentation: Documentation/README.md
- ❓ FAQ: Documentation/Guides/faq.md
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: support@sono-eval.example
- Explainable assessment engine (heuristic-first)
- Multi-path evaluation
- CLI and REST API
- Docker deployment
- Comprehensive documentation
- Repaired assessment retrieval endpoint
- Timezone-aware datetime handling
- LRU cache eviction for memory storage
- Enhanced security validation
- Real ML-based scoring (not placeholder)
- Batch assessment processing
- Authentication system
- Web UI for reviews
- Enhanced analytics
- Redis-backed memory storage for high concurrency
- Multi-language support
- Plugin system
- Real-time collaboration
- Integration with GitHub/GitLab
- Mobile dashboards
See CHANGELOG.md for version history.
- Dark Horse Model - Based on tex-assist-coding research
- T5 - Google's Text-to-Text Transfer Transformer
- PEFT - Hugging Face Parameter-Efficient Fine-Tuning
- Apache Superset - Modern data exploration platform
- Lines of Code: ~2,500
- Documentation Pages: 15+
- Test Coverage: Core functionality tested
- Docker Services: 4 containers
- API Endpoints: 10+ REST endpoints
- CLI Commands: 15+ commands
Built with ❤️ by the Sono-Eval Team
Version: 0.1.0 | Last Updated: January 2026 | Status: Active Development
CRITICAL: All AI agents MUST read
AGENT_KNOWLEDGE_BASE.mdbefore performing any tasks. It contains non-negotiable Patent, Security, and Design rules.
Additional resources: