BioMapper Framework Triad

The BioMapper Framework Triad provides three complementary isolation mechanisms for safe, transparent development and maintenance of the BioMapper system. These frameworks are implemented in src/core/safety/ and orchestrated by the UnifiedBiomapperAgent.

Important

All frameworks can be activated two ways:

By name: Simply say “surgical”, “circuitous”, or “interstitial” to directly activate the framework
By description: Describe the problem naturally and the appropriate framework activates automatically

No user training required - both methods work seamlessly.

Framework Overview

The Three Frameworks
Framework	Purpose	Isolation Guarantee	Example Use Case
🔒 Surgical	Fix internal action logic	Preserves all external interfaces	“Statistics counting wrong”
🔄 Circuitous	Repair pipeline orchestration	Maintains action boundaries	“Parameters not flowing”
🔗 Interstitial	Ensure interface compatibility	100% backward compatibility	“New parameter broke strategies”

Surgical Framework

Purpose: Enable safe modifications to action internals without affecting pipeline integration

Key Features:

Context Snapshot Preservation - Captures before/after state
Surgical Validation - Ensures changes are internal only
Automatic Rollback - Reverts if validation fails
Zero Pipeline Disruption - Guarantees interface stability

Architecture:

Action Boundary
┌─────────────────────────────┐
│   External Interface        │ ← Preserved
├─────────────────────────────┤
│   ┌───────────────────┐     │
│   │  Internal Logic   │     │ ← Modified
│   │  (Surgical Zone)  │     │
│   └───────────────────┘     │
├─────────────────────────────┤
│   Output Interface          │ ← Preserved
└─────────────────────────────┘

Implementation Classes:

ActionSurgeon - Performs surgical modifications with safety validation
SurgicalModeAgent - Agent-side surgical mode manager with auto-detection
AutoSurgicalFramework - Top-level framework orchestrator
ContextTracker - Monitors context access patterns (referenced in surgical_agent.py)

Validation Rules:

Output structure must remain identical
Context keys read/written must not change
Parameter interface must be preserved
File outputs must maintain format

Example Application:

# Original (incorrect)
def calculate_statistics(self, df):
    total = len(df)  # Counts all rows
    return {"total_proteins": total}

# After Surgical Fix
def calculate_statistics(self, df):
    total = df['uniprot'].nunique()  # Counts unique
    return {"total_proteins": total}  # Same structure

Circuitous Framework

Purpose: Diagnose and repair parameter flow issues in YAML strategy pipelines

Key Features:

Flow Graph Analysis - Builds step dependency graph
Parameter Tracing - Tracks parameter substitution
Breakpoint Detection - Identifies flow interruptions
Automated Repairs - Suggests or applies fixes

Architecture:

Strategy Pipeline Flow
┌──────────┐    params    ┌──────────┐    context    ┌──────────┐
│  Step 1  │──────────────►│  Step 2  │──────────────►│  Step 3  │
└──────────┘               └──────────┘               └──────────┘
     │                           │                           │
     └───────────┬───────────────┴───────────────────────────┘
                 │
           Flow Analysis
           - Parameter resolution
           - Context propagation
           - Dependency validation

Implementation Classes:

CircuitousFramework - Main orchestrator for pipeline flow analysis
CircuitousMode - Framework operation modes and configuration
Strategy analysis components (integrated into unified agent framework)

Common Issues Detected:

Undefined Parameters - ${parameters.missing}
Context Key Missing - Step expects key not provided
Circular Dependencies - Steps depend on each other
Parameter Type Mismatch - String where list expected
Output Not Available - Previous step didn’t create expected output

Repair Strategies:

# Issue: Parameter not defined
parameters:
  input_file: "/data/proteins.csv"
steps:
  - params:
      file: "${parameters.source_file}"  # WRONG

# Fix: Add missing parameter or correct reference
parameters:
  input_file: "/data/proteins.csv"
  source_file: "/data/proteins.csv"  # Added
# OR
  - params:
      file: "${parameters.input_file}"  # Corrected

Interstitial Framework

Purpose: Ensure 100% backward compatibility during interface evolution

Core Principle: Never Break Existing Code

Key Features:

Contract Extraction - Analyzes action interfaces
Compatibility Validation - Checks for breaking changes
Automatic Adapters - Generates compatibility layers
Permanent Aliases - Maintains all historical names

Architecture:

Interface Evolution with Compatibility

