adaptive-memory-multi-model-router 2.14.45 → 2.14.47

package/docs/LLM_COUNCIL_DECISION.md

@@ -1,508 +0,0 @@
-#!/usr/bin/env python3
-"""
-TMLPD Improvement Council - Multi-LLM Decision Making
-
-Uses multiple AI providers to analyze, debate, and vote on
-the best improvement path for TMLPD v2.0.
-
-Council Members:
-1. Anthropic Claude (Architectural perspective)
-2. OpenAI GPT-4 (Practical implementation)
-3. Google Gemini (Research alignment)
-4. Cerebras Llama (Cost/benefit analysis)
-"""
-
-import asyncio
-import json
-from datetime import datetime
-from pathlib import Path
-from typing import Dict, List, Any
-
-# Mock implementations (in real system, use actual API calls)
-class CouncilMember:
-    """A council member with specific perspective"""
-
-    def __init__(self, name: str, provider: str, perspective: str):
-        self.name = name
-        self.provider = provider
-        self.perspective = perspective
-
-    async def deliberate(self, proposals: List[Dict]) -> Dict[str, Any]:
-        """
-        Analyze proposals and provide recommendations
-
-        Returns: Ranking with reasoning
-        """
-        # In production, call actual LLM API
-        # For now, return perspective-based analysis
-
-        analysis = {
-            "member": self.name,
-            "provider": self.provider,
-            "perspective": self.perspective,
-            "rankings": [],
-            "reasoning": ""
-        }
-
-        # Different perspectives weight factors differently
-        if self.perspective == "architectural":
-            # Prioritize: System design, scalability, maintainability
-            priority_factors = ["scalability", "maintainability", "abstraction"]
-            analysis["reasoning"] = (
-                "Focus on solid architectural foundations that enable "
-                "future growth. Multi-provider system and difficulty-aware "
-                "routing provide the best extensibility."
-            )
-
-        elif self.perspective == "practical":
-            # Prioritize: Implementation speed, user value, quick wins
-            priority_factors = ["implementation_speed", "user_value", "quick_wins"]
-            analysis["reasoning"] = (
-                "Prioritize features that provide immediate user value. "
-                "CLI interface and error handling give instant usability "
-                "improvements."
-            )
-
-        elif self.perspective == "research":
-            # Prioritize: Research backing, innovation, alignment with trends
-            priority_factors = ["research_support", "innovation", "trend_alignment"]
-            analysis["reasoning"] = (
-                "Emphasize improvements with strong research backing. "
-                "Advanced memory systems and difficulty-aware routing have "
-                "solid arXiv validation."
-            )
-
-        elif self.perspective == "cost_benefit":
-            # Prioritize: Cost reduction, ROI, efficiency
-            priority_factors = ["cost_savings", "roi", "efficiency"]
-            analysis["reasoning"] = (
-                "Focus on improvements that reduce operational costs and "
-                "increase efficiency. Multi-provider routing enables 40-60% "
-                "cost reduction (MONK benchmarks)."
-            )
-
-        # Score each proposal
-        for proposal in proposals:
-            score = self._score_proposal(proposal, priority_factors)
-            analysis["rankings"].append({
-                "proposal": proposal["name"],
-                "score": score,
-                "justification": self._justify_score(proposal, score)
-            })
-
-        # Sort by score
-        analysis["rankings"].sort(key=lambda x: x["score"], reverse=True)
-
-        return analysis
-
-    def _score_proposal(self, proposal: Dict, factors: List[str]) -> float:
-        """Score a proposal based on perspective factors"""
-        score = 0.0
-
-        # Base score from value rating
-        score += proposal.get("value", 0) * 20  # 0-100 points
-
-        # Adjust for effort (lower effort = better)
-        effort_days = proposal.get("effort_days", 5)
-        score += (10 - effort_days) * 5  # Prefer quicker implementations
-
-        # Research backing boost
-        if proposal.get("research_backed"):
-            if "research" in factors:
-                score += 15
-
-        # Impact boost
-        impact = proposal.get("impact", 0)
-        if impact >= 4 and "user_value" in factors:
-            score += 10
-
-        return min(score, 100)
-
-    def _justify_score(self, proposal: Dict, score: float) -> str:
-        """Generate justification for the score"""
-        justifications = []
-
-        if score >= 80:
-            justifications.append("Critical priority")
-        elif score >= 60:
-            justifications.append("High priority")
-        elif score >= 40:
-            justifications.append("Medium priority")
-        else:
-            justifications.append("Lower priority")
-
-        if proposal.get("research_backed"):
-            justifications.append("Strong research support")
-
-        if proposal.get("effort_days", 5) <= 2:
-            justifications.append("Quick to implement")
-
-        return ", ".join(justifications)
-
-
-class ImprovementCouncil:
-    """Council of AI experts for decision making"""
-
-    def __init__(self):
-        self.members = [
-            CouncilMember(
-                name="Claude (Architect)",
-                provider="anthropic",
-                perspective="architectural"
-            ),
-            CouncilMember(
-                name="GPT-4 (Pragmatist)",
-                provider="openai",
-                perspective="practical"
-            ),
-            CouncilMember(
-                name="Gemini (Researcher)",
-                provider="google",
-                perspective="research"
-            ),
-            CouncilMember(
-                name="Llama (Cost Analyst)",
-                provider="cerebras",
-                perspective="cost_benefit"
-            )
-        ]
-
-        self.proposals = [
-            {
-                "name": "Multi-Provider System with Health Monitoring",
-                "effort_days": 3,
-                "value": 5,
-                "impact": 5,
-                "research_backed": True,
-                "citations": [
-                    "https://arxiv.org/html/2506.12508v1",
-                    "https://arxiv.org/abs/2511.15755"
-                ],
-                "description": "Enable switching between Anthropic, OpenAI, Cerebras, etc. with health monitoring and automatic failover. MONK benchmarks show 40-60% cost reduction."
-            },
-            {
-                "name": "Difficulty-Aware Routing",
-                "effort_days": 2,
-                "value": 5,
-                "impact": 5,
-                "research_backed": True,
-                "citations": [
-                    "https://arxiv.org/html/2509.11079v2"
-                ],
-                "description": "Classify tasks by difficulty (trivial/simple/medium/complex/expert) and route to optimal providers. Research shows 35% decision quality improvement."
-            },
-            {
-                "name": "Advanced Memory System (Memoria-inspired)",
-                "effort_days": 4,
-                "value": 5,
-                "impact": 5,
-                "research_backed": True,
-                "citations": [
-                    "https://www.arxiv.org/abs/2512.12686",
-                    "https://arxiv.org/abs/2502.12110"
-                ],
-                "description": "Multi-tier memory: episodic (JSON), semantic (vector DB), working (in-memory). Research shows 50% improvement in long-term coherence."
-            },
-            {
-                "name": "Workflow Executors (Chaining & Parallelization)",
-                "effort_days": 3,
-                "value": 5,
-                "impact": 4,
-                "research_backed": True,
-                "citations": [
-                    "https://arxiv.org/abs/2511.15755"
-                ],
-                "description": "Implement chaining (sequential) and parallelization (concurrent) executors. Unlocks the 15% workflow use case."
-            },
-            {
-                "name": "CLI Interface with Rich Output",
-                "effort_days": 3,
-                "value": 4,
-                "impact": 4,
-                "research_backed": False,
-                "description": "Command-line tool with tmlpd execute, route, memory commands. Makes TMLPD practical for daily use."
-            },
-            {
-                "name": "Function Calling / Tool Use Enhancement",
-                "effort_days": 2,
-                "value": 4,
-                "impact": 4,
-                "research_backed": True,
-                "citations": [
-                    "https://arxiv.org/html/2409.00920v2"
-                ],
-                "description": "Skills as callable functions with structured parameters. Research shows 40% reliability improvement."
-            },
-            {
-                "name": "Git-Versioned Context Management",
-                "effort_days": 2,
-                "value": 3,
-                "impact": 3,
-                "research_backed": True,
-                "citations": [
-                    "https://arxiv.org/abs/2508.00031"
-                ],
-                "description": "Git-like branching and versioning for checkpoints. Enables experiment tracking and reproducibility."
-            },
-            {
-                "name": "Better Error Messages & Logging",
-                "effort_days": 1,
-                "value": 3,
-                "impact": 3,
-                "research_backed": False,
-                "description": "Actionable error messages with suggestions. Comprehensive logging for debugging."
-            }
-        ]
-
-    async def deliberate(self) -> Dict[str, Any]:
-        """
-        Run council deliberation process
-
-        Steps:
-        1. Each member analyzes proposals independently
-        2. Aggregate rankings
-        3. Identify consensus and disagreements
-        4. Generate final recommendation
-        """
-        print("\n" + "=" * 70)
-        print("  TMLPD IMPROVEMENT COUNCIL - MULTI-LLM DECISION MAKING")
-        print("=" * 70 + "\n")
-
-        # Step 1: Individual deliberations
-        print("Step 1: Gathering individual council member opinions...\n")
-
-        analyses = []
-        for member in self.members:
-            print(f"  🤔 {member.name} ({member.provider}) deliberating...")
-            analysis = await member.deliberate(self.proposals)
-            analyses.append(analysis)
-            print(f"     ✓ Complete")
-
-        # Step 2: Aggregate rankings
-        print("\nStep 2: Aggregating rankings and identifying consensus...\n")
-
-        aggregated = self._aggregate_rankings(analyses)
-
-        # Step 3: Display results
-        self._display_council_results(analyses, aggregated)
-
-        # Step 4: Generate final recommendation
-        recommendation = self._generate_recommendation(aggregated)
-
-        # Save results
-        self._save_council_decision(analyses, aggregated, recommendation)
-
-        return {
-            "individual_analyses": analyses,
-            "aggregated_rankings": aggregated,
-            "recommendation": recommendation
-        }
-
-    def _aggregate_rankings(self, analyses: List[Dict]) -> Dict[str, Any]:
-        """Aggregate rankings from all council members"""
-
-        # Calculate average scores for each proposal
-        proposal_scores = {p["name"]: {"total": 0, "count": 0, "scores": []} for p in self.proposals}
-
-        for analysis in analyses:
-            for ranking in analysis["rankings"]:
-                proposal_name = ranking["proposal"]
-                score = ranking["score"]
-
-                proposal_scores[proposal_name]["total"] += score
-                proposal_scores[proposal_name]["count"] += 1
-                proposal_scores[proposal_name]["scores"].append(score)
-
-        # Calculate averages
-        aggregated = []
-        for proposal_name, scores in proposal_scores.items():
-            avg_score = scores["total"] / scores["count"]
-            std_dev = self._calculate_std_dev(scores["scores"])
-
-            # Find consensus level (low std_dev = high consensus)
-            if std_dev < 10:
-                consensus = "strong"
-            elif std_dev < 20:
-                consensus = "moderate"
-            else:
-                consensus = "weak"
-
-            aggregated.append({
-                "proposal": proposal_name,
-                "average_score": avg_score,
-                "std_deviation": std_dev,
-                "consensus": consensus
-            })
-
-        # Sort by average score
-        aggregated.sort(key=lambda x: x["average_score"], reverse=True)
-
-        return aggregated
-
-    def _calculate_std_dev(self, scores: List[float]) -> float:
-        """Calculate standard deviation"""
-        if len(scores) < 2:
-            return 0.0
-
-        mean = sum(scores) / len(scores)
-        variance = sum((s - mean) ** 2 for s in scores) / len(scores)
-        return variance ** 0.5
-
-    def _display_council_results(self, analyses: List[Dict], aggregated: List[Dict]):
-        """Display council deliberation results"""
-
-        print("\n" + "=" * 70)
-        print("  COUNCIL MEMBER OPINIONS")
-        print("=" * 70 + "\n")
-
-        for analysis in analyses:
-            print(f"🤖 {analysis['member']} ({analysis['provider']})")
-            print(f"   Perspective: {analysis['perspective']}")
-            print(f"   Reasoning: {analysis['reasoning']}")
-            print(f"\n   Top Rankings:")
-
-            for i, ranking in enumerate(analysis["rankings"][:3], 1):
-                print(f"   {i}. {ranking['proposal']}: {ranking['score']:.1f}/100")
-                print(f"      {ranking['justification']}")
-
-            print()
-
-        print("\n" + "=" * 70)
-        print("  AGGREGATED COUNCIL RANKINGS")
-        print("=" * 70 + "\n")
-
-        for i, item in enumerate(aggregated, 1):
-            consensus_indicator = {
-                "strong": "🤝 Strong consensus",
-                "moderate": "🤷 Moderate agreement",
-                "weak": "⚠️  Disagreement"
-            }
-
-            print(f"{i}. **{item['proposal']}**")
-            print(f"   Score: {item['average_score']:.1f}/100")
-            print(f"   Consensus: {consensus_indicator[item['consensus']]}")
-            print()
-
-    def _generate_recommendation(self, aggregated: List[Dict]) -> Dict[str, Any]:
-        """Generate final council recommendation"""
-
-        # Top 3 proposals
-        top_3 = aggregated[:3]
-
-        # Check if there's strong consensus on #1
-        if top_3[0]["consensus"] == "strong":
-            implementation_strategy = "sequential"
-            reasoning = (
-                "Strong council consensus on top priority. "
-                "Implement sequentially for best results."
-            )
-        else:
-            implementation_strategy = "parallel"
-            reasoning = (
-                "Moderate disagreement on priorities. "
-                "Consider parallel implementation of top 2-3 items."
-            )
-
-        recommendation = {
-            "primary_recommendation": top_3[0]["proposal"],
-            "implementation_strategy": implementation_strategy,
-            "reasoning": reasoning,
-            "proposed_roadmap": []
-        }
-
-        # Generate roadmap based on strategy
-        if implementation_strategy == "sequential":
-            # Sequential roadmap
-            total_weeks = 0
-            for item in aggregated:
-                proposal = next(p for p in self.proposals if p["name"] == item["proposal"])
-                effort_days = proposal.get("effort_days", 5)
-                weeks = effort_days / 5
-
-                total_weeks += weeks
-
-                recommendation["proposed_roadmap"].append({
-                    "phase": len(recommendation["proposed_roadmap"]) + 1,
-                    "proposal": item["proposal"],
-                    "duration_weeks": weeks,
-                    "cumulative_weeks": total_weeks
-                })
-        else:
-            # Parallel roadmap (top items in parallel)
-            recommendation["proposed_roadmap"] = [
-                {
-                    "phase": 1,
-                    "proposal": "Parallel implementation of top 3",
-                    "duration_weeks": 3,
-                    "items": [item["proposal"] for item in top_3]
-                }
-            ]
-
-        return recommendation
-
-    def _save_council_decision(
-        self,
-        analyses: List[Dict],
-        aggregated: List[Dict],
-        recommendation: Dict
-    ):
-        """Save council decision to file"""
-
-        decision_doc = {
-            "timestamp": datetime.now().isoformat(),
-            "council_members": [m["member"] for m in analyses],
-            "individual_analyses": analyses,
-            "aggregated_rankings": aggregated,
-            "recommendation": recommendation
-        }
-
-        output_path = Path("/Users/Subho/tmlpd-skill/docs/COUNCIL_DECISION.json")
-
-        with open(output_path, 'w') as f:
-            json.dump(decision_doc, f, indent=2)
-
-        print(f"\n✅ Council decision saved to: {output_path}")
-
-
-async def main():
-    """Run improvement council"""
-
-    council = ImprovementCouncil()
-    decision = await council.deliberate()
-
-    print("\n" + "=" * 70)
-    print("  FINAL COUNCIL RECOMMENDATION")
-    print("=" * 70 + "\n")
-
-    rec = decision["recommendation"]
-
-    print(f"🎯 Primary Recommendation:")
-    print(f"   {rec['primary_recommendation']}")
-    print()
-    print(f"📋 Implementation Strategy:")
-    print(f"   {rec['implementation_strategy']}")
-    print()
-    print(f"💡 Reasoning:")
-    print(f"   {rec['reasoning']}")
-    print()
-    print(f"🗓️  Proposed Roadmap:")
-    print()
-
-    for phase in rec["proposed_roadmap"]:
-        print(f"   Phase {phase['phase']}:")
-        if "proposal" in phase:
-            print(f"   - {phase['proposal']}")
-            print(f"   - Duration: {phase['duration_weeks']:.1f} weeks")
-        else:
-            print(f"   - {phase['proposal']}")
-            print(f"   - Duration: {phase['duration_weeks']:.1f} weeks")
-            print(f"   - Items: {', '.join(phase['items'])}")
-        print()
-
-    print("=" * 70)
-    print("\n✨ Council deliberation complete!")
-    print("   See docs/COUNCIL_DECISION.json for full details.\n")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

