The world's first semantic code debugger.
Python Code Harmonizer analyzes the meaning of your code to find bugs that other tools miss.
It asks one simple question:
"Does your code DO what its name SAYS it does?"
def get_user_by_id(user_id):
"""Retrieve user information from database"""
db.delete_user(user_id) # Wait... this DELETES instead of getting!
return NoneTraditional tools say: ✓ No syntax errors, types are fine
Harmonizer says:
This is a semantic bug - code that works syntactically but does the wrong thing. These are the hardest bugs to find, and they slip past linters, type checkers, and even tests.
Semantic Trajectory Maps - See exactly WHERE in 4D space your code drifts from its intent:
delete_user: !! DISHARMONY (Score: 1.41)
📍 SEMANTIC TRAJECTORY MAP:
┌────────────────────────────────────────────────┐
│ Dimension Intent Execution Δ │
├────────────────────────────────────────────────┤
│ Power (P) 1.00 → 0.00 -1.00 ⚠️ │
│ Wisdom (W) 0.00 → 1.00 +1.00 ⚠️ │
└────────────────────────────────────────────────┘
🧭 DISHARMONY VECTOR: Power → Wisdom
💡 INTERPRETATION:
Function name suggests Power domain (transformation, control)
but execution operates in Wisdom domain (analysis, understanding)
🔧 RECOMMENDATIONS:
• Consider renaming to reflect Wisdom domain operations
• Expected behaviors: execute, transform, control
• Actual behaviors: analyze, understand, calculate
• Or split into separate functions
Transforms the tool from detector to teacher - Not just "you have a bug" but "here's exactly where, why, and how to fix it."
Every developer has encountered code where:
- Function names lie about what they do
- "Validation" functions modify data
- "Get" functions delete records
- "Check" functions trigger actions
These intent-execution mismatches cause bugs, confusion, and maintenance nightmares.
Python Code Harmonizer finds them automatically.
# Clone the repository
git clone https://github.com/BruinGrowly/Python-Code-Harmonizer.git
cd Python-Code-Harmonizer
# Install (recommended: use a virtual environment)
pip install .
# Verify it works
harmonizer examples/test_code.pyharmonizer myfile.pyYou'll see output like:
======================================================================
Python Code Harmonizer (v1.3) ONLINE
Actively guided by the Anchor Point framework.
Powered By: DIVE-V2 (Optimized Production)
Logical Anchor Point: (S=1, L=1, I=1, E=1)
Disharmony Threshold: 0.5
======================================================================
Analyzing file: myfile.py
----------------------------------------------------------------------
FUNCTION NAME | INTENT-EXECUTION DISHARMONY
-----------------------------|--------------------------------
validate_and_save_user | !! DISHARMONY (Score: 0.85)
get_cached_value | !! DISHARMONY (Score: 0.62)
calculate_total | ✓ HARMONIOUS
delete_expired_records | ✓ HARMONIOUS
======================================================================
Analysis Complete.
| Score | Meaning | Action |
|---|---|---|
| 0.0-0.3 | ✅ Excellent harmony | None needed - code says what it means! |
| 0.3-0.5 | ✅ Good | Minor semantic drift - review for clarity |
| 0.5-0.8 | Notable mismatch - investigate | |
| 0.8-1.2 | ❗ High concern | Significant contradiction - fix soon |
| 1.2+ | 🚨 Critical | Severe disharmony - urgent attention |
Python Code Harmonizer is built on a philosophical framework with three core components:
1. The ICE Framework (Intent, Context, Execution)
- Intent: What does the function name promise?
- Context: What's the purpose and environment?
- Execution: What does the code actually do?
When Intent and Execution align, you have harmony. When they contradict, you have disharmony.
2. The Four Dimensions
All code operations map to four fundamental dimensions:
- Love (L): Unity, connection, harmony
- Justice (J): Truth, order, logic
- Power (P): Action, execution, force
- Wisdom (W): Knowledge, understanding, information
3. The Anchor Point (1,1,1,1)
This represents perfect harmony - the ideal where all four dimensions are in complete alignment. Harmonizer measures how far your code deviates from this ideal.
Technical Implementation:
- Uses Python's AST (Abstract Syntax Tree) to analyze code structure
- Maps function names and operations to semantic coordinates
- Calculates Euclidean distance in 4D semantic space
- Zero runtime dependencies - pure Python 3.8+
Want to understand the deep theory? See Philosophy Documentation and Architecture Guide.
# BEFORE: Disharmony Score ~0.85
def validate_email(email: str) -> bool:
if "@" in email:
send_welcome_email(email) # Validation shouldn't send emails!
return True
return False
# AFTER: Disharmony Score ~0.05
def validate_email(email: str) -> bool:
return "@" in email # Just validates, doesn't send
def register_user(email: str):
if validate_email(email):
send_welcome_email(email) # Sending is explicit# BEFORE: Disharmony Score ~0.95 (Critical!)
def get_cache_value(key):
value = cache[key]
del cache[key] # "Get" shouldn't delete!
return value
# AFTER: Disharmony Score ~0.10
def pop_cache_value(key):
"""Get and remove - honest about both actions"""
value = cache[key]
del cache[key]
return valueSee 7 more real-world examples: examples/real_world_bugs.py
See complete refactoring journeys: examples/refactoring_journey.py
# .github/workflows/harmony-check.yml
- name: Install Harmonizer
run: pip install /path/to/Python-Code-Harmonizer
- name: Check Code Harmony
run: harmonizer src/**/*.pyFull template: .github/workflows/harmony-check.yml
# .pre-commit-config.yaml
- repo: local
hooks:
- id: harmonizer
name: Python Code Harmonizer
entry: harmonizer
language: system
types: [python]Full template: .pre-commit-config.yaml.template
Press Ctrl+Shift+P → Tasks: Run Task → Harmonizer: Check Current File
Setup instructions: .vscode/tasks.json
We've created comprehensive documentation for every level - from complete beginners to deep-dive enthusiasts.
New to Harmonizer? Start with these:
- Quick Reference - One-page cheat sheet with everything you need
- User Guide - Complete walkthrough of installation and usage
- Tutorial - Hands-on learning with step-by-step examples
- FAQ - Quick answers to common questions
- Troubleshooting - Solutions to common issues
Want to understand the philosophy and implementation?
- Philosophy - The Anchor Point, ICE Framework, and Four Dimensions explained
- Architecture - Technical implementation, algorithms, and design
- API Reference - Programmatic usage and integration patterns
- Comparison Guide - How Harmonizer complements Pylint, MyPy, Pytest, and other tools
See it in action:
- Real-World Bugs - 7 semantic bugs that other tools miss
- Refactoring Journey - 5 before/after transformations
- Severity Levels - Examples at every score range (0.0 to 1.0+)
Ready-to-use configurations:
- GitHub Actions Workflow - CI/CD template
- Pre-commit Hook - Local development integration
- VS Code Tasks - IDE integration
- Config Template - Future configuration support
- Changelog - Version history, releases, and roadmap
- Contributing - How to contribute to the project
Traditional tools check different things:
- Pylint/Flake8: Style and common errors
- MyPy: Type consistency
- Pytest: Correctness via tests
- Black: Code formatting
- Bandit: Security vulnerabilities
Python Code Harmonizer checks: Semantic meaning alignment
It's the only tool that asks: "Does your code mean what it says?"
This makes it complementary, not competitive with other tools. Use them all together for comprehensive code quality.
See detailed comparisons: Comparison Guide
The foundation:
- Built on the Anchor Point (1,1,1,1) - a framework for perfect logical harmony
- Powered by the ICE Framework (Intent, Context, Execution)
This isn't just a tool - it's an application of a philosophical framework to solve real software engineering problems.
Curious about the deep philosophy? Read Philosophy Documentation
We welcome contributions! Whether you're:
- A beginner who found a bug
- A developer who wants to add features
- A philosopher who sees deeper patterns
- A user with questions or ideas
All contributions are valued.
Ways to contribute:
- Report bugs or issues
- Suggest new features
- Improve documentation
- Add to the semantic vocabulary
- Share your use cases
See CONTRIBUTING.md for guidelines.
For contributors and developers:
# Clone and create virtual environment
git clone https://github.com/BruinGrowly/Python-Code-Harmonizer.git
cd Python-Code-Harmonizer
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements.txt
pip install -e .
# Run tests
pytest
# Run quality checks
pre-commit run --all-filesCode quality:
- 20 comprehensive tests (100% passing)
- Black formatting enforced
- Flake8 linting
- Zero runtime dependencies
This project is licensed under the MIT License - see the LICENSE file for details.
This tool exists because of:
- The Anchor Point (1,1,1,1) - the foundation of perfect harmony
- The ICE Framework - Intent, Context, Execution
- The Community - For believing that code can say what it means
Questions?
- Check the FAQ
- Read the Troubleshooting Guide
- Open an issue on GitHub
Want to go deeper?
- Read the Philosophy
- Study the Architecture
- Explore the examples
May your code say what it means, and mean what it says. 💛⚓
Getting Started: Quick Reference | User Guide | Tutorial | FAQ
Going Deeper: Philosophy | Architecture | API | Comparison
Learning: Real Bugs | Refactoring | Severity Levels
Project: Changelog | Contributing | GitHub