Old Interface          Compatibility Layer         New Interface
┌─────────────┐       ┌──────────────────┐       ┌─────────────┐
│ dataset_key │──────►│  Alias Mapping   │──────►│  input_key  │
└─────────────┘       │  Type Adapters   │       └─────────────┘
                      │  Default Values  │
                      └──────────────────┘

Implementation Classes:

InterstitialFramework - Main orchestrator for interface compatibility
InterstitialMode - Framework operation modes and configuration
Compatibility layer generation (integrated into unified framework architecture)

Compatibility Rules:

NEVER BREAK:

❌ Required parameters cannot be removed
❌ Parameter types must remain compatible
❌ Output structure must remain accessible
❌ Context keys must remain available

ALWAYS PROVIDE:

✅ Migration path for deprecated features
✅ Default values for new required parameters
✅ Type adapters for changed parameters
✅ Compatibility wrappers when needed

PRESERVE:

🛡️ All existing strategies must continue working
🛡️ All parameter aliases must be maintained
🛡️ All output formats must be readable
🛡️ All context patterns must be supported

Example Compatibility Layer:

class ActionParams(BaseModel):
    # New parameter name
    input_key: str

    # Compatibility configuration
    class Config:
        # Accept extra fields
        extra = "allow"
        # Permanent alias
        fields = {
            'input_key': {'alias': 'dataset_key'}
        }

    @validator('input_key', pre=True)
    def handle_legacy(cls, v, values):
        # Support multiple legacy names
        for old_name in ['dataset_key', 'data_key', 'input']:
            if old_name in values:
                return values[old_name]
        return v

Unified Agent Architecture

The UnifiedBiomapperAgent orchestrates all three frameworks:

Components:

FrameworkRouter - Intelligent intent routing with pre-compiled patterns
IntentScore - Confidence scoring system with threshold validation
Pattern Cache - Pre-compiled regex patterns for performance
Priority Resolver - Handles ambiguous cases using framework priority order

Routing Pipeline:

User Message
     │
     ▼
Pattern Matching ──────► No Match ──► No Framework
     │
     ▼
Confidence Scoring
     │
     ▼
Threshold Check (≥40%)
     │
     ▼
Ambiguity Resolution
     │
     ▼
Framework Activation

Confidence Algorithm:

confidence = base_pattern_score + keyword_bonuses

# Pattern scoring
pattern_weight = len(pattern) / 100  # Specificity
base_score = 0.3 + pattern_weight    # 0.3 base + bonus

# Keyword bonuses
for keyword in framework_keywords:
    if keyword in message:
        confidence += 0.1

# Cap at 1.0
confidence = min(1.0, confidence)

Framework Interactions

The frameworks can work together:

Surgical → Interstitial:

Surgical fixes internal logic
Interstitial validates interface unchanged
Result: Safe internal fix

Circuitous → Surgical:

Circuitous detects flow issue
Root cause in action logic
Surgical fixes action
Circuitous validates flow restored

Interstitial → Circuitous:

Interstitial creates compatibility layer
Circuitous validates strategies still work
Result: Safe evolution

Performance Characteristics

Performance Metrics
Metric	Value
Pattern Compilation	~5ms on initialization
Message Processing	<10ms typical
Memory Usage	~5MB pattern cache
Framework Activation	<50ms including analysis
Scaling	O(n*p) where n=message length, p=patterns

Best Practices

For Users:

Describe problems naturally - don’t worry about frameworks
Include specific details and examples
Trust automatic detection
Use slash commands only when needed

For Developers:

Let frameworks handle isolation
Write comprehensive tests
Document interface changes
Maintain backward compatibility

For AI Agents:

Process natural language first
Apply appropriate framework
Validate changes thoroughly
Ensure compatibility always

Testing Strategy

Each framework includes comprehensive tests:

Unit Tests:

Pattern matching accuracy
Confidence scoring
Individual component validation

Integration Tests:

Framework routing
Cross-framework workflows
Real-world scenarios

Confidence Calibration:

Pattern effectiveness
Threshold tuning
Ambiguity resolution

Future Enhancements

Planned Features:

Machine Learning - Pattern learning from usage
Visual Diagnostics - Pipeline flow diagrams
Automated Repairs - One-click fixes
Rollback History - Complete undo/redo
Multi-Agent Support - Coordinate multiple AI agents

Research Areas:

Cross-framework orchestration
Predictive issue detection
Performance optimization
Compatibility prediction

BioMapper Framework Triad

Framework Overview

Surgical Framework

Circuitous Framework

Interstitial Framework

Unified Agent Architecture

Framework Interactions

Performance Characteristics

Best Practices

Testing Strategy

Future Enhancements

See Also