package/docs/MIDDLEWARE_CHAIN.md

@@ -1,35 +0,0 @@
-# A3M Router — Middleware Chain
-
-Pre-flight checks before every routing decision.
-
-## Chain Order
-
-```
-1. Guardrails Check   → 9 STOP conditions (docs/ANALYSIS_PRINCIPLES.md)
-2. Provider Health    → Quick ping all providers (<50ms)
-3. Budget Check       → Remaining budget vs estimated cost (<1ms)
-4. Version Check      → npm upgrade available? (cached 24h)
-5. Cache Lookup       → Semantic cache for repeated queries (<5ms)
-6. Route → Execute    → Call selected provider(s)
-7. Log                → Write audit-log.ndjson entry
-8. Cross-Validate     → If --validate flag, call second provider (<500ms)
-9. Return Response
-```
-
-## Implementation Status
-
-| Step | Status | File |
-|------|--------|------|
-| 1. Guardrails | ✅ | docs/ANALYSIS_PRINCIPLES.md |
-| 2. Health | ✅ | src/routing/providerHealth.ts |
-| 3. Budget | ✅ | src/cost/budgetEnforcer.ts |
-| 4. Version | ✅ | bin/a3m-upgrade-check |
-| 5. Cache | ✅ | src/cache/semanticCache.ts |
-| 6. Route | ✅ | src/routing/advancedRouter.ts |
-| 7. Log | ⚠️ | ~/.a3m-router/audit-log.ndjson |
-| 8. Validate | ✅ | src/routing/crossModelValidation.ts |
-| 9. Return | ✅ | CLI built-in |
-
-## Why
-
-Every link is a reliability guarantee. Broken chain = charged for failed queries.