Oracle Middleware¶

The Oracle Resilience Middleware provides automatic error recovery and intelligent suggestions to help AI agents recover from common mistakes.

Overview¶

When an AI agent makes a mistake (typo in function name, wrong file path), the Oracle middleware:

Detects the error type
Analyzes the context
Suggests corrections
Optionally auto-retries with the correction

graph LR
    A[AI Request] --> B[Code Scalpel]
    B --> C{Error?}
    C -->|No| D[Return Result]
    C -->|Yes| E[Oracle Middleware]
    E --> F[Fuzzy Match]
    E --> G[Path Resolve]
    E --> H[Syntax Suggest]
    F --> I[Recovery Options]
    G --> I
    H --> I
    I --> J[Enhanced Error Response]

Features¶

1. Symbol Fuzzy Matching¶

Corrects typos in function/class names:

Request with typo:

{
  "tool": "extract_code",
  "params": {
    "target_name": "procss_order",
    "target_type": "function"
  }
}

Enhanced error response:

{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'procss_order' not found"
  },
  "oracle": {
    "recovery_attempted": true,
    "method": "levenshtein_fuzzy_match",
    "suggestions": [
      {"name": "process_order", "confidence": 0.93, "distance": 1},
      {"name": "process_orders", "confidence": 0.85, "distance": 2}
    ],
    "best_match": "process_order",
    "auto_retry_available": true
  }
}

2. Path Resolution¶

Suggests correct file paths:

Request with wrong path:

{
  "tool": "analyze_code",
  "params": {
    "file_path": "src/servics/order.py"
  }
}

Enhanced response:

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found: src/servics/order.py"
  },
  "oracle": {
    "suggestions": [
      {"path": "src/services/order.py", "confidence": 0.95},
      {"path": "src/services/orders.py", "confidence": 0.80}
    ],
    "workspace_hint": "Similar files found in src/services/"
  }
}

3. Syntax Error Hints¶

Helps fix code syntax:

{
  "error": {
    "code": "PARSE_ERROR",
    "message": "Syntax error at line 15"
  },
  "oracle": {
    "syntax_hint": "Missing closing parenthesis",
    "line": 15,
    "column": 28,
    "context": "def foo(bar:",
    "suggestion": "def foo(bar):"
  }
}

Configuration¶

Enable/Disable Oracle¶

In .code-scalpel/config.json:

{
  "oracle": {
    "enabled": true,
    "auto_retry": false,
    "fuzzy_threshold": 0.8,
    "max_suggestions": 3
  }
}

Options¶

Option	Type	Default	Description
`enabled`	bool	true	Enable Oracle middleware
`auto_retry`	bool	false	Auto-retry with best match
`fuzzy_threshold`	float	0.8	Minimum confidence for suggestions
`max_suggestions`	int	3	Maximum recovery options

Recovery Methods¶

Levenshtein Distance¶

For symbol name typos:

# Calculates edit distance between strings
# "procss_order" → "process_order" = distance 1

Distance	Confidence
1	0.90-0.95
2	0.80-0.90
3	0.70-0.80
>3	Not suggested

Path Similarity¶

For file path errors:

# Compares path components
# "src/servics/order.py" → "src/services/order.py"

Syntax Analysis¶

For parse errors:

# Analyzes AST error location
# Suggests common fixes (missing colons, parentheses, etc.)

Using Oracle Responses¶

Python¶

def call_with_recovery(tool, params):
    response = call_tool(tool, params)

    if response.get("error") and response.get("oracle"):
        oracle = response["oracle"]

        if oracle.get("auto_retry_available"):
            # Auto-retry with best suggestion
            best = oracle["best_match"]
            params["target_name"] = best
            return call_tool(tool, params)

        elif oracle.get("suggestions"):
            # Present suggestions to AI
            suggestions = oracle["suggestions"]
            return {"error": response["error"], "suggestions": suggestions}

    return response

TypeScript¶

interface OracleRecovery {
  recovery_attempted: boolean;
  method: string;
  suggestions: Array<{
    name?: string;
    path?: string;
    confidence: number;
  }>;
  best_match?: string;
  auto_retry_available: boolean;
}

async function callWithRecovery(tool: string, params: any) {
  const response = await callTool(tool, params);

  if (response.error && response.oracle?.auto_retry_available) {
    params.target_name = response.oracle.best_match;
    return callTool(tool, params);
  }

  return response;
}

Stage 2 Enhancement¶

Oracle also enhances errors in data.error:

{
  "data": {
    "error": {
      "code": "SYMBOL_NOT_FOUND",
      "message": "Class 'UserServce' not found"
    }
  },
  "oracle": {
    "enhanced": true,
    "original_error": "data.error",
    "suggestions": [
      {"name": "UserService", "confidence": 0.95}
    ]
  }
}

Token Efficiency¶

Oracle adds minimal overhead:

Component	Tokens
Error without Oracle	~50
Error with Oracle	~100-150
Recovery suggestions	~30 per suggestion

Tier Availability¶

Feature	Community	Pro	Enterprise
Basic Oracle	✅	✅	✅
Fuzzy matching	✅	✅	✅
Path suggestions	✅	✅	✅
Auto-retry	❌	✅	✅
Custom thresholds	❌	✅	✅
Audit logging	❌	❌	✅

Best Practices¶

Trust Oracle suggestions - High confidence (>0.9) is usually correct
Enable auto-retry cautiously - May cause unexpected behavior
Log recoveries - Track common mistakes for improvement
Adjust thresholds - Lower for typo-prone codebases
Present options - Let AI choose from suggestions when uncertain