Skip to content

COGNITIVE_CODING_ENGINE_README.md

Latest commit

 

History

History
187 lines (144 loc) · 8.73 KB

COGNITIVE_CODING_ENGINE_README.md

File metadata and controls

187 lines (144 loc) · 8.73 KB
Raw

🧠 FRIDAY Cognitive Coding Engine — Implementation Complete

What THIS ?

A complete cognitive coding intelligence layer for FRIDAY that transforms her from a "generate → run → fix" loop into a system that thinks like an expert programmer. 5 new modules totaling 3,563 lines of Python, plus full integration into main.py.

Architecture

User Goal
    │
    ▼
┌─────────────────────────────────────────────────────┐
│              COGNITIVE CODER (Orchestrator)          │
│         actions/cognitive_coder.py (748 lines)       │
│                                                      │
│  Pipeline: Perceive → Plan → Simulate → Execute →   │
│            Debug → Reflect → Consolidate             │
└──────────┬──────┬──────┬──────┬──────┬──────────────┘
           │      │      │      │      │
    ┌──────▼──┐ ┌─▼───┐ ┌▼────┐ ┌▼───┐ ┌▼──────────┐
    │ Code    │ │Code │ │Code │ │Code│ │ code_helper│
    │ Intel   │ │Plan │ │Sim  │ │Ref │ │ dev_agent  │
    │ (894L)  │ │(609)│ │(631)│ │(681)│ │ (existing) │
    └─────────┘ └─────┘ └─────┘ └─────┘ └────────────┘

Modules

1. brain/code_intelligence.py — Semantic Code Understanding (894 lines)

What it does: The "perception" layer. Builds a semantic graph of codebases and maintains a chunk memory of code patterns — like an expert programmer's 50,000 mental chunks.

Key features:

  • AST Parser: Parses Python files into structural components (classes, functions, imports, decorators)
  • Codebase Graph: Builds a dependency graph (file → class → method → function) with import edges
  • Chunk Memory: Stores code patterns (design patterns, idioms, algorithms) with success tracking
  • Pattern Recognition: Identifies 15+ patterns (factory, observer, strategy, MVC, retry/backoff, etc.)
  • Complexity Analysis: Cyclomatic + cognitive complexity, nesting depth, parameter count
  • Impact Analysis: "What would break if I change this file?" — traces dependency chains
  • Semantic Search: Search the graph by name, type, or property

2. brain/code_planner.py — Hierarchical Goal Decomposition (609 lines)

What it does: The "planning" layer. Decomposes complex coding goals into subgoals using Active Inference (Free Energy Principle) to select the optimal plan.

Key features:

  • LLM-Assisted Decomposition: Breaks goals into 3-7 subgoals with concrete steps
  • EFE Calculation: Expected Free Energy scoring for each subgoal:
    • Expected cost (time/effort)
    • Expected risk (failure probability)
    • Information gain (learning potential)
    • Goal relevance
    • Complexity penalty
  • Mentally Simulates each step before execution — predicts success, errors, side effects
  • Adaptive Replanning: Monitors prediction errors, triggers replan when errors accumulate
  • Prior Retrieval: Queries chunk memory for known patterns before planning

3. brain/code_simulator.py — Predictive Execution Sandbox (631 lines)

What it does: The "simulation" layer. Mentally executes code before running it, detecting anomalies and predicting errors.

Key features:

  • 13 Bug Pattern Detectors: off-by-one, mutable defaults, bare except, unbounded recursion, race conditions, resource leaks, SQL injection, hardcoded secrets, blocking calls in async, infinite loops, unhandled None, type confusion, unused variables
  • LLM Simulation: Predicts: would it run? what output? what errors? what edge cases?
  • Performance Prediction: Time/space complexity estimation, bottleneck identification
  • Execution Path Tracing: Step-by-step execution path with branch probabilities
  • Error Fix Prediction: Given an error, predicts root cause and suggests fix
  • Anomaly Database: Persistent storage of detected anomalies with resolution tracking

4. brain/code_reflector.py — Failure Analysis & Learning (681 lines)

What it does: The "reflection" layer. Analyzes failures, builds root-cause trees, and learns debugging procedures from experience.

Key features:

  • Root-Cause Analysis: LLM-powered hypothesis generation ranked by probability
  • Hypothesis Ranking: Combines LLM reasoning with historical pattern matching
  • Failure Pattern Library: Builds a persistent database of known bugs + proven fixes
  • Debugging Strategy Selection: Picks the best approach per error type (binary search, type trace, scope trace, etc.)
  • Failure Replay: Re-examines past failures with new knowledge
  • Procedural Learning: Successful fixes automatically become reusable procedures
  • Cross-Module Learning: Records in learning engine + procedural memory

5. actions/cognitive_coder.py — Master Orchestrator (748 lines)

What it does: Wires all 4 brain modules + existing code_helper/dev_agent into a unified cognitive coding pipeline.

9 Actions:

Action Description
build Full cognitive pipeline: plan → simulate → execute → debug → reflect
analyze Build codebase semantic graph + parse structure
plan Generate execution plan without executing (shows EFE scores)
simulate Predict code behavior + anomaly detection before running
debug Root-cause analysis with hypothesis ranking
refactor Complexity analysis + improvement suggestions
review Deep code review combining all cognitive modules
explain Explain code with cognitive context + pattern recognition
status Get cognitive system status

Integration into main.py

6 changes applied to main.py:

  1. Imports (line ~220): 5 new import blocks for cognitive modules
  2. Tool Declaration (line ~1300): cognitive_code tool with 7 parameters
  3. Tool Handler (line ~3476): @register_tool("cognitive_code") with 300s timeout
  4. Prompt Injection (line ~1870): Injects code intelligence, planner, simulator, reflector state into Gemini's system prompt
  5. Module Init (line ~1500): Logs cognitive module status on startup
  6. Shutdown Save (line ~4294): Persists all cognitive state on window close

How It Works (Example: "Build a REST API for user management")

1. PERCEIVE: Scans existing codebase, builds semantic graph
   → "Found 12 files, 3 classes, 15 functions. Pattern: Flask routes detected."

2. PLAN: Decomposes into subgoals with EFE scores
   → sg1: Design data model (EFE=0.23)
   → sg2: Create API routes (EFE=0.31)
   → sg3: Add authentication (EFE=0.45)
   → sg4: Write tests (EFE=0.28)

3. SIMULATE: Predicts each step
   → "sg3 has high risk — JWT implementation error-prone"
   → Anomaly: hardcoded secret detected in template

4. EXECUTE: Writes code using dev_agent/code_helper

5. DEBUG (if errors): Root-cause analysis
   → "TypeError in line 42: likely cause is None user_id (p=0.7)"
   → Fix strategy: add None check before database query

6. REFLECT: Learns from the session
   → "Pattern: REST API + auth → always add None guards"
   → Stored as failure pattern + procedural memory

Files Modified/Created

File Action Lines
brain/code_intelligence.py NEW 894
brain/code_planner.py NEW 609
brain/code_simulator.py NEW 631
brain/code_reflector.py NEW 681
actions/cognitive_coder.py NEW 748
main.py MODIFIED +102 lines (6 integration points)
cognitive_coding_integration.py NEW (reference) 230

Testing

All 5 new modules pass Python AST syntax verification:

✅ brain/code_intelligence.py
✅ brain/code_planner.py
✅ brain/code_simulator.py
✅ brain/code_reflector.py
✅ actions/cognitive_coder.py
✅ main.py (modified)

What This Enables

FRIDAY can:

  • 🧠 Understand codebases semantically (AST graphs, dependency analysis, pattern recognition)
  • 📋 Plan complex tasks hierarchically with predicted outcomes (EFE minimization)
  • 🔮 Simulate code before running it (anomaly detection, error prediction)
  • 🔍 Debug failures with root-cause analysis and hypothesis ranking
  • 📚 Learn from every coding session (failure patterns, procedural memory)
  • ♻️ Adapt plans when predictions fail (adaptive replanning)
  • 🏗️ Recognize design patterns and code idioms (chunk memory)
  • 📊 Analyze complexity and suggest refactoring