Clean up repository: Remove unnecessary markdown files and update README

.gitignore

@@ -6,3 +6,30 @@ __pycache__/
 data/benchmark_vector_db/
 data/benchmark_results/mmlu_real_results.json
 models/
+# Development summary files
+COMPLETE_DEMO_ANALYSIS.md
+FINAL_SUMMARY.md
+PUSH_TO_GITHUB.md
+GITHUB_INSTRUCTIONS.md
+CLUSTERING_EXECUTION_LOG.md
+CLUSTERING_RESULTS_SUMMARY.md
+CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md
+REAL_DATA_FETCH_STATUS.md
+VECTOR_DB_STATUS.md
+VECTOR_DB_SUMMARY.md
+ARCHITECTURE.md
+CHANGELOG_ROADMAP.md
+CLAUDE_DESKTOP_TROUBLESHOOTING.md
+DEPLOYMENT.md
+DYNAMIC_TOOLS_DESIGN.md
+EXECUTION_PLAN.md
+HOSTING_GUIDE.md
+INDEX.md
+MCP_CONNECTION_GUIDE.md
+PROJECT_SUMMARY.md
+PROMPT_IMPROVER_PLAN.md
+QUICKSTART.md
+QUICK_ANSWERS.md
+RUN_COMMANDS.sh
+SERVER_INFO.md
+SETUP_COMPLETE.md

ARCHITECTURE.md

@@ -1,486 +0,0 @@
-# ToGMAL Architecture
-
-## System Overview
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         Claude Desktop                          │
-│                    (or other MCP Client)                        │
-└────────────────────────────┬────────────────────────────────────┘
-                             │ stdio/MCP Protocol
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│                     ToGMAL MCP Server                           │
-│                    (togmal_mcp.py)                             │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │                   MCP Tools Layer                         │  │
-│  │  - togmal_analyze_prompt                                 │  │
-│  │  - togmal_analyze_response                               │  │
-│  │  - togmal_submit_evidence                                │  │
-│  │  - togmal_get_taxonomy                                   │  │
-│  │  - togmal_get_statistics                                 │  │
-│  └──────────────────┬───────────────────────────────────────┘  │
-│                     │                                           │
-│  ┌──────────────────▼───────────────────────────────────────┐  │
-│  │              Detection Heuristics                         │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │  Math/Physics Speculation Detector                 │  │  │
-│  │  │  - Pattern: "theory of everything"                 │  │  │
-│  │  │  - Pattern: "new equation"                         │  │  │
-│  │  │  - Pattern: excessive notation                     │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │  Ungrounded Medical Advice Detector                │  │  │
-│  │  │  - Pattern: "you probably have"                    │  │  │
-│  │  │  - Pattern: "take Xmg"                            │  │  │
-│  │  │  - Check: has_sources                              │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │  Dangerous File Operations Detector                │  │  │
-│  │  │  - Pattern: "rm -rf"                              │  │  │
-│  │  │  - Pattern: recursive deletion                     │  │  │
-│  │  │  - Check: has_safeguards                          │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │  Vibe Coding Overreach Detector                   │  │  │
-│  │  │  - Pattern: "complete app"                         │  │  │
-│  │  │  - Pattern: large line counts                      │  │  │
-│  │  │  - Check: has_planning                            │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │  Unsupported Claims Detector                       │  │  │
-│  │  │  - Pattern: "always/never"                         │  │  │
-│  │  │  - Pattern: statistics without source              │  │  │
-│  │  │  - Check: has_hedging                             │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  └──────────────────┬───────────────────────────────────────┘  │
-│                     │                                           │
-│  ┌──────────────────▼───────────────────────────────────────┐  │
-│  │           Risk Assessment & Interventions                 │  │
-│  │  - Calculate weighted risk score                         │  │
-│  │  - Map to risk levels (LOW → CRITICAL)                  │  │
-│  │  - Recommend interventions                               │  │
-│  └──────────────────┬───────────────────────────────────────┘  │
-│                     │                                           │
-│  ┌──────────────────▼───────────────────────────────────────┐  │
-│  │              Taxonomy Database                            │  │
-│  │  - In-memory storage (extendable to persistent)          │  │
-│  │  - Evidence entries with metadata                        │  │
-│  │  - Filtering and pagination                              │  │
-│  └───────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Data Flow - Prompt Analysis
-
-```
-User Prompt
-    │
-    ├─────────────────────────────────────────────┐
-    │                                             │
-    ▼                                             │
-togmal_analyze_prompt                             │
-    │                                             │
-    ├──► Math/Physics Detector ──► Result 1      │
-    │                                             │
-    ├──► Medical Advice Detector ──► Result 2    │
-    │                                             │
-    ├──► File Ops Detector ──► Result 3          │
-    │                                             │
-    ├──► Vibe Coding Detector ──► Result 4       │
-    │                                             │
-    └──► Unsupported Claims Detector ──► Result 5│
-                                                  │
-    ┌─────────────────────────────────────────────┘
-    │
-    ▼
-Risk Calculation
-    │
-    ├─► Weight results
-    ├─► Calculate score
-    └─► Map to risk level
-        │
-        ▼
-Intervention Recommendation
-    │
-    ├─► Step breakdown?
-    ├─► Human-in-loop?
-    ├─► Web search?
-    └─► Simplified scope?
-        │
-        ▼
-Format Response (Markdown/JSON)
-    │
-    └──► Return to Client
-```
-
-## Detection Pipeline
-
-```
-Input Text
-    │
-    ▼
-┌───────────────────────────┐
-│   Preprocessing           │
-│   - Lowercase             │
-│   - Strip whitespace      │
-└───────────┬───────────────┘
-            │
-            ▼
-┌───────────────────────────┐
-│   Pattern Matching        │
-│   - Regex patterns        │
-│   - Keyword detection     │
-│   - Structural analysis   │
-└───────────┬───────────────┘
-            │
-            ▼
-┌───────────────────────────┐
-│   Confidence Scoring      │
-│   - Count matches         │
-│   - Weight by type        │
-│   - Normalize to [0,1]    │
-└───────────┬───────────────┘
-            │
-            ▼
-┌───────────────────────────┐
-│   Context Checks          │
-│   - has_sources?          │
-│   - has_hedging?          │
-│   - has_safeguards?       │
-└───────────┬───────────────┘
-            │
-            ▼
-Detection Result
-{
-  detected: bool,
-  categories: list,
-  confidence: float,
-  metadata: dict
-}
-```
-
-## Risk Calculation Algorithm
-
-```
-For each detection category:
-    
-    Math/Physics:
-        risk += confidence × 0.5
-    
-    Medical Advice:
-        risk += confidence × 1.5  # Highest weight
-    
-    File Operations:
-        risk += confidence × 2.0  # Critical actions
-    
-    Vibe Coding:
-        risk += confidence × 0.4
-    
-    Unsupported Claims:
-        risk += confidence × 0.3
-
-Total Risk Score:
-    
-    ≥ 1.5 → CRITICAL
-    ≥ 1.0 → HIGH
-    ≥ 0.5 → MODERATE
-    < 0.5 → LOW
-```
-
-## Intervention Decision Tree
-
-```
-                    Detection Results
-                          │
-        ┌─────────────────┼─────────────────┐
-        │                 │                 │
-        ▼                 ▼                 ▼
-  Math/Physics?     Medical Advice?   File Operations?
-        │                 │                 │
-        ├─► Yes           ├─► Yes           ├─► Yes
-        │   │             │   │             │   │
-        │   ├─► Step      │   ├─► Human    │   ├─► Human
-        │   │   Breakdown │   │   in Loop   │   │   in Loop
-        │   │             │   │             │   │
-        │   └─► Web       │   └─► Web       │   └─► Step
-        │       Search    │       Search    │       Breakdown
-        │                 │                 │
-        └─► No            └─► No            └─► No
-            │                 │                 │
-            ▼                 ▼                 ▼
-      Continue          Continue          Continue
-
-                    ┌───────────┐
-                    │  Combine  │
-                    │  Results  │
-                    └─────┬─────┘
-                          │
-                          ▼
-              Intervention List
-              (deduplicated)
-```
-
-## Taxonomy Database Schema
-
-```
-TAXONOMY_DB = {
-    "category_name": [
-        {
-            "id": "abc123def456",
-            "category": "math_physics_speculation",
-            "prompt": "User's prompt text...",
-            "response": "LLM's response text...",
-            "description": "Why problematic...",
-            "severity": "high",
-            "timestamp": "2025-10-18T00:00:00",
-            "prompt_hash": "a1b2c3d4"
-        },
-        { ... more entries ... }
-    ],
-    "another_category": [ ... ]
-}
-
-Indices:
-- By category (dict key)
-- By severity (filter)
-- By timestamp (sort)
-- By hash (deduplication)
-```
-
-## Component Responsibilities
-
-### MCP Tools Layer
-**Responsibilities:**
-- Input validation (Pydantic models)
-- Parameter extraction
-- Tool orchestration
-- Response formatting
-- Character limit enforcement
-
-**Does NOT:**
-- Perform detection logic
-- Calculate risk scores
-- Store data directly
-
-### Detection Heuristics Layer
-**Responsibilities:**
-- Pattern matching
-- Confidence scoring
-- Context analysis
-- Detection result generation
-
-**Does NOT:**
-- Make intervention decisions
-- Format responses
-- Handle I/O
-
-### Risk Assessment Layer
-**Responsibilities:**
-- Aggregate detection results
-- Calculate weighted risk scores
-- Map scores to risk levels
-- Generate intervention recommendations
-
-**Does NOT:**
-- Perform detection
-- Format responses
-- Store data
-
-### Taxonomy Database
-**Responsibilities:**
-- Store evidence entries
-- Support filtering/pagination
-- Provide statistics
-- Maintain capacity limits
-
-**Does NOT:**
-- Perform analysis
-- Make decisions
-- Format responses
-
-## Extension Points
-
-### Adding New Detection Categories
-
-```python
-# 1. Add enum value
-class CategoryType(str, Enum):
-    NEW_CATEGORY = "new_category"
-
-# 2. Create detector function
-def detect_new_category(text: str) -> Dict[str, Any]:
-    patterns = { ... }
-    # Detection logic
-    return {
-        'detected': bool,
-        'categories': list,
-        'confidence': float
-    }
-
-# 3. Update analysis functions
-def analyze_prompt(params):
-    results['new_category'] = detect_new_category(params.prompt)
-    # ... rest of logic
-
-# 4. Update risk calculation
-def calculate_risk_level(results):
-    if results['new_category']['detected']:
-        risk_score += results['new_category']['confidence'] * WEIGHT
-
-# 5. Add intervention logic
-def recommend_interventions(results):
-    if results['new_category']['detected']:
-        interventions.append({ ... })
-```
-
-### Adding Persistent Storage
-
-```python
-# 1. Define storage backend
-class TaxonomyStorage:
-    def save(self, category, entry): ...
-    def load(self, category, filters): ...
-    def get_stats(self): ...
-
-# 2. Replace in-memory dict
-storage = TaxonomyStorage(backend="sqlite")  # or "postgres", "mongodb"
-
-# 3. Update tool functions
-@mcp.tool()
-async def submit_evidence(params):
-    # Instead of: TAXONOMY_DB[category].append(entry)
-    await storage.save(params.category, entry)
-```
-
-### Adding ML Models
-
-```python
-# 1. Define model interface
-class AnomalyDetector:
-    def fit(self, X): ...
-    def predict(self, x) -> float: ...
-
-# 2. Train from taxonomy
-detector = AnomalyDetector()
-training_data = get_training_data_from_taxonomy()
-detector.fit(training_data)
-
-# 3. Use in detection
-def detect_with_ml(text: str) -> float:
-    features = extract_features(text)
-    anomaly_score = detector.predict(features)
-    return anomaly_score
-```
-
-## Performance Characteristics
-
-### Time Complexity
-- **Pattern Matching**: O(n) where n = text length
-- **All Detectors**: O(n) (parallel constant time)
-- **Risk Calculation**: O(1) (fixed number of categories)
-- **Taxonomy Query**: O(m·log m) where m = matching entries
-- **Overall**: O(n + m·log m)
-
-### Space Complexity
-- **Server Base**: ~50 MB
-- **Per Request**: ~1 KB (temporary)
-- **Per Taxonomy Entry**: ~1 KB
-- **Total with 1000 entries**: ~51 MB
-
-### Latency
-- **Single Detection**: ~10-50 ms
-- **All Detections**: ~50-100 ms
-- **Format Response**: ~1-10 ms
-- **Total Per Request**: ~100-150 ms
-
-## Security Considerations
-
-### Input Validation
-```
-User Input
-    │
-    ▼
-Pydantic Model
-    │
-    ├─► Type checking
-    ├─► Length limits
-    ├─► Pattern validation
-    └─► Field constraints
-        │
-        ▼
-    Valid Input
-```
-
-### Privacy Protection
-```
-┌────────────────────────────────────┐
-│  NO External API Calls             │
-│  NO Data Transmission              │
-│  NO Logging Sensitive Info         │
-│  YES Local Processing Only         │
-│  YES User Consent Required         │
-│  YES Data Stays on Device          │
-└────────────────────────────────────┘
-```
-
-### Human-in-the-Loop
-```
-Sensitive Operation Detected
-    │
-    ▼
-Request User Confirmation
-    │
-    ├─► Yes → Proceed
-    │
-    └─► No → Cancel
-```
-
-## Scalability Path
-
-### Current: Single Instance
-```
-Client → stdio → ToGMAL Server → Response
-```
-
-### Future: HTTP Transport
-```
-Multiple Clients → HTTP → ToGMAL Server → Response
-                          ↓
-                    Shared Database
-```
-
-### Advanced: Distributed
-```
-Clients → Load Balancer → ToGMAL Servers (N)
-                              ↓
-                        Shared Database
-                              ↓
-                        ML Model Cache
-```
-
-## Monitoring Points
-
-```
-┌─────────────────────────────────────┐
-│  Metrics to Track                   │
-├─────────────────────────────────────┤
-│  - Tool call frequency              │
-│  - Detection rates by category      │
-│  - Risk level distribution          │
-│  - Intervention effectiveness       │
-│  - False positive rate              │
-│  - Response latency                 │
-│  - Taxonomy growth rate             │
-│  - User feedback submissions        │
-└─────────────────────────────────────┘
-```
-
----
-
-This architecture supports:
-- ✅ Privacy-preserving analysis
-- ✅ Low-latency detection
-- ✅ Extensible design
-- ✅ Production readiness
-- ✅ Future ML integration

CHANGELOG_ROADMAP.md

@@ -1,399 +0,0 @@
-# ToGMAL Changelog & Roadmap
-
-## Version 1.0.0 (October 2025) - Initial Release
-
-### ✨ Features
-
-#### Core Detection System
-- ✅ Math/Physics speculation detector with pattern matching
-- ✅ Ungrounded medical advice detector with source checking
-- ✅ Dangerous file operations detector with safeguard validation
-- ✅ Vibe coding overreach detector with scope analysis
-- ✅ Unsupported claims detector with hedging verification
-
-#### Risk Assessment
-- ✅ Weighted confidence scoring system
-- ✅ Four-tier risk levels (LOW, MODERATE, HIGH, CRITICAL)
-- ✅ Dynamic risk calculation based on detection results
-- ✅ Context-aware confidence adjustment
-
-#### Intervention System
-- ✅ Step breakdown recommendations
-- ✅ Human-in-the-loop suggestions
-- ✅ Web search recommendations
-- ✅ Simplified scope guidance
-- ✅ Automatic intervention mapping by detection type
-
-#### MCP Tools
-- ✅ `togmal_analyze_prompt` - Pre-process analysis
-- ✅ `togmal_analyze_response` - Post-process analysis
-- ✅ `togmal_submit_evidence` - Taxonomy contribution with user confirmation
-- ✅ `togmal_get_taxonomy` - Database query with filtering/pagination
-- ✅ `togmal_get_statistics` - Aggregate metrics
-
-#### Data Management
-- ✅ In-memory taxonomy database
-- ✅ Evidence submission with human-in-the-loop
-- ✅ Pagination support for large result sets
-- ✅ Category and severity filtering
-- ✅ Statistical summaries
-
-#### Developer Experience
-- ✅ Comprehensive documentation (README, DEPLOYMENT, QUICKSTART)
-- ✅ Test examples with expected outcomes
-- ✅ Architecture documentation with diagrams
-- ✅ Claude Desktop configuration examples
-- ✅ Type-safe Pydantic models
-- ✅ Full MCP best practices compliance
-
-### 📊 Statistics
-- **Lines of Code**: 1,270 (server) + 500+ (tests/docs)
-- **Detection Patterns**: 25+ regex patterns across 5 categories
-- **MCP Tools**: 5 tools with full documentation
-- **Test Cases**: 10 comprehensive scenarios
-- **Documentation Pages**: 6 files (README, DEPLOYMENT, QUICKSTART, etc.)
-
-### 🎯 Design Goals Achieved
-- ✅ Privacy-preserving (no external API calls)
-- ✅ Low latency (< 150ms per request)
-- ✅ Deterministic detection (reproducible results)
-- ✅ Extensible architecture (easy to add patterns)
-- ✅ Human-centered (always allows override)
-
----
-
-## Version 1.1.0 (Planned - Q1 2026)
-
-### 🚀 Planned Features
-
-#### Enhanced Detection
-- 🔜 Code smell detector for programming anti-patterns
-- 🔜 SQL injection pattern detector for database queries
-- 🔜 Privacy violation detector (PII, credentials in code)
-- 🔜 License compliance checker for code generation
-- 🔜 Bias and fairness detector for content analysis
-
-#### Improved Accuracy
-- 🔜 Context-aware pattern matching (not just regex)
-- 🔜 Multi-language support (start with Spanish, Chinese)
-- 🔜 Domain-specific pattern libraries
-- 🔜 Confidence calibration based on feedback
-- 🔜 False positive reduction heuristics
-
-#### User Experience
-- 🔜 Configurable sensitivity levels (strict/moderate/lenient)
-- 🔜 Custom pattern editor UI (if web interface added)
-- 🔜 Detection history and trends
-- 🔜 Exportable reports (PDF, CSV)
-- 🔜 Batch analysis mode
-
-#### Integration
-- 🔜 GitHub Actions integration for PR checks
-- 🔜 VS Code extension
-- 🔜 Slack bot for team safety
-- 🔜 API webhooks for custom workflows
-- 🔜 Prometheus metrics export
-
----
-
-## Version 2.0.0 (Planned - Q3 2026)
-
-### 🔬 Machine Learning Integration
-
-#### Traditional ML Models
-- 🔜 Unsupervised clustering for anomaly detection
-- 🔜 Feature extraction from text (TF-IDF, embeddings)
-- 🔜 Statistical outlier detection
-- 🔜 Time-series analysis for trend detection
-- 🔜 Ensemble methods combining heuristics + ML
-
-#### Training Pipeline
-- 🔜 Automated retraining from taxonomy submissions
-- 🔜 Cross-validation framework
-- 🔜 Performance benchmarking suite
-- 🔜 Model versioning and rollback
-- 🔜 A/B testing framework
-
-#### Persistent Storage
-- 🔜 SQLite backend for local deployments
-- 🔜 PostgreSQL support for multi-user setups
-- 🔜 MongoDB support for document-oriented storage
-- 🔜 Data export/import utilities
-- 🔜 Backup and restore functionality
-
-#### Performance Optimization
-- 🔜 Caching layer for repeated queries
-- 🔜 Parallel detection pipeline
-- 🔜 Incremental analysis for large texts
-- 🔜 Background processing for non-blocking operations
-- 🔜 Resource pooling for high-concurrency
-
----
-
-## Version 3.0.0 (Planned - 2027)
-
-### 🌐 Advanced Capabilities
-
-#### Federated Learning
-- 🔜 Privacy-preserving model updates across users
-- 🔜 Differential privacy guarantees
-- 🔜 Decentralized taxonomy building
-- 🔜 Peer-to-peer pattern sharing
-- 🔜 Community-driven improvement
-
-#### Context Understanding
-- 🔜 Multi-turn conversation awareness
-- 🔜 User intent detection
-- 🔜 Domain adaptation based on context
-- 🔜 Temporal reasoning (before/after analysis)
-- 🔜 Cross-reference checking
-
-#### Domain-Specific Models
-- 🔜 Medical domain specialist
-- 🔜 Legal compliance checker
-- 🔜 Financial advice validator
-- 🔜 Engineering standards enforcer
-- 🔜 Educational content verifier
-
-#### Advanced Interventions
-- 🔜 Automated prompt refinement suggestions
-- 🔜 Real-time correction proposals
-- 🔜 Alternative approach generation
-- 🔜 Risk mitigation strategies
-- 🔜 Learning resources recommendation
-
----
-
-## Feature Requests (Community Driven)
-
-### High Priority
-- [ ] Custom pattern templates for organizations
-- [ ] Integration with popular IDEs (IntelliJ, PyCharm)
-- [ ] Support for more file formats (PDF analysis, image text)
-- [ ] Multi-user collaboration features
-- [ ] Role-based access control
-
-### Medium Priority
-- [ ] Natural language pattern definition (no regex needed)
-- [ ] Visual dashboard for analytics
-- [ ] Email digest of daily detections
-- [ ] Integration with CI/CD pipelines
-- [ ] Mobile app for on-the-go analysis
-
-### Low Priority
-- [ ] Voice interface for accessibility
-- [ ] Browser extension for web-based LLM tools
-- [ ] Desktop notification system
-- [ ] Gamification of taxonomy contributions
-- [ ] Social features (share patterns, leaderboards)
-
----
-
-## Technical Debt & Improvements
-
-### Code Quality
-- [ ] Increase test coverage to 90%+
-- [ ] Add integration tests with MCP client
-- [ ] Performance benchmarking suite
-- [ ] Memory profiling and optimization
-- [ ] Code coverage reporting
-
-### Documentation
-- [ ] Video tutorials
-- [ ] Interactive playground
-- [ ] API reference (auto-generated)
-- [ ] Contribution guidelines
-- [ ] Security audit documentation
-
-### Infrastructure
-- [ ] Automated release process
-- [ ] Docker images on Docker Hub
-- [ ] Helm charts for Kubernetes
-- [ ] Terraform modules for cloud deployment
-- [ ] Ansible playbooks for server setup
-
----
-
-## Research Directions
-
-### Academic Interests
-- Effectiveness of different intervention strategies
-- False positive/negative rates across domains
-- User behavior changes with safety interventions
-- Pattern evolution over time
-- Cross-cultural differences in LLM usage
-
-### Industry Applications
-- Healthcare LLM safety in clinical settings
-- Financial services compliance checking
-- Legal review automation assistance
-- Educational content quality assurance
-- Enterprise governance and risk management
-
-### Open Problems
-- Zero-shot detection of novel failure modes
-- Adversarial robustness against prompt engineering
-- Balancing safety with creative freedom
-- Determining optimal intervention timing
-- Measuring long-term impact on user behavior
-
----
-
-## Breaking Changes
-
-### Version 1.x → 2.0
-- ML models will require additional dependencies (scikit-learn, numpy)
-- Database schema changes (migration scripts provided)
-- New configuration format for ML settings
-- API changes for detection result structure
-
-### Version 2.x → 3.0
-- Federated learning requires network capabilities
-- Context-aware features need conversation history
-- Domain models require larger memory footprint
-- API changes for multi-turn analysis
-
----
-
-## Deprecation Schedule
-
-### Version 1.x
-- **No deprecations** - All features fully supported
-- Commitment to backward compatibility for 2 years
-
-### Version 2.0
-- In-memory storage will become **optional** (still supported)
-- Heuristic-only mode will be **supplemented** (not replaced)
-- Single-request analysis remains **fully supported**
-
-### Version 3.0
-- Regex-based patterns may become **legacy** feature
-- Simple patterns will be **auto-converted** to ML-compatible format
-- Manual intervention recommendations may become **AI-assisted**
-
----
-
-## Community Contributions
-
-### How to Contribute
-
-#### Code Contributions
-1. Fork the repository
-2. Create a feature branch
-3. Write tests for new features
-4. Submit a pull request with description
-5. Address review comments
-
-#### Pattern Contributions
-1. Use `togmal_submit_evidence` tool
-2. Provide clear descriptions
-3. Include severity assessment
-4. Add reproduction steps if possible
-5. Vote on existing submissions
-
-#### Documentation Contributions
-1. Identify unclear sections
-2. Propose improvements
-3. Add examples and use cases
-4. Translate to other languages
-5. Create video tutorials
-
-### Recognition
-- Contributors listed in README
-- Significant contributions highlighted in releases
-- Option for co-authorship on research papers
-- Speaking opportunities at conferences
-- Early access to new features
-
----
-
-## Versioning Strategy
-
-### Semantic Versioning (X.Y.Z)
-- **X (Major)**: Breaking changes, new ML models, architecture changes
-- **Y (Minor)**: New features, new detectors, non-breaking API changes
-- **Z (Patch)**: Bug fixes, documentation updates, pattern improvements
-
-### Release Cadence
-- **Patch releases**: As needed for critical bugs (1-2 weeks)
-- **Minor releases**: Quarterly (every 3 months)
-- **Major releases**: Annually or when significant changes warrant
-
-### Support Policy
-- **Current major version**: Full support
-- **Previous major version**: Security fixes for 1 year
-- **Older versions**: Community support only
-
----
-
-## Success Metrics
-
-### Version 1.0 Goals (6 months)
-- [ ] 100+ active users
-- [ ] 1,000+ analyzed prompts
-- [ ] 50+ taxonomy submissions
-- [ ] 10+ community pattern contributions
-- [ ] 5+ integration examples
-
-### Version 2.0 Goals (12 months)
-- [ ] 1,000+ active users
-- [ ] 10,000+ analyzed prompts
-- [ ] ML models deployed in production
-- [ ] 50%+ detection accuracy improvement
-- [ ] 3+ organizational deployments
-
-### Version 3.0 Goals (24 months)
-- [ ] 10,000+ active users
-- [ ] Federated learning network established
-- [ ] Domain-specific models for 5+ industries
-- [ ] Research paper published
-- [ ] Conference presentations
-
----
-
-## License & Governance
-
-### Current: MIT License
-- Permissive open source
-- Commercial use allowed
-- Attribution required
-- No warranty provided
-
-### Future Considerations
-- Potential move to Apache 2.0 for patent protection
-- Contributor License Agreement (CLA) for large contributions
-- Trademark registration for "ToGMAL"
-- Formal governance structure (if project grows)
-
----
-
-## Contact & Support
-
-- **GitHub**: [Repository URL]
-- **Discord**: [Community Server]
-- **Email**: [email protected]
-- **Twitter**: @togmal_project
-- **Documentation**: https://docs.togmal.dev
-
----
-
-**Last Updated**: October 2025  
-**Next Review**: January 2026
-
----
-
-## Quick Stats
-
-| Metric | Current | Target (v2.0) | Target (v3.0) |
-|--------|---------|---------------|---------------|
-| Detection Categories | 5 | 10 | 20 |
-| Pattern Library | 25 | 100 | 500 |
-| Languages Supported | 1 | 3 | 10 |
-| Average Latency | 100ms | 50ms | 25ms |
-| Accuracy (F1) | 0.70 | 0.85 | 0.95 |
-| Active Users | TBD | 1,000 | 10,000 |
-| Taxonomy Entries | 0 | 10,000 | 100,000 |
-
----
-
-*This is a living document. Priorities may shift based on community feedback and emerging needs.*

CLAUDE_DESKTOP_TROUBLESHOOTING.md

@@ -1,294 +0,0 @@
-# Claude Desktop MCP Integration Troubleshooting
-
-## ✅ Current Status
-
-### What's Working:
-- ✅ **MCP Server:** `togmal_mcp.py` is functioning correctly
-- ✅ **Config File:** Properly placed at `~/Library/Application Support/Claude/claude_desktop_config.json`
-- ✅ **Python Environment:** Virtual environment exists with all dependencies
-- ✅ **Server Test:** Responds correctly to JSON-RPC initialize requests
-
-### Test Result:
-```bash
-$ echo '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | python togmal_mcp.py
-Response: {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"togmal_mcp","version":"1.18.0"}}}
-```
-**✅ Server is working perfectly!**
-
----
-
-## ❌ The Problem
-
-**Claude Desktop version 0.12.55 is too old to support MCP servers.**
-
-### Evidence from Logs:
-```
-2025-10-18 11:20:32 [info] Starting app { appVersion: '0.12.55' }
-2025-10-18 11:27:46 [info] Update downloaded and ready to install { releaseName: 'Claude 0.13.108' }
-```
-
-### What's Missing:
-- No MCP server initialization logs
-- No MCP connection attempts
-- No tool registration messages
-
----
-
-## 🔧 Solution
-
-### **Step 1: Install Claude Desktop Update**
-
-An update is already downloaded and waiting!
-
-1. **Quit Claude Desktop completely** (⌘+Q)
-2. **Reopen Claude Desktop** 
-3. **Install the update** when prompted (Claude 0.13.108)
-4. **Restart Claude Desktop** after update
-
-### **Step 2: Verify MCP Support**
-
-After updating, check if MCP is supported:
-
-1. Open Claude Desktop
-2. Go to **Settings** → **Advanced** (or **Developer**)
-3. Look for **"MCP Servers"** or **"Model Context Protocol"** section
-4. You should see "togmal" listed as a connected server
-
-### **Step 3: Check Logs Again**
-
-After the update, logs should show:
-```
-[info] Starting MCP server: togmal
-[info] MCP server togmal connected successfully
-[info] Registered 5 tools from togmal
-```
-
-### **Step 4: Test in Conversation**
-
-Ask Claude Desktop:
-```
-"What MCP tools are available?"
-```
-
-You should see:
-- `togmal_analyze_prompt`
-- `togmal_analyze_response`
-- `togmal_submit_evidence`
-- `togmal_get_taxonomy`
-- `togmal_get_statistics`
-
----
-
-## 🎯 Alternative: Verify MCP Version Support
-
-### Check Minimum Claude Desktop Version for MCP:
-
-MCP support was added in **Claude Desktop 0.13.x** (approximately November 2024).
-
-**Your current version:** 0.12.55 ❌  
-**Update available:** 0.13.108 ✅  
-**Minimum required:** ~0.13.0 ✅
-
----
-
-## 📋 Complete Checklist
-
-### ✅ Already Completed:
-- [x] MCP server code is correct (tested with JSON-RPC)
-- [x] Config file is in the right location
-- [x] Python path is correct
-- [x] Dependencies are installed
-- [x] Server responds to initialize requests
-
-### ⏳ To Do:
-- [ ] Update Claude Desktop to 0.13.108
-- [ ] Restart Claude Desktop
-- [ ] Verify MCP servers appear in settings
-- [ ] Test tools in conversation
-
----
-
-## 🔍 Detailed Verification Commands
-
-### 1. Test Server Manually
-```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /Users/hetalksinmaths/togmal/.venv/bin/python /Users/hetalksinmaths/togmal/togmal_mcp.py
-```
-
-**Expected Output:** JSON response with `"serverInfo":{"name":"togmal_mcp"}`
-
-### 2. Verify Config
-```bash
-cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-**Expected Content:**
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"],
-      "description": "Taxonomy of Generative Model Apparent Limitations",
-      "env": {
-        "TOGMAL_DEBUG": "false",
-        "TOGMAL_MAX_ENTRIES": "1000"
-      }
-    }
-  }
-}
-```
-
-### 3. Check Python Environment
-```bash
-/Users/hetalksinmaths/togmal/.venv/bin/python -c "import mcp; from mcp.server.fastmcp import FastMCP; print('MCP imports OK')"
-```
-
-**Expected Output:** `MCP imports OK`
-
-### 4. Monitor Logs After Update
-```bash
-tail -f ~/Library/Logs/Claude/main.log
-```
-
-**Look for:** Lines mentioning "MCP", "togmal", or "tools"
-
----
-
-## 🚨 If Update Doesn't Fix It
-
-### Additional Troubleshooting Steps:
-
-#### 1. **Check Claude Desktop Version**
-After update, verify version in **Claude Desktop → About**
-
-Should be **0.13.108** or higher.
-
-#### 2. **Clear Claude Desktop Cache**
-```bash
-rm -rf ~/Library/Application\ Support/Claude/Cache/*
-rm -rf ~/Library/Application\ Support/Claude/Code\ Cache/*
-```
-
-Then restart Claude Desktop.
-
-#### 3. **Reinstall Claude Desktop**
-1. Download latest from https://claude.ai/download
-2. Uninstall current version
-3. Install fresh copy
-4. Config file should persist
-
-#### 4. **Check for Conflicting MCP Servers**
-```bash
-cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-Make sure there are no syntax errors or conflicting server names.
-
-#### 5. **Test with Minimal Config**
-Temporarily simplify the config:
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-Remove the `env` and `description` fields to test if they cause issues.
-
----
-
-## 📊 Expected Behavior After Fix
-
-### In Claude Desktop Settings:
-```
-MCP Servers:
-  ✅ togmal - Connected (5 tools)
-```
-
-### In Conversation:
-```
-User: "Use ToGMAL to analyze this prompt: 'Build quantum computer'"
-
-Claude: [Calls togmal_analyze_prompt tool]
-
-ToGMAL Analysis:
-  Risk Level: MODERATE
-  Detections: Math/Physics Speculation
-  Interventions: Step breakdown, Web search
-```
-
-### In Logs:
-```
-[info] MCP server togmal started (PID: 12345)
-[info] Tools registered from togmal: 5
-[debug] togmal_analyze_prompt available
-[debug] togmal_analyze_response available
-[debug] togmal_submit_evidence available
-[debug] togmal_get_taxonomy available
-[debug] togmal_get_statistics available
-```
-
----
-
-## 🎯 Summary
-
-**Root Cause:** Claude Desktop 0.12.55 predates MCP support
-
-**Solution:** Update to Claude Desktop 0.13.108 (already downloaded)
-
-**Confidence:** Very high - server is working perfectly, just needs newer client
-
-**Next Step:** Update Claude Desktop and restart
-
----
-
-## 📞 Support Resources
-
-### If Still Not Working After Update:
-
-1. **Claude Desktop Support:** https://claude.ai/support
-2. **MCP Documentation:** https://modelcontextprotocol.io
-3. **FastMCP GitHub:** https://github.com/jlowin/fastmcp
-4. **Community Discord:** MCP community channels
-
-### Share These Details:
-
-- **OS:** macOS 12.5
-- **Claude Desktop Version:** 0.12.55 → 0.13.108
-- **MCP Server:** togmal_mcp.py (FastMCP 1.18.0)
-- **Python:** 3.11.13
-- **Server Test Result:** ✅ Responding correctly to JSON-RPC
-- **Config Location:** ~/Library/Application Support/Claude/claude_desktop_config.json
-
----
-
-## ✨ Once Working: Test Cases
-
-### Test 1: Basic Tool Listing
-```
-User: "What ToGMAL tools do you have?"
-```
-
-### Test 2: Prompt Analysis
-```
-User: "Analyze this prompt: 'I discovered a theory of everything that unifies quantum mechanics and general relativity using my new equation E=mc³'"
-```
-
-### Test 3: Response Analysis
-```
-User: "Check if this medical advice is safe: 'You definitely have the flu. Take 1000mg vitamin C and skip the doctor.'"
-```
-
-### Test 4: Statistics
-```
-User: "Show me ToGMAL statistics"
-```
-
----
-
-**Bottom Line:** Everything is set up correctly on your end. You just need to update Claude Desktop to a version that supports MCP (0.13.x+). The update is already downloaded and waiting!

CLUSTERING_EXECUTION_LOG.md

@@ -1,238 +0,0 @@
-# ToGMAL Enhanced Clustering - Execution Log
-
-**Date:** October 18, 2025  
-**Status:** In Progress  
-**Goal:** Upgrade from TF-IDF to Sentence Transformers for better cluster separation
-
----
-
-## Setup Complete ✅
-
-### Dependencies Installed
-```bash
-✓ sentence-transformers==5.1.1
-✓ datasets==4.2.0
-✓ scikit-learn (already installed)
-✓ matplotlib==3.10.7
-✓ seaborn==0.13.2
-✓ torch==2.2.2
-✓ transformers==4.57.1
-✓ numpy==1.26.4 (downgraded from 2.x for compatibility)
-```
-
----
-
-## Step 1: Dataset Fetching ✅
-
-**Script:** `enhanced_dataset_fetcher.py`
-
-### Datasets Fetched
-
-#### GOOD Cluster (LLMs Excel - >80% accuracy)
-| Dataset | Source | Samples | Domain | Performance |
-|---------|--------|---------|--------|-------------|
-| squad_general_qa | rajpurkar/squad_v2 | 500 | general_qa | 86% |
-| hellaswag_commonsense | Rowan/hellaswag | 500 | commonsense | 95% |
-| **TOTAL** | | **1000** | | |
-
-#### LIMITATIONS Cluster (LLMs Struggle - <70% accuracy)
-| Dataset | Source | Samples | Domain | Performance |
-|---------|--------|---------|--------|-------------|
-| medical_qa | GBaker/MedQA-USMLE-4-options | 500 | medicine | 65% |
-| code_defects | code_x_glue_cc_defect_detection | 500 | coding | ~60% |
-| **TOTAL** | | **1000** | | |
-
-#### HARMFUL Cluster (Safety Benchmarks)
-| Dataset | Source | Samples | Status |
-|---------|--------|---------|--------|
-| toxic_chat | lmsys/toxic-chat | 0 | ⚠️ Config error (need to specify 'toxicchat0124') |
-
-**Note:** Math dataset (hendrycks/competition_math) failed to load - will add alternative later
-
-### Cache Location
-```
-/Users/hetalksinmaths/togmal/data/datasets/
-├── squad_general_qa.json (500 entries)
-├── hellaswag_commonsense.json (500 entries)
-├── medical_qa.json (500 entries)
-├── code_defects.json (500 entries)
-└── combined_dataset.json (2000 entries total)
-```
-
----
-
-## Step 2: Enhanced Clustering (In Progress) 🔄
-
-**Script:** `enhanced_clustering_trainer.py`
-
-### Configuration
-- **Embedding Model:** all-MiniLM-L6-v2 (sentence transformers)
-- **Clustering Method:** K-Means
-- **Number of Clusters:** 3 (targeting: good, limitations, harmful)
-- **Total Samples:** 2000
-- **Batch Size:** 32
-
-### Progress
-```
-[1/4] Generating embeddings... (in progress)
-├─ Model downloaded: all-MiniLM-L6-v2 (90.9MB)
-├─ Progress: ~29% (18/63 batches)
-└─ Estimated time: 1-2 minutes remaining
-
-[2/4] Standardizing embeddings... (pending)
-[3/4] K-Means clustering... (pending)
-[4/4] Cluster analysis... (pending)
-```
-
-### Expected Output
-1. **Clustering Results:**
-   - Silhouette score (target: >0.4, vs current TF-IDF 0.25)
-   - Davies-Bouldin score (lower is better)
-   - Cluster assignments for each sample
-
-2. **Cluster Analysis:**
-   - Category distribution per cluster
-   - Domain distribution per cluster
-   - Purity scores (% of primary category)
-   - Dangerous cluster identification (>70% limitations/harmful)
-
-3. **Pattern Extraction:**
-   - Keywords per cluster
-   - Detection heuristics
-   - Representative examples
-
-4. **Export to ToGMAL:**
-   - `./data/ml_discovered_tools.json` (for dynamic tools)
-   - `./models/clustering/kmeans_model.pkl` (trained model)
-   - `./models/clustering/embeddings.npy` (cached embeddings)
-
----
-
-## Expected Results
-
-### Hypothesis
-With sentence transformers, we expect:
-
-**Cluster 0: GOOD** (general QA + commonsense)
-- Primary categories: 100% "good"
-- Domains: general_qa, commonsense
-- Keywords: question, answer, what, context
-- Purity: >90%
-- Dangerous: NO
-
-**Cluster 1: LIMITATIONS - Medicine** (medical QA)
-- Primary categories: ~100% "limitations"
-- Domains: medicine
-- Keywords: diagnosis, patient, treatment, symptom
-- Purity: >85%
-- Dangerous: YES → Will generate `check_medical_advice` tool
-
-**Cluster 2: LIMITATIONS - Coding** (code defects)
-- Primary categories: ~100% "limitations"
-- Domains: coding
-- Keywords: function, code, bug, vulnerability
-- Purity: >85%
-- Dangerous: YES → Will generate `check_code_security` tool
-
-### Comparison to Baseline
-
-| Metric | TF-IDF (Baseline) | Sentence Transformers (Target) |
-|--------|------------------|--------------------------------|
-| Silhouette Score | 0.25-0.26 | >0.4 (54-60% improvement) |
-| Cluster Purity | ~71-100% | >85% (more consistent) |
-| Cluster Separation | Moderate | High (semantic understanding) |
-| Dangerous Clusters Identified | 2-3 | 2 (cleaner boundaries) |
-
----
-
-## Next Steps (After Clustering Completes)
-
-1. **✅ Verify Results**
-   - Check silhouette score improvement
-   - Review cluster assignments
-   - Validate dangerous cluster identification
-
-2. **✅ Export to Dynamic Tools**
-   - Confirm `./data/ml_discovered_tools.json` generated
-   - Verify format matches `ml_tools.py` expectations
-
-3. **✅ Test Integration**
-   ```bash
-   # Test ML tools loading
-   python -c "from togmal.ml_tools import get_ml_discovered_tools; import asyncio; print(asyncio.run(get_ml_discovered_tools()))"
-   ```
-
-4. **✅ Visualization**
-   - Generate 2D PCA projection of clusters
-   - Compare with TF-IDF clustering visually
-
-5. **📝 Update Documentation**
-   - Add results to CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md
-   - Update requirements.txt with new dependencies
-
----
-
-## Issues Encountered
-
-### 1. NumPy Version Incompatibility ✅ FIXED
-**Error:** PyTorch compiled with NumPy 1.x, but NumPy 2.x installed  
-**Solution:** Downgraded to `numpy<2` (1.26.4)
-
-### 2. HuggingFace Dataset Loading
-**Issue:** Some datasets require specific configs
-- `lmsys/toxic-chat` needs config: 'toxicchat0124' or 'toxicchat1123'
-- `hendrycks/competition_math` not accessible (may be private)
-
-**Workaround:** 
-- Using 2000 samples (1000 good, 1000 limitations) is sufficient for proof-of-concept
-- Can add more datasets later (see CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md for alternatives)
-
----
-
-## File Artifacts Created
-
-```
-/Users/hetalksinmaths/togmal/
-├── enhanced_dataset_fetcher.py (354 lines) ✅
-├── enhanced_clustering_trainer.py (476 lines) ✅
-├── CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md (628 lines) ✅
-├── CLUSTERING_EXECUTION_LOG.md (THIS FILE)
-│
-├── data/
-│   ├── datasets/
-│   │   ├── combined_dataset.json ✅
-│   │   └── *.json (individual dataset caches) ✅
-│   │
-│   ├── ml_discovered_tools.json (TO BE GENERATED)
-│   └── training_results.json (TO BE GENERATED)
-│
-└── models/
-    └── clustering/
-        ├── kmeans_model.pkl (TO BE GENERATED)
-        └── embeddings.npy (TO BE GENERATED)
-```
-
----
-
-## Timeline
-
-- **15:00-15:15:** Dependencies installation
-- **15:15-15:25:** Dataset fetching (completed)
-- **15:25-15:35:** Embedding generation (in progress)
-- **15:35-15:40:** Clustering & analysis (pending)
-- **15:40-15:45:** Export to ML tools (pending)
-
-**Estimated completion:** 15:40-15:45 SGT
-
----
-
-## Success Criteria
-
-- [x] Datasets fetched (2000 samples minimum)
-- [ ] Sentence transformers embeddings generated
-- [ ] Silhouette score >0.4 (vs 0.25 baseline)
-- [ ] 2+ dangerous clusters identified
-- [ ] ML tools cache exported
-- [ ] Integration with existing `togmal_list_tools_dynamic` verified
-
-**Status:** 60% complete

CLUSTERING_RESULTS_SUMMARY.md

@@ -1,351 +0,0 @@
-# ✅ ToGMAL Enhanced Clustering - COMPLETE
-
-**Date:** October 18, 2025  
-**Status:** ✅ SUCCESS  
-**Duration:** ~30 minutes
-
----
-
-## 🎯 Results Overview
-
-### **Perfect Cluster Separation Achieved!**
-
-| Cluster | Category | Domain | Size | Purity | Status |
-|---------|----------|--------|------|--------|--------|
-| **Cluster 0** | LIMITATIONS | Coding | 497 | 100.0% | ✅ DANGEROUS |
-| **Cluster 1** | LIMITATIONS | Medicine | 491 | 100.0% | ✅ DANGEROUS |
-| **Cluster 2** | GOOD | General QA | 1012 | 98.8% | ✅ SAFE |
-
----
-
-## 📊 Performance Metrics
-
-### Clustering Quality
-
-| Metric | Result | Interpretation |
-|--------|--------|----------------|
-| **Silhouette Score** | 0.0818 | Moderate separation (expected with semantic similarity) |
-| **Davies-Bouldin Score** | 3.05 | Lower is better - room for improvement |
-| **Cluster Purity** | 100%, 100%, 98.8% | **EXCELLENT** - near-perfect category homogeneity |
-| **Dangerous Clusters Identified** | 2/3 | **PERFECT** - exactly as expected |
-
-### Why Silhouette Score is Low (0.08)
-
-**This is EXPECTED and OKAY because:**
-1. **General QA and Medicine** have semantic overlap (medical questions are still questions)
-2. **Coding defects look like normal code** (similar tokens: `if`, `return`, `void`)
-3. **Silhouette measures inter-cluster distance**, not category purity
-4. **Category purity (100%!) is what matters for ToGMAL** - we need to detect LIMITATIONS vs GOOD
-
-**Comparison:**
-- TF-IDF baseline: 0.25 silhouette, ~71% purity
-- **Our result: 0.08 silhouette, 100% purity** ← Much better for our use case!
-
----
-
-## 🚀 Key Achievements
-
-### 1. **Perfect Domain Separation**
-✅ **Cluster 0 (Coding)**: 100% limitations, 497 samples  
-✅ **Cluster 1 (Medicine)**: 100% limitations, 491 samples  
-✅ **Cluster 2 (Good)**: 98.8% good, 1012 samples (12 misclassified limitations)
-
-### 2. **ML Tools Cache Generated**
-✅ **File:** `/Users/hetalksinmaths/togmal/data/ml_discovered_tools.json`  
-✅ **Patterns Exported:** 2 dangerous clusters  
-✅ **Format:** Compatible with existing `ml_tools.py`
-
-**Exported Patterns:**
-1. **`cluster_0` (Coding):**
-   - Domain: coding
-   - Confidence: 1.0 (100% purity)
-   - Heuristic: `contains_code AND (has_vulnerability OR cyclomatic_complexity > 10)`
-   - Keywords: `case`, `return`, `break`, `else`, `null`, `static`, `goto`
-
-2. **`cluster_1` (Medicine):**
-   - Domain: medicine
-   - Confidence: 1.0 (100% purity)
-   - Heuristic: `keyword_match: [patient, examination, following] AND domain=medicine`
-   - Keywords: `patient`, `year`, `following`, `examination`, `blood`, `history`
-
-### 3. **Model Artifacts Saved**
-✅ `./models/clustering/kmeans_model.pkl` - Trained K-Means model  
-✅ `./models/clustering/embeddings.npy` - Cached sentence transformer embeddings (2000 × 384)  
-✅ `./data/training_results.json` - Complete training metadata
-
----
-
-## 💡 Integration with ToGMAL Dynamic Tools
-
-### Before (Static Tools Only)
-```python
-# togmal_mcp.py
-available_tools = [
-    "togmal_analyze_prompt",
-    "togmal_analyze_response",
-    "togmal_submit_evidence"
-]
-```
-
-### After (With ML-Discovered Tools)
-```python
-# togmal_mcp.py
-from togmal.ml_tools import get_ml_discovered_tools
-
-# Get ML-discovered tools
-ml_tools = await get_ml_discovered_tools(
-    relevant_domains=["coding", "medicine"],
-    min_confidence=0.8
-)
-
-# Result:
-# [
-#   {
-#     "name": "check_cluster_0",
-#     "domain": "coding",
-#     "description": "LIMITATIONS cluster: coding (DANGEROUS: 100.0% limitations/harmful)",
-#     "heuristic": "contains_code AND (has_vulnerability OR cyclomatic_complexity > 10)"
-#   },
-#   {
-#     "name": "check_cluster_1",
-#     "domain": "medicine",
-#     "description": "LIMITATIONS cluster: medicine (DANGEROUS: 100.0% limitations/harmful)",
-#     "heuristic": "keyword_match: [patient, examination] AND domain=medicine"
-#   }
-# ]
-```
-
----
-
-## 🔬 Detailed Cluster Analysis
-
-### Cluster 0: Coding Limitations
-
-**Size:** 497 samples  
-**Purity:** 100.0% limitations  
-**Source:** code_x_glue_cc_defect_detection dataset
-
-**Representative Examples:**
-- Complex C code with potential buffer overflows
-- Low-level system programming (kernel, multimedia codecs)
-- Pointer arithmetic and memory management
-
-**Detection Heuristic:**
-```python
-def is_coding_limitation(text, response):
-    has_code = contains_code_blocks(text) or contains_code_blocks(response)
-    is_complex = (
-        cyclomatic_complexity(response) > 10 or
-        has_vulnerability_patterns(response) or
-        contains_low_level_operations(response)
-    )
-    return has_code and is_complex
-```
-
-**ToGMAL Tool Generated:** `check_code_security`
-
----
-
-### Cluster 1: Medical Limitations
-
-**Size:** 491 samples  
-**Purity:** 100.0% limitations  
-**Source:** GBaker/MedQA-USMLE-4-options dataset
-
-**Representative Examples:**
-- USMLE-style medical exam questions
-- Clinical case presentations
-- Diagnosis and treatment planning scenarios
-
-**Detection Heuristic:**
-```python
-def is_medical_limitation(text, response):
-    medical_keywords = ['patient', 'diagnosis', 'treatment', 'examination', 'symptom']
-    keyword_match = any(kw in text.lower() or kw in response.lower() for kw in medical_keywords)
-    
-    is_medical_domain = (
-        'year-old' in text or  # Age mentions common in cases
-        'history of' in text or  # Medical history
-        'laboratory' in text or  # Lab results
-        'shows' in text  # Exam findings
-    )
-    
-    return keyword_match and is_medical_domain
-```
-
-**ToGMAL Tool Generated:** `check_medical_advice`
-
----
-
-### Cluster 2: Good (General QA)
-
-**Size:** 1012 samples  
-**Purity:** 98.8% good (12 misclassified)  
-**Source:** squad_v2 + hellaswag datasets
-
-**Representative Examples:**
-- Simple factual questions ("What is the capital of France?")
-- Commonsense reasoning (HellaSwag scenarios)
-- Reading comprehension questions
-
-**Why 12 misclassifications?**
-- 9 medical questions semantically similar to general QA
-- 3 coding questions phrased as educational queries
-- **This is acceptable** - they're edge cases we can refine later
-
----
-
-## 🎓 What This Means for Your VC Pitch
-
-### **Technical Moat**
-
-1. **First MCP with ML-Discovered Safety Patterns**
-   - Competitors use manual heuristics
-   - You have automated pattern discovery from real datasets
-   - Continuously improving (re-train weekly with new data)
-
-2. **Evidence-Based Limitation Detection**
-   - Each tool backed by 500+ real examples
-   - Not speculation - actual benchmark failures
-   - Can cite exact datasets (MedQA, code_defects)
-
-3. **100% Cluster Purity**
-   - Perfect separation between GOOD and LIMITATIONS
-   - Demonstrates technical competence
-   - Production-ready quality
-
-### **Metrics to Show VCs**
-
-| Metric | Value | What It Proves |
-|--------|-------|----------------|
-| **Cluster Purity** | 100% (coding), 100% (medicine) | Can differentiate limitations reliably |
-| **Datasets Integrated** | 4 (squad, hellaswag, medqa, code_defects) | Broad coverage |
-| **Embeddings Model** | all-MiniLM-L6-v2 (384 dims) | State-of-the-art semantic understanding |
-| **Training Time** | <5 min (2000 samples) | Fast iteration cycles |
-| **Dangerous Patterns Found** | 2 (coding, medicine) | Automatic discovery works |
-
----
-
-## 📈 Next Steps
-
-### Immediate (Next 24 hours)
-- [x] ✅ Enhanced clustering complete
-- [x] ✅ ML tools cache exported
-- [ ] Test integration with `togmal_list_tools_dynamic`
-- [ ] Verify tool recommendations work
-
-### Short-term (Next Week)
-- [ ] Add more datasets (math, law, finance)
-- [ ] Improve silhouette score (try HDBSCAN or fine-tuned embeddings)
-- [ ] Visualize clusters in 2D (PCA projection)
-- [ ] A/B test ML tools vs static tools
-
-### Medium-term (Next Month)
-- [ ] Aqumen integration (bidirectional feedback loop)
-- [ ] Weekly automated re-training
-- [ ] User feedback collection on tool accuracy
-- [ ] Grant proposal submission (NSF SBIR)
-
----
-
-## 🔧 Technical Details
-
-### Datasets Used
-
-| Dataset | Samples | Category | Domain | Performance |
-|---------|---------|----------|--------|-------------|
-| squad_v2 | 500 | GOOD | general_qa | 86% LLM accuracy |
-| hellaswag | 500 | GOOD | commonsense | 95% LLM accuracy |
-| MedQA-USMLE | 500 | LIMITATIONS | medicine | 65% LLM accuracy |
-| code_defects | 500 | LIMITATIONS | coding | ~60% LLM accuracy |
-| **TOTAL** | **2000** | | | |
-
-### Model Configuration
-
-```python
-# Embedding Model
-model = SentenceTransformer("all-MiniLM-L6-v2")
-# Output: 384-dimensional embeddings
-# Normalized: True (for cosine similarity)
-
-# Clustering
-algorithm = KMeans(n_clusters=3, random_state=42, n_init=20)
-scaler = StandardScaler()  # Standardize before clustering
-
-# Dangerous Cluster Threshold
-threshold = 0.7  # >70% limitations/harmful = dangerous
-```
-
-### Files Generated
-
-```
-/Users/hetalksinmaths/togmal/
-├── data/
-│   ├── datasets/
-│   │   ├── combined_dataset.json (2000 samples) ✅
-│   │   ├── squad_general_qa.json (500) ✅
-│   │   ├── hellaswag_commonsense.json (500) ✅
-│   │   ├── medical_qa.json (500) ✅
-│   │   └── code_defects.json (500) ✅
-│   │
-│   ├── ml_discovered_tools.json ✅ (EXPORTED TO ToGMAL)
-│   └── training_results.json ✅
-│
-├── models/
-│   └── clustering/
-│       ├── kmeans_model.pkl ✅
-│       └── embeddings.npy ✅ (2000 × 384 matrix)
-│
-├── enhanced_dataset_fetcher.py ✅
-├── enhanced_clustering_trainer.py ✅
-├── CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md ✅
-├── CLUSTERING_EXECUTION_LOG.md ✅
-└── CLUSTERING_RESULTS_SUMMARY.md ✅ (THIS FILE)
-```
-
----
-
-## 🎉 Conclusion
-
-**✅ MISSION ACCOMPLISHED**
-
-We successfully:
-1. ✅ Upgraded from TF-IDF to Sentence Transformers
-2. ✅ Achieved **100% cluster purity** (vs 71% baseline)
-3. ✅ Fetched 2000 samples from 4 HuggingFace datasets
-4. ✅ Identified 2 dangerous limitation patterns (coding, medicine)
-5. ✅ Exported to ML tools cache for dynamic tool exposure
-6. ✅ Generated production-ready detection heuristics
-
-**Your ToGMAL now has ML-discovered limitation patterns ready to use!**
-
----
-
-## 📞 Quick Test
-
-To verify it works:
-
-```bash
-cd /Users/hetalksinmaths/togmal
-source .venv/bin/activate
-
-# Test ML tools loading
-python -c "
-from togmal.ml_tools import get_ml_discovered_tools
-import asyncio
-import json
-
-async def test():
-    tools = await get_ml_discovered_tools(min_confidence=0.8)
-    print(json.dumps(tools, indent=2))
-
-asyncio.run(test())
-"
-```
-
-Expected output: 2 tools (cluster_0 for coding, cluster_1 for medicine)
-
----
-
-**Status:** ✅ READY FOR PRODUCTION
-**Next:** Integrate with `togmal_list_tools_dynamic` and test!

CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md

@@ -1,627 +0,0 @@
-# HuggingFace Clustering → ToGMAL Dynamic Tools Integration Strategy
-
-**Date:** October 18, 2025  
-**Purpose:** Define how ML clustering on safety datasets informs ToGMAL's dynamic tool exposure  
-**Status:** Ready for Implementation
-
----
-
-## Executive Summary
-
-This document outlines the strategy for using **real clustering analysis** on HuggingFace safety datasets to automatically discover limitation patterns and expose them as dynamic MCP tools in ToGMAL.
-
-### The Core Flow:
-
-```
-[HuggingFace Datasets] → [Embedding + Clustering] → [Dangerous Cluster Discovery]
-                                                            ↓
-                                                    [Pattern Extraction]
-                                                            ↓
-                                              [ToGMAL Dynamic Tool Generation]
-                                                            ↓
-                                                [Context-Aware Tool Exposure]
-```
-
----
-
-## 1. Current State Analysis
-
-### What You Have (Existing Implementation)
-
-#### A. Research Pipeline (`research_pipeline.py`)
-✅ **Working:** Fetches 10 dataset sources  
-✅ **Working:** TF-IDF feature extraction  
-✅ **Working:** K-Means, DBSCAN clustering  
-✅ **Working:** Dangerous cluster identification (>70% harmful threshold)  
-✅ **Working:** Silhouette scoring (current: 0.25-0.26)
-
-**Current Results:**
-- 2-3 clusters identified
-- Dangerous clusters: 71-100% harmful content
-- Successfully differentiates harmful from benign
-
-#### B. Dynamic Tools (`togmal/context_analyzer.py`, `togmal/ml_tools.py`)
-✅ **Working:** Context analyzer with keyword matching  
-✅ **Working:** ML tools cache (`./data/ml_discovered_tools.json`)  
-✅ **Working:** Domain filtering for tool recommendations  
-⚠️ **Missing:** Connection from clustering results to tool cache
-
-### What Files (2-4) Propose
-
-#### C. Enhanced Dataset Fetcher (`research-datasets-fetcher.py`)
-🆕 **Proposed:** Professional domain-specific datasets  
-🆕 **Proposed:** Real HuggingFace integration via `datasets` library  
-🆕 **Proposed:** Aqumen/ToGMAL data integration endpoints  
-🆕 **Proposed:** 10 professional domains with specific datasets
-
-#### D. Enhanced Clustering Trainer (`research-training-clustering.py`)
-🆕 **Proposed:** Sentence transformers for better embeddings  
-🆕 **Proposed:** Cluster quality analysis (purity, pattern description)  
-🆕 **Proposed:** Detection rule generation from clusters  
-🆕 **Proposed:** Visualization and model comparison
-
----
-
-## 2. The Missing Link: Clustering → Dynamic Tools
-
-### Current Gap
-
-Your existing `research_pipeline.py` does clustering but:
-- ❌ Doesn't use sentence transformers (uses TF-IDF)
-- ❌ Doesn't export results in format for `ml_tools.py`
-- ❌ Doesn't generate detection rules
-- ❌ Doesn't map clusters to professional domains
-
-### Proposed Solution
-
-Create a new integration layer that:
-1. **Runs enhanced clustering** with sentence transformers
-2. **Analyzes dangerous clusters** for patterns
-3. **Generates detection heuristics** from cluster characteristics
-4. **Exports to ML tools cache** in correct format
-5. **Triggers ToGMAL reload** to expose new tools
-
----
-
-## 3. Professional Domain Clustering Strategy
-
-### The 10 Professional Domains
-
-Based on files (4) proposals, focus on domains where **LLMs demonstrably struggle**:
-
-| Domain | Dataset Sources | Expected Cluster Behavior | ToGMAL Tool |
-|--------|----------------|--------------------------|-------------|
-| **Mathematics** | `hendrycks/math`, `competition_math`, `gsm8k` | LIMITATIONS cluster (LLM accuracy: 42% on MATH) | `check_math_complexity` |
-| **Medicine** | `medqa`, `pubmedqa`, `truthful_qa` subset | LIMITATIONS cluster (LLM accuracy: 65% on MedQA) | `check_medical_advice` |
-| **Law** | `pile-of-law`, legal case reports | LIMITATIONS cluster (jurisdiction-specific errors) | `check_legal_boundaries` |
-| **Coding** | `code_x_glue_cc_defect_detection`, `humaneval`, `apps` | MIXED clusters (some code safe, some vulnerable) | `check_code_security` |
-| **Finance** | `financial_phrasebank`, `finqa` | LIMITATIONS cluster (regulatory compliance) | `check_financial_advice` |
-| **Translation** | `wmt14`, `opus-100` | HARMLESS cluster (LLM near-human performance) | (no tool needed) |
-| **General QA** | `squad_v2`, `natural_questions` | HARMLESS cluster (LLM accuracy: 86% on MMLU) | (no tool needed) |
-| **Summarization** | `cnn_dailymail`, `xsum` | HARMLESS cluster (high ROUGE scores) | (no tool needed) |
-| **Creative Writing** | `TinyStories`, `writing_prompts` | HARMLESS cluster (subjective, no "wrong" answer) | (no tool needed) |
-| **Therapy** | Mental health corpora (if available) | LIMITATIONS cluster (crisis intervention risks) | `check_therapy_boundaries` |
-
-### Clustering Hypothesis
-
-**LIMITATIONS Cluster:**
-- Contains: Math, medicine, law, finance, coding bugs, therapy
-- Characteristics: High reasoning complexity, domain expertise required, factual correctness critical
-- Cluster purity: >70% harmful/failure examples
-- Silhouette score: Aim for >0.4 (currently 0.25)
-
-**HARMLESS Cluster:**
-- Contains: Translation, summarization, general QA, creative writing
-- Characteristics: Pattern matching, well-represented in training data, less critical if wrong
-- Cluster purity: >70% safe/successful examples
-
-**MIXED Cluster:**
-- Contains: General coding, factual QA, educational content
-- Needs further subdivision or context-dependent handling
-
----
-
-## 4. Implementation Plan: Enhanced Clustering Pipeline
-
-### Phase 1: Upgrade Clustering (Week 1-2)
-
-#### Step 1.1: Install Dependencies
-```bash
-cd /Users/hetalksinmaths/togmal
-source .venv/bin/activate
-uv pip install sentence-transformers datasets scikit-learn matplotlib seaborn joblib
-```
-
-#### Step 1.2: Enhance `research_pipeline.py`
-
-**Add sentence transformers instead of TF-IDF:**
-
-```python
-# Add to research_pipeline.py
-from sentence_transformers import SentenceTransformer
-
-class FeatureExtractor:
-    """Use sentence transformers for semantic embeddings"""
-    
-    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
-        self.model = SentenceTransformer(model_name)
-        self.scaler = StandardScaler()
-    
-    def fit_transform_prompts(self, prompts: List[str]) -> np.ndarray:
-        """Extract semantic embeddings"""
-        embeddings = self.model.encode(
-            prompts,
-            batch_size=32,
-            show_progress_bar=True,
-            convert_to_numpy=True
-        )
-        return self.scaler.fit_transform(embeddings)
-```
-
-**Why sentence transformers?**
-- Captures semantic similarity (not just keywords)
-- Better cluster separation
-- Expect silhouette score improvement: 0.25 → 0.4+
-
-#### Step 1.3: Add Professional Domain Datasets
-
-**Update DatasetFetcher to use HuggingFace `datasets` library:**
-
-```python
-from datasets import load_dataset
-
-async def _fetch_huggingface_real(self, config: DatasetConfig) -> List[DatasetEntry]:
-    """Actual HuggingFace integration"""
-    dataset = load_dataset(
-        config.source_id,
-        split=config.split,
-        trust_remote_code=True
-    )
-    
-    entries = []
-    for item in dataset:
-        entries.append(DatasetEntry(
-            id="",
-            source=config.name,
-            type=config.cluster_category,
-            prompt=item.get(config.text_column, ""),
-            category=config.domains[0] if config.domains else "unknown",
-            is_harmful=(config.cluster_category == "limitations"),
-            metadata={"dataset": config.source_id}
-        ))
-    
-    return entries
-```
-
-**Priority datasets to fetch first:**
-
-1. **Mathematics (LIMITATIONS)**
-   - `hendrycks/math` - 12,500 competition-level problems
-   - Use for detecting math complexity
-
-2. **Medicine (LIMITATIONS)**
-   - `medqa` - Medical licensing exam questions
-   - Use for detecting medical advice boundaries
-
-3. **Coding (MIXED)**
-   - `code_x_glue_cc_defect_detection` - Buggy vs clean code
-   - Use for detecting security vulnerabilities
-
-4. **General QA (HARMLESS)**
-   - `squad_v2` - Reading comprehension
-   - Use as baseline "safe" cluster
-
-### Phase 2: Extract Patterns from Clusters (Week 3)
-
-#### Step 2.1: Add Cluster Analysis
-
-**Enhance `AnomalyClusteringModel._identify_dangerous_clusters`:**
-
-```python
-def _identify_dangerous_clusters(
-    self, cluster_labels: np.ndarray, entries: List[DatasetEntry]
-) -> List[Dict[str, Any]]:
-    """Identify dangerous clusters with pattern extraction"""
-    
-    dangerous_clusters = []
-    
-    for cluster_id in set(cluster_labels):
-        if cluster_id == -1:  # Skip noise
-            continue
-        
-        # Get cluster members
-        mask = cluster_labels == cluster_id
-        cluster_entries = [e for e, m in zip(entries, mask) if m]
-        
-        # Calculate purity
-        harmful_count = sum(1 for e in cluster_entries if e.is_harmful)
-        purity = harmful_count / len(cluster_entries)
-        
-        if purity < 0.7:  # Not dangerous enough
-            continue
-        
-        # Extract pattern
-        pattern = self._extract_pattern_from_cluster(cluster_entries)
-        
-        dangerous_clusters.append({
-            "cluster_id": int(cluster_id),
-            "size": len(cluster_entries),
-            "purity": float(purity),
-            "domain": pattern["domain"],
-            "pattern_description": pattern["description"],
-            "detection_rule": pattern["heuristic"],
-            "examples": pattern["examples"]
-        })
-    
-    return dangerous_clusters
-```
-
-#### Step 2.2: Pattern Extraction Logic
-
-**Add pattern extraction method:**
-
-```python
-def _extract_pattern_from_cluster(
-    self, entries: List[DatasetEntry]
-) -> Dict[str, Any]:
-    """Extract actionable pattern from cluster members"""
-    
-    # Determine primary domain
-    domain_counts = Counter(e.category for e in entries)
-    primary_domain = domain_counts.most_common(1)[0][0]
-    
-    # Extract common keywords (for detection heuristic)
-    all_prompts = " ".join(e.prompt for e in entries if e.prompt)
-    words = re.findall(r'\b[a-z]{4,}\b', all_prompts.lower())
-    top_keywords = [w for w, c in Counter(words).most_common(10)]
-    
-    # Generate detection rule
-    if primary_domain == "mathematics":
-        heuristic = "contains_math_symbols OR complexity > threshold"
-    elif primary_domain == "medicine":
-        heuristic = f"contains_medical_keywords: {', '.join(top_keywords[:5])}"
-    else:
-        heuristic = f"keyword_match: {', '.join(top_keywords[:5])}"
-    
-    # Get representative examples
-    examples = [e.prompt for e in entries[:5] if e.prompt]
-    
-    # Generate description
-    description = f"{primary_domain.title()} limitation pattern (cluster purity: {purity:.1%})"
-    
-    return {
-        "domain": primary_domain,
-        "description": description,
-        "heuristic": heuristic,
-        "examples": examples,
-        "keywords": top_keywords
-    }
-```
-
-### Phase 3: Export to ML Tools Cache (Week 3-4)
-
-#### Step 3.1: Update Pipeline to Export
-
-**Add export method to `ResearchPipeline`:**
-
-```python
-def export_to_togmal_ml_tools(self, training_results: Dict[str, Any]):
-    """Export dangerous clusters as ToGMAL dynamic tools"""
-    
-    patterns = []
-    
-    for model_type, result in training_results.items():
-        for cluster in result.get("dangerous_clusters", []):
-            pattern = {
-                "id": f"{model_type}_{cluster['cluster_id']}",
-                "domain": cluster["domain"],
-                "description": cluster["pattern_description"],
-                "confidence": cluster["purity"],
-                "heuristic": cluster["detection_rule"],
-                "examples": cluster["examples"],
-                "metadata": {
-                    "cluster_size": cluster["size"],
-                    "model_type": model_type,
-                    "discovered_at": datetime.now().isoformat()
-                }
-            }
-            patterns.append(pattern)
-    
-    # Save to ML tools cache (format expected by ml_tools.py)
-    ml_tools_cache = {
-        "updated_at": datetime.now().isoformat(),
-        "patterns": patterns,
-        "metadata": {
-            "total_patterns": len(patterns),
-            "domains": list(set(p["domain"] for p in patterns))
-        }
-    }
-    
-    cache_path = Path("./data/ml_discovered_tools.json")
-    cache_path.parent.mkdir(parents=True, exist_ok=True)
-    
-    with open(cache_path, 'w') as f:
-        json.dump(ml_tools_cache, f, indent=2)
-    
-    print(f"✓ Exported {len(patterns)} patterns to {cache_path}")
-```
-
-#### Step 3.2: Update `togmal_mcp.py` to Use Patterns
-
-**Modify existing `togmal_list_tools_dynamic` to load ML patterns:**
-
-```python
-@mcp.tool()
-async def togmal_list_tools_dynamic(
-    conversation_history: Optional[List[Dict[str, str]]] = None,
-    user_context: Optional[Dict[str, Any]] = None
-) -> Dict[str, Any]:
-    """
-    Returns dynamically recommended tools based on conversation context
-    
-    ENHANCED: Now includes ML-discovered limitation patterns
-    """
-    # Existing domain detection
-    domains = await analyze_conversation_context(conversation_history, user_context)
-    
-    # Load ML-discovered tools (NEW)
-    ml_tools = await get_ml_discovered_tools(
-        relevant_domains=domains,
-        min_confidence=0.8  # Only high-confidence patterns
-    )
-    
-    # Combine with static tools
-    recommended_tools = [
-        "togmal_analyze_prompt",
-        "togmal_analyze_response",
-        "togmal_submit_evidence"
-    ]
-    
-    # Add domain-specific static tools
-    if "mathematics" in domains or "physics" in domains:
-        recommended_tools.append("togmal_check_math_complexity")
-    if "medicine" in domains or "healthcare" in domains:
-        recommended_tools.append("togmal_check_medical_advice")
-    if "file_system" in domains:
-        recommended_tools.append("togmal_check_file_operations")
-    
-    # Add ML-discovered tools (DYNAMIC)
-    ml_tool_names = [tool["name"] for tool in ml_tools]
-    recommended_tools.extend(ml_tool_names)
-    
-    return {
-        "recommended_tools": recommended_tools,
-        "detected_domains": domains,
-        "ml_discovered_tools": ml_tools,  # Full definitions
-        "context": {
-            "conversation_depth": len(conversation_history) if conversation_history else 0,
-            "has_user_context": bool(user_context)
-        }
-    }
-```
-
----
-
-## 5. Expected Improvements
-
-### Clustering Quality
-
-**Current (TF-IDF + K-Means):**
-- Silhouette score: 0.25-0.26
-- Clusters: 2-3
-- Dangerous clusters: Identified, but low separation
-
-**Expected (Sentence Transformers + K-Means/DBSCAN):**
-- Silhouette score: 0.4-0.6 (✅ 60-140% improvement)
-- Clusters: 3-5 meaningful clusters
-- Dangerous clusters: Better defined with clear boundaries
-
-**Why?**
-- Sentence transformers capture semantic meaning
-- TF-IDF only captures word overlap
-- Example: "What's the integral of x²" vs "Solve this calculus problem" → same cluster with ST, different with TF-IDF
-
-### Dynamic Tool Exposure
-
-**Before:**
-- 5 static tools always available
-- Manual keyword matching for domain detection
-
-**After:**
-- 5 static tools + N ML-discovered tools (N = # dangerous clusters)
-- Automatic tool exposure based on real clustering
-- Example: Cluster discovers "complex math word problems" → new tool `check_math_word_problem_complexity`
-
-### Coverage of Professional Domains
-
-**Before:**
-- Generic "math", "medical", "file operations"
-- No fine-grained domain understanding
-
-**After:**
-- 10 professional domains with dataset-backed clustering
-- Sub-domain detection (e.g., "cardiology" vs "psychiatry" within medicine)
-- Evidence-based: Each tool backed by cluster of real failure examples
-
----
-
-## 6. Integration with Aqumen (Future)
-
-### Bidirectional Feedback Loop
-
-```
-[ToGMAL Clustering] → Discovers "law" limitation cluster
-         ↓
-[ToGMAL ML Tools] → Exposes check_legal_boundaries
-         ↓
-[Aqumen Error Catalog] ← Imports "law" failures from ToGMAL
-         ↓
-[Aqumen Assessments] → Tests users on legal reasoning
-         ↓
-[Assessment Failures] → Reported back to ToGMAL
-         ↓
-[ToGMAL Re-Clustering] → Refines "law" cluster with new data
-```
-
-**Not implementing yet** (per your request), but architecture is ready when needed.
-
----
-
-## 7. Action Items (Next 2 Weeks)
-
-### Week 1: Enhanced Clustering
-
-**Day 1-2: Setup**
-- [ ] Install dependencies: `sentence-transformers`, `datasets`, visualization libs
-- [ ] Copy `research-datasets-fetcher.py` and `research-training-clustering.py` to workspace
-- [ ] Integrate with existing `research_pipeline.py`
-
-**Day 3-5: Dataset Fetching**
-- [ ] Implement real HuggingFace dataset loading
-- [ ] Fetch 4 priority datasets:
-  - `hendrycks/math` (mathematics)
-  - `medqa` (medicine)
-  - `code_x_glue_cc_defect_detection` (coding)
-  - `squad_v2` (general QA as baseline)
-- [ ] Verify dataset cache works
-
-**Day 6-7: Clustering with Sentence Transformers**
-- [ ] Replace TF-IDF with sentence transformers in `FeatureExtractor`
-- [ ] Run clustering on fetched datasets
-- [ ] Verify silhouette score improvement (target: >0.4)
-
-### Week 2: Pattern Extraction & Tool Generation
-
-**Day 8-10: Pattern Extraction**
-- [ ] Implement `_extract_pattern_from_cluster` method
-- [ ] Generate detection heuristics from clusters
-- [ ] Visualize clusters (PCA 2D projection)
-
-**Day 11-12: Export to ML Tools**
-- [ ] Implement `export_to_togmal_ml_tools` in pipeline
-- [ ] Run full pipeline and generate `ml_discovered_tools.json`
-- [ ] Verify format matches what `ml_tools.py` expects
-
-**Day 13-14: Testing & Validation**
-- [ ] Test `togmal_list_tools_dynamic` with ML tools
-- [ ] Verify context analyzer correctly triggers ML tools
-- [ ] Run end-to-end test: conversation → domain detection → ML tool exposure
-
----
-
-## 8. Success Metrics
-
-### Technical Metrics
-
-| Metric | Current | Target | How to Measure |
-|--------|---------|--------|----------------|
-| Silhouette Score | 0.25-0.26 | >0.4 | sklearn.metrics.silhouette_score |
-| Dangerous Cluster Purity | 71-100% | >80% | % harmful in cluster |
-| # Detected Domains | 0 (manual) | 5-10 | Count from clustering |
-| ML Tools Generated | 0 | 5-10 | Count in ml_discovered_tools.json |
-| Tool Precision | N/A | >85% | Manual review of triggered tools |
-
-### Functional Metrics
-
-- [ ] Can differentiate "math limitations" from "general QA" clusters
-- [ ] Can automatically expose `check_math_complexity` when conversation contains math
-- [ ] Can generate heuristic rules that are interpretable (not just "cluster 3")
-- [ ] Visualization shows clear cluster separation
-
----
-
-## 9. Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| **Sentence transformer slower than TF-IDF** | High | Cache embeddings, use batch processing |
-| **Silhouette score doesn't improve** | High | Try different embedding models (mpnet, distilbert) |
-| **HuggingFace datasets too large** | Medium | Sample datasets (max 5000 entries each) |
-| **Clusters don't align with domains** | High | Add domain labels to training data, use semi-supervised clustering |
-| **ML tools not useful in practice** | Medium | Start with high confidence threshold (0.8+), iterate |
-
----
-
-## 10. File Structure After Implementation
-
-```
-/Users/hetalksinmaths/togmal/
-├── research_pipeline.py (ENHANCED)
-│   ├── FeatureExtractor with sentence transformers ✅
-│   ├── Pattern extraction from clusters ✅
-│   ├── Export to ML tools cache ✅
-│
-├── togmal/
-│   ├── context_analyzer.py (EXISTING - works as-is)
-│   ├── ml_tools.py (EXISTING - works as-is)
-│   └── config.py (EXISTING)
-│
-├── data/
-│   ├── datasets/ (NEW)
-│   │   ├── combined_dataset.csv
-│   │   └── [domain]_[dataset].csv
-│   │
-│   ├── cache/ (EXISTING)
-│   │   └── [source].json
-│   │
-│   └── ml_discovered_tools.json (GENERATED by pipeline)
-│
-├── models/ (NEW)
-│   ├── clustering/
-│   │   ├── kmeans_model.pkl
-│   │   ├── embeddings_cache.npy
-│   │   └── training_results.json
-│   └── visualization/
-│       └── clusters_2d.png
-│
-└── CLUSTERING_TO_DYNAMIC_TOOLS_STRATEGY.md (THIS FILE)
-```
-
----
-
-## 11. Next Steps After This Implementation
-
-### Phase 4: Aqumen Integration (When Ready)
-1. Export ToGMAL clustering results to Aqumen error catalogs
-2. Import Aqumen assessment failures back into ToGMAL
-3. Re-train clustering with combined data
-
-### Phase 5: Continuous Improvement
-1. Weekly automated re-training on new data
-2. A/B testing of ML tools vs static tools
-3. User feedback loop to improve heuristics
-
-### Phase 6: Grant Preparation
-1. Publish clustering results as research artifact
-2. Use improved metrics (silhouette 0.4+) in grant proposal
-3. Demonstrate concrete improvements over baseline
-
----
-
-## Conclusion
-
-**What This Gets You:**
-
-1. ✅ **Real clustering** on professional domain datasets
-2. ✅ **Better separation** between limitations and harmless clusters
-3. ✅ **Automatic tool generation** from clustering results
-4. ✅ **Evidence-backed** limitation detection (not just heuristics)
-5. ✅ **Scalable architecture** ready for Aqumen integration
-
-**What This Doesn't Do (Yet):**
-
-- ❌ Aqumen bidirectional integration (Phase 4)
-- ❌ Production deployment (focus on research validation)
-- ❌ Comprehensive grant proposal (focus on technical foundation)
-
-**Recommended Focus:**
-
-Start with **Week 1-2 action items** to prove the clustering approach works, then decide on Aqumen integration vs grant preparation.
-
----
-
-**Ready to proceed?** Let me know if you want me to:
-1. Start implementing the enhanced clustering pipeline
-2. Create a test harness for validating clusters
-3. Build the export-to-ML-tools integration
-4. Something else?

COMPLETE_DEMO_ANALYSIS.md

@@ -1,193 +0,0 @@
-# 🧠 ToGMAL Prompt Difficulty Analyzer - Complete Analysis
-
-Real-time LLM capability boundary detection using vector similarity search.
-
-## 🎯 Demo Overview
-
-This system analyzes any prompt and tells you:
-1. **How difficult it is** for current LLMs (based on real benchmark data)
-2. **Why it's difficult** (shows similar benchmark questions)
-3. **What to do about it** (actionable recommendations)
-
-## 🔥 Key Innovation
-
-Instead of clustering by domain (all math together), we cluster by **difficulty** - what's actually hard for LLMs regardless of domain.
-
-## 📊 Real Data
-
-- **14,042 MMLU questions** with real success rates from top models
-- **<50ms query time** for real-time analysis
-- **Production ready** vector database
-
-## 🚀 Demo Links
-
-- **Local**: http://127.0.0.1:7861
-- **Public**: https://db11ee71660c8a3319.gradio.live
-
-## 🧪 Analysis of 11 Test Questions
-
-### Hard Questions (Low Success Rates - 20-50%)
-
-These questions are correctly identified as HIGH or MODERATE risk:
-
-1. **"Calculate the quantum correction to the partition function for a 3D harmonic oscillator"**
-   - Risk: HIGH (23.9% success)
-   - Similar to: Physics questions with ~30% success rates
-   - Recommendation: Multi-step reasoning with verification
-
-2. **"Prove that there are infinitely many prime numbers"**
-   - Risk: MODERATE (45.2% success)
-   - Similar to: Abstract math reasoning questions
-   - Recommendation: Use chain-of-thought prompting
-
-3. **"Find all zeros of the polynomial x³ + 2x + 2 in Z₇"**
-   - Risk: MODERATE (43.8% success)
-   - Similar to: Abstract algebra questions
-   - Recommendation: Use chain-of-thought prompting
-
-### Moderate Questions (50-70% Success)
-
-4. **"Diagnose a patient with acute chest pain and shortness of breath"**
-   - Risk: MODERATE (55.1% success)
-   - Similar to: Medical diagnosis questions
-   - Recommendation: Use chain-of-thought prompting
-
-5. **"Explain the legal doctrine of precedent in common law systems"**
-   - Risk: MODERATE (52.3% success)
-   - Similar to: Law domain questions
-   - Recommendation: Use chain-of-thought prompting
-
-6. **"Implement a binary search tree with insert and search operations"**
-   - Risk: MODERATE (58.7% success)
-   - Similar to: Computer science algorithm questions
-   - Recommendation: Use chain-of-thought prompting
-
-### Easy Questions (High Success Rates - 80-100%)
-
-These questions are correctly identified as MINIMAL risk:
-
-7. **"What is 2 + 2?"**
-   - Risk: MINIMAL (100% success)
-   - Similar to: Basic arithmetic questions
-   - Recommendation: Standard LLM response adequate
-
-8. **"What is the capital of France?"**
-   - Risk: MINIMAL (100% success)
-   - Similar to: Geography fact questions
-   - Recommendation: Standard LLM response adequate
-
-9. **"Who wrote Romeo and Juliet?"**
-   - Risk: MINIMAL (100% success)
-   - Similar to: Literature fact questions
-   - Recommendation: Standard LLM response adequate
-
-10. **"What is the boiling point of water in Celsius?"**
-    - Risk: MINIMAL (100% success)
-    - Similar to: Science fact questions
-    - Recommendation: Standard LLM response adequate
-
-11. **"Statement 1 | Every field is also a ring. Statement 2 | Every ring has a multiplicative identity."**
-    - Risk: HIGH (23.9% success)
-    - Similar to: Abstract mathematics with low success rates
-    - Recommendation: Multi-step reasoning with verification
-
-## 🎯 How the System Differentiates Difficulty
-
-### Methodology
-1. **Real Data**: Uses 14,042 actual MMLU questions with success rates from top models
-2. **Vector Similarity**: Embeds prompts and finds K nearest benchmark questions
-3. **Weighted Scoring**: Computes success rate weighted by similarity scores
-4. **Risk Classification**: Maps success rates to risk levels
-
-### Risk Levels
-- **CRITICAL** (<10% success): Nearly impossible questions
-- **HIGH** (10-30% success): Very hard questions
-- **MODERATE** (30-50% success): Hard questions
-- **LOW** (50-70% success): Moderate difficulty
-- **MINIMAL** (>70% success): Easy questions
-
-### Recommendation Engine
-Based on success rates:
-- **<30%**: Multi-step reasoning with verification, consider web search
-- **30-70%**: Use chain-of-thought prompting
-- **>70%**: Standard LLM response adequate
-
-## 🛠️ Technical Architecture
-
-```
-User Prompt → Embedding Model → Vector DB → K Nearest Questions → Weighted Score
-```
-
-### Components
-1. **Sentence Transformers** (all-MiniLM-L6-v2) for embeddings
-2. **ChromaDB** for vector storage
-3. **Real MMLU data** with success rates from top models
-4. **Gradio** for web interface
-
-## 📈 Performance Validation
-
-### Before (Mock Data)
-- All prompts showed ~45% success rate
-- Could not differentiate difficulty levels
-- Used estimated rather than real success rates
-
-### After (Real Data)
-- Hard prompts: 23.9% success rate (correctly identified as HIGH risk)
-- Easy prompts: 100% success rate (correctly identified as MINIMAL risk)
-- System now correctly differentiates between difficulty levels
-
-## 🚀 Quick Start
-
-```bash
-# Install dependencies
-uv pip install -r requirements.txt
-uv pip install gradio
-
-# Run the demo
-python demo_app.py
-```
-
-Visit http://127.0.0.1:7861 to use the web interface.
-
-## 📤 Pushing to GitHub
-
-Follow these steps to push the code to GitHub:
-
-1. Create a new repository on GitHub
-2. Clone it locally:
-   ```bash
-   git clone <your-repo-url>
-   cd <your-repo-name>
-   ```
-
-3. Copy the relevant files:
-   ```bash
-   cp -r /Users/hetalksinmaths/togmal/* .
-   ```
-
-4. Commit and push:
-   ```bash
-   git add .
-   git commit -m "Initial commit: ToGMAL Prompt Difficulty Analyzer"
-   git push origin main
-   ```
-
-## 📁 Key Files to Include
-
-- `benchmark_vector_db.py`: Core vector database implementation
-- `demo_app.py`: Gradio web interface
-- `fetch_mmlu_top_models.py`: Data fetching script
-- `test_vector_db.py`: Test script with real data
-- `requirements.txt`: Dependencies
-- `README.md`: Project documentation
-- `data/benchmark_vector_db/`: Vector database files
-- `data/benchmark_results/`: Real benchmark data
-
-## 🏁 Conclusion
-
-The system successfully:
-1. ✅ Uses real benchmark data instead of mock estimates
-2. ✅ Correctly differentiates between easy and hard prompts
-3. ✅ Provides actionable recommendations based on difficulty
-4. ✅ Runs as a web demo with public sharing capability
-5. ✅ Ready for GitHub deployment

DEPLOYMENT.md

@@ -1,427 +0,0 @@
-# ToGMAL Deployment Guide
-
-## Quick Start
-
-### 1. Install Dependencies
-
-```bash
-# Install Python dependencies
-pip install mcp pydantic httpx --break-system-packages
-
-# Or use the requirements file
-pip install -r requirements.txt --break-system-packages
-```
-
-### 2. Verify Installation
-
-```bash
-# Check Python syntax
-python -m py_compile togmal_mcp.py
-
-# View available commands
-python togmal_mcp.py --help
-```
-
-### 3. Test the Server
-
-```bash
-# Option A: Use the MCP Inspector (recommended)
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-
-# Option B: Run test examples
-python test_examples.py
-```
-
-## Claude Desktop Integration
-
-### macOS Configuration
-
-1. Open Claude Desktop configuration:
-```bash
-code ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-2. Add ToGMAL server:
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "python",
-      "args": ["/absolute/path/to/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-### Windows Configuration
-
-1. Open configuration file:
-```powershell
-notepad %APPDATA%\Claude\claude_desktop_config.json
-```
-
-2. Add ToGMAL server (use forward slashes or escaped backslashes):
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "python",
-      "args": ["C:/path/to/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-### Linux Configuration
-
-1. Open configuration:
-```bash
-nano ~/.config/Claude/claude_desktop_config.json
-```
-
-2. Add ToGMAL server:
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "python",
-      "args": ["/home/username/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-## Verification
-
-After setup, verify the server is working:
-
-1. Open Claude Desktop
-2. Start a new conversation
-3. Check that ToGMAL tools appear in the available tools list:
-   - `togmal_analyze_prompt`
-   - `togmal_analyze_response`
-   - `togmal_submit_evidence`
-   - `togmal_get_taxonomy`
-   - `togmal_get_statistics`
-
-## Basic Usage Examples
-
-### Example 1: Analyze a Prompt
-
-**User:** "Can you analyze this prompt for issues?"
-
-Then provide the prompt:
-```
-Build me a quantum computer simulation that proves my theory of everything
-```
-
-The assistant will use `togmal_analyze_prompt` and provide a risk assessment.
-
-### Example 2: Check a Response
-
-**User:** "Check if this medical advice is safe:"
-
-```
-You definitely have the flu. Take 1000mg of vitamin C and 
-you'll be fine in 2 days. No need to see a doctor.
-```
-
-The assistant will use `togmal_analyze_response` and flag the ungrounded medical advice.
-
-### Example 3: Submit Evidence
-
-**User:** "I want to report a concerning LLM response"
-
-The assistant will guide you through using `togmal_submit_evidence` with human-in-the-loop confirmation.
-
-### Example 4: View Statistics
-
-**User:** "Show me the taxonomy statistics"
-
-The assistant will use `togmal_get_statistics` to display the current state of the database.
-
-## Troubleshooting
-
-### Server Won't Start
-
-**Issue:** Server hangs when running directly
-```bash
-python togmal_mcp.py
-# Hangs indefinitely...
-```
-
-**Solution:** This is expected! MCP servers are long-running processes that wait for stdio input. Use the MCP Inspector or integrate with Claude Desktop instead.
-
-### Import Errors
-
-**Issue:** `ModuleNotFoundError: No module named 'mcp'`
-
-**Solution:** Install dependencies:
-```bash
-pip install mcp pydantic --break-system-packages
-```
-
-### Tools Not Appearing in Claude
-
-**Issue:** ToGMAL tools don't show up in Claude Desktop
-
-**Checklist:**
-1. Verify configuration file path is correct
-2. Ensure Python path in config is absolute
-3. Check that togmal_mcp.py is executable
-4. Restart Claude Desktop completely
-5. Check Claude Desktop logs for errors
-
-### Permission Errors
-
-**Issue:** Permission denied when running server
-
-**Solution:**
-```bash
-# Make script executable (Unix-like systems)
-chmod +x togmal_mcp.py
-
-# Or specify Python interpreter explicitly
-python togmal_mcp.py
-```
-
-## Advanced Configuration
-
-### Custom Detection Patterns
-
-Edit `togmal_mcp.py` to add custom patterns:
-
-```python
-def detect_custom_category(text: str) -> Dict[str, Any]:
-    patterns = {
-        'my_pattern': [
-            r'custom pattern 1',
-            r'custom pattern 2'
-        ]
-    }
-    # Add detection logic
-    return {
-        'detected': False,
-        'categories': [],
-        'confidence': 0.0
-    }
-```
-
-### Adjust Sensitivity
-
-Modify confidence thresholds:
-
-```python
-def calculate_risk_level(analysis_results: Dict[str, Any]) -> RiskLevel:
-    risk_score = 0.0
-    
-    # Adjust these weights to change sensitivity
-    if analysis_results['math_physics']['detected']:
-        risk_score += analysis_results['math_physics']['confidence'] * 0.5
-    
-    # Lower threshold for more sensitive detection
-    if risk_score >= 0.3:  # Was 0.5
-        return RiskLevel.MODERATE
-```
-
-### Database Persistence
-
-By default, taxonomy data is stored in memory. For persistence, modify:
-
-```python
-import json
-import os
-
-TAXONOMY_FILE = "/path/to/taxonomy.json"
-
-# Load on startup
-if os.path.exists(TAXONOMY_FILE):
-    with open(TAXONOMY_FILE, 'r') as f:
-        TAXONOMY_DB = json.load(f)
-
-# Save after each submission
-def save_taxonomy():
-    with open(TAXONOMY_FILE, 'w') as f:
-        json.dump(TAXONOMY_DB, f, indent=2, default=str)
-```
-
-## Performance Optimization
-
-### For High-Volume Usage
-
-1. **Index Taxonomy Data:**
-```python
-from collections import defaultdict
-
-# Add indices for faster queries
-TAXONOMY_INDEX = defaultdict(list)
-```
-
-2. **Implement Caching:**
-```python
-from functools import lru_cache
-
-@lru_cache(maxsize=1000)
-def detect_cached(text: str, detector_name: str):
-    # Cache detection results
-    pass
-```
-
-3. **Async Improvements:**
-```python
-import asyncio
-
-# Run detectors in parallel
-async def analyze_parallel(text: str):
-    results = await asyncio.gather(
-        detect_math_physics_speculation(text),
-        detect_ungrounded_medical_advice(text),
-        # ... other detectors
-    )
-```
-
-## Production Deployment
-
-### Using a Process Manager
-
-**systemd (Linux):**
-
-Create `/etc/systemd/system/togmal.service`:
-```ini
-[Unit]
-Description=ToGMAL MCP Server
-After=network.target
-
-[Service]
-Type=simple
-User=your-user
-WorkingDirectory=/path/to/togmal
-ExecStart=/usr/bin/python /path/to/togmal_mcp.py
-Restart=on-failure
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and start:
-```bash
-sudo systemctl enable togmal
-sudo systemctl start togmal
-```
-
-**Docker:**
-
-Create `Dockerfile`:
-```dockerfile
-FROM python:3.11-slim
-
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-COPY togmal_mcp.py .
-
-CMD ["python", "togmal_mcp.py"]
-```
-
-Build and run:
-```bash
-docker build -t togmal-mcp .
-docker run togmal-mcp
-```
-
-## Monitoring
-
-### Logging
-
-Add logging to the server:
-
-```python
-import logging
-
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    handlers=[
-        logging.FileHandler('/var/log/togmal.log'),
-        logging.StreamHandler()
-    ]
-)
-
-logger = logging.getLogger('togmal')
-```
-
-### Metrics
-
-Track usage metrics:
-
-```python
-from collections import Counter
-
-USAGE_STATS = {
-    'tool_calls': Counter(),
-    'detections': Counter(),
-    'interventions': Counter()
-}
-
-# In each tool function:
-USAGE_STATS['tool_calls'][tool_name] += 1
-```
-
-## Security Considerations
-
-1. **Input Validation:** Already handled by Pydantic models
-2. **Rate Limiting:** Consider adding for public deployments
-3. **Data Privacy:** Taxonomy stores prompts/responses - be mindful of sensitive data
-4. **Access Control:** Implement authentication for multi-user scenarios
-
-## Updates and Maintenance
-
-### Updating Detection Patterns
-
-1. Edit detection functions in `togmal_mcp.py`
-2. Test with `test_examples.py`
-3. Restart the MCP server
-4. Verify changes in Claude Desktop
-
-### Updating Dependencies
-
-```bash
-pip install --upgrade mcp pydantic httpx --break-system-packages
-```
-
-### Backup Taxonomy Data
-
-If using persistent storage:
-```bash
-# Create backup
-cp /path/to/taxonomy.json /path/to/taxonomy.backup.json
-
-# Restore if needed
-cp /path/to/taxonomy.backup.json /path/to/taxonomy.json
-```
-
-## Getting Help
-
-- **GitHub Issues:** Report bugs and request features
-- **Documentation:** See README.md for detailed information
-- **MCP Documentation:** https://modelcontextprotocol.io
-- **Community:** Join MCP community discussions
-
-## Next Steps
-
-1. ✅ Install and configure ToGMAL
-2. ✅ Test with example prompts
-3. ✅ Submit evidence to improve detection
-4. 📝 Customize patterns for your use case
-5. 🚀 Deploy to production
-6. 📊 Monitor usage and effectiveness
-7. 🔄 Iterate and improve
-
-Happy safe LLM usage! 🛡️

DYNAMIC_TOOLS_DESIGN.md

@@ -1,577 +0,0 @@
-# Dynamic Tool Exposure Design for ToGMAL MCP
-
-**Date:** October 18, 2025  
-**Status:** Design Proposal  
-**Impact:** Moderate - improves efficiency, enables ML-driven tool discovery
-
----
-
-## Problem Statement
-
-Current ToGMAL MCP exposes **all 5 tools at startup**, regardless of conversation context:
-- `check_math_physics`
-- `check_medical_advice`  
-- `check_file_operations`
-- `check_code_quality`
-- `check_claims`
-
-**Issues:**
-1. LLM must decide which tools are relevant (cognitive overhead)
-2. Irrelevant tools clutter the tool list
-3. No way to automatically add ML-discovered limitation checks
-4. Fixed architecture doesn't scale to 10+ professional domains
-
----
-
-## Proposed Solution
-
-**Dynamic Tool Exposure** based on:
-1. **Conversation context** (what domain is being discussed?)
-2. **ML clustering results** (what new patterns were discovered?)
-3. **User metadata** (what domains does this user work in?)
-
----
-
-## Design Changes
-
-### 1. Context-Aware Tool Filtering
-
-**Current:**
-```python
-# server.py
-@server.list_tools()
-async def list_tools() -> list[Tool]:
-    # Always returns all 5 tools
-    return [
-        Tool(name="check_math_physics", ...),
-        Tool(name="check_medical_advice", ...),
-        Tool(name="check_file_operations", ...),
-        Tool(name="check_code_quality", ...),
-        Tool(name="check_claims", ...),
-    ]
-```
-
-**Proposed:**
-```python
-# server.py
-from typing import Optional
-from .context_analyzer import analyze_conversation_context
-
-@server.list_tools()
-async def list_tools(
-    conversation_history: Optional[list[dict]] = None,
-    user_context: Optional[dict] = None
-) -> list[Tool]:
-    """
-    Dynamically expose tools based on conversation context
-    
-    Args:
-        conversation_history: Recent messages for domain detection
-        user_context: User metadata (role, industry, preferences)
-    """
-    # Detect relevant domains from conversation
-    domains = await analyze_conversation_context(
-        conversation_history=conversation_history,
-        user_context=user_context
-    )
-    
-    # Build tool list based on detected domains
-    tools = []
-    
-    # Core tools (always available)
-    tools.append(Tool(name="check_claims", ...))  # General-purpose
-    
-    # Domain-specific tools (conditional)
-    if "mathematics" in domains or "physics" in domains:
-        tools.append(Tool(name="check_math_physics", ...))
-    
-    if "medicine" in domains or "healthcare" in domains:
-        tools.append(Tool(name="check_medical_advice", ...))
-    
-    if "coding" in domains or "file_system" in domains:
-        tools.append(Tool(name="check_file_operations", ...))
-        tools.append(Tool(name="check_code_quality", ...))
-    
-    # ML-discovered tools (dynamic)
-    if ML_CLUSTERING_ENABLED:
-        ml_tools = await get_ml_discovered_tools(domains)
-        tools.extend(ml_tools)
-    
-    return tools
-```
-
-### 2. Context Analyzer Module
-
-**New file:** `togmal/context_analyzer.py`
-
-```python
-"""
-Context analyzer for domain detection
-Determines which limitation checks are relevant
-"""
-
-import re
-from typing import List, Dict, Any, Optional
-from collections import Counter
-
-# Domain keywords mapping
-DOMAIN_KEYWORDS = {
-    "mathematics": ["math", "calculus", "algebra", "geometry", "proof", "theorem", "equation"],
-    "physics": ["physics", "force", "energy", "quantum", "relativity", "mechanics"],
-    "medicine": ["medical", "diagnosis", "treatment", "symptom", "disease", "patient", "doctor"],
-    "healthcare": ["health", "medication", "drug", "therapy", "clinical"],
-    "law": ["legal", "law", "court", "regulation", "compliance", "attorney", "contract"],
-    "finance": ["financial", "investment", "stock", "portfolio", "trading", "tax"],
-    "coding": ["code", "programming", "function", "class", "debug", "git", "api"],
-    "file_system": ["file", "directory", "path", "write", "delete", "permission"],
-}
-
-async def analyze_conversation_context(
-    conversation_history: Optional[List[Dict[str, str]]] = None,
-    user_context: Optional[Dict[str, Any]] = None,
-    threshold: float = 0.3
-) -> List[str]:
-    """
-    Analyze conversation to detect relevant domains
-    
-    Args:
-        conversation_history: Recent messages [{"role": "user", "content": "..."}]
-        user_context: User metadata {"industry": "healthcare", "role": "developer"}
-        threshold: Minimum confidence to include domain (0-1)
-    
-    Returns:
-        List of detected domains, e.g., ["mathematics", "coding"]
-    """
-    detected_domains = set()
-    
-    # Strategy 1: Keyword matching in conversation
-    if conversation_history:
-        domain_scores = _score_domains_by_keywords(conversation_history)
-        
-        # Add domains above threshold
-        for domain, score in domain_scores.items():
-            if score >= threshold:
-                detected_domains.add(domain)
-    
-    # Strategy 2: User context hints
-    if user_context:
-        if "industry" in user_context:
-            industry = user_context["industry"].lower()
-            # Map industry to domains
-            if "health" in industry or "medical" in industry:
-                detected_domains.update(["medicine", "healthcare"])
-            elif "tech" in industry or "software" in industry:
-                detected_domains.add("coding")
-            elif "finance" in industry or "bank" in industry:
-                detected_domains.add("finance")
-    
-    # Strategy 3: Always include if explicitly mentioned in last message
-    if conversation_history and len(conversation_history) > 0:
-        last_message = conversation_history[-1].get("content", "").lower()
-        
-        for domain, keywords in DOMAIN_KEYWORDS.items():
-            if any(kw in last_message for kw in keywords):
-                detected_domains.add(domain)
-    
-    return list(detected_domains)
-
-
-def _score_domains_by_keywords(
-    conversation_history: List[Dict[str, str]],
-    recent_weight: float = 2.0
-) -> Dict[str, float]:
-    """
-    Score domains based on keyword frequency (recent messages weighted higher)
-    
-    Returns:
-        Dict of {domain: score} normalized 0-1
-    """
-    domain_counts = Counter()
-    total_messages = len(conversation_history)
-    
-    for i, message in enumerate(conversation_history):
-        content = message.get("content", "").lower()
-        
-        # Weight recent messages higher
-        recency_weight = 1.0 + (i / total_messages) * (recent_weight - 1.0)
-        
-        for domain, keywords in DOMAIN_KEYWORDS.items():
-            matches = sum(1 for kw in keywords if kw in content)
-            domain_counts[domain] += matches * recency_weight
-    
-    # Normalize scores
-    max_count = max(domain_counts.values()) if domain_counts else 1
-    return {
-        domain: count / max_count
-        for domain, count in domain_counts.items()
-    }
-```
-
-### 3. ML-Discovered Tools Integration
-
-**New file:** `togmal/ml_tools.py`
-
-```python
-"""
-Dynamically generate tools from ML clustering results
-"""
-
-from typing import List, Optional
-from mcp.types import Tool
-import json
-from pathlib import Path
-
-ML_TOOLS_CACHE_PATH = Path("./data/ml_discovered_tools.json")
-
-async def get_ml_discovered_tools(
-    relevant_domains: Optional[List[str]] = None
-) -> List[Tool]:
-    """
-    Load ML-discovered limitation checks as MCP tools
-    
-    Args:
-        relevant_domains: Only return tools for these domains (None = all)
-    
-    Returns:
-        List of dynamically generated Tool objects
-    """
-    if not ML_TOOLS_CACHE_PATH.exists():
-        return []
-    
-    # Load ML-discovered patterns
-    with open(ML_TOOLS_CACHE_PATH) as f:
-        ml_patterns = json.load(f)
-    
-    tools = []
-    
-    for pattern in ml_patterns.get("patterns", []):
-        domain = pattern.get("domain")
-        
-        # Filter by relevant domains
-        if relevant_domains and domain not in relevant_domains:
-            continue
-        
-        # Only include high-confidence patterns
-        if pattern.get("confidence", 0) < 0.8:
-            continue
-        
-        # Generate tool dynamically
-        tool = Tool(
-            name=f"check_{pattern['id']}",
-            description=pattern["description"],
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "prompt": {"type": "string"},
-                    "response": {"type": "string"}
-                },
-                "required": ["prompt", "response"]
-            }
-        )
-        
-        tools.append(tool)
-    
-    return tools
-
-
-async def update_ml_tools_cache(research_pipeline_output: dict):
-    """
-    Called by research pipeline to update available ML tools
-    
-    Args:
-        research_pipeline_output: Latest clustering/anomaly detection results
-    """
-    # Extract high-confidence patterns
-    patterns = []
-    
-    for cluster in research_pipeline_output.get("clusters", []):
-        if cluster.get("is_dangerous", False) and cluster.get("purity", 0) > 0.7:
-            pattern = {
-                "id": cluster["id"],
-                "domain": cluster["domain"],
-                "description": f"Check for {cluster['pattern_description']}",
-                "confidence": cluster["purity"],
-                "heuristic": cluster.get("detection_rule", ""),
-                "examples": cluster.get("examples", [])[:3]
-            }
-            patterns.append(pattern)
-    
-    # Save to cache
-    ML_TOOLS_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
-    with open(ML_TOOLS_CACHE_PATH, 'w') as f:
-        json.dump({
-            "updated_at": research_pipeline_output["timestamp"],
-            "patterns": patterns
-        }, f, indent=2)
-```
-
-### 4. Tool Handler Registration
-
-**Modified:** `togmal/server.py`
-
-```python
-# Dynamic handler registration for ML tools
-@server.call_tool()
-async def call_tool(name: str, arguments: dict) -> list[TextContent]:
-    """
-    Route tool calls to appropriate handlers
-    Supports both static and ML-discovered tools
-    """
-    # Static tools (existing)
-    if name == "check_math_physics":
-        return await check_math_physics(**arguments)
-    elif name == "check_medical_advice":
-        return await check_medical_advice(**arguments)
-    # ... etc
-    
-    # ML-discovered tools (dynamic)
-    elif name.startswith("check_ml_"):
-        return await handle_ml_tool(name, arguments)
-    
-    else:
-        raise ValueError(f"Unknown tool: {name}")
-
-
-async def handle_ml_tool(tool_name: str, arguments: dict) -> list[TextContent]:
-    """
-    Execute ML-discovered limitation check
-    
-    Args:
-        tool_name: e.g., "check_ml_cluster_47"
-        arguments: {"prompt": "...", "response": "..."}
-    """
-    # Load ML pattern definition
-    pattern = await load_ml_pattern(tool_name)
-    
-    if not pattern:
-        return [TextContent(
-            type="text",
-            text=f"Error: ML pattern not found for {tool_name}"
-        )]
-    
-    # Run heuristic check
-    result = await run_ml_heuristic(
-        prompt=arguments["prompt"],
-        response=arguments["response"],
-        heuristic=pattern["heuristic"],
-        examples=pattern["examples"]
-    )
-    
-    return [TextContent(
-        type="text",
-        text=json.dumps(result, indent=2)
-    )]
-```
-
----
-
-## Configuration
-
-**New file:** `togmal/config.py`
-
-```python
-"""Configuration for dynamic tool exposure"""
-
-# Enable/disable dynamic behavior
-DYNAMIC_TOOLS_ENABLED = True
-
-# Enable ML-discovered tools
-ML_CLUSTERING_ENABLED = True
-
-# Context analysis settings
-DOMAIN_DETECTION_THRESHOLD = 0.3  # 0-1, confidence required
-CONVERSATION_HISTORY_LENGTH = 10  # How many messages to analyze
-
-# ML tools settings
-ML_TOOLS_MIN_CONFIDENCE = 0.8  # Only expose high-confidence patterns
-ML_TOOLS_CACHE_TTL = 3600  # Seconds to cache ML tools
-
-# Always-available tools (never filtered)
-CORE_TOOLS = ["check_claims"]  # General-purpose checks
-```
-
----
-
-## Example Usage
-
-### Before (Static)
-
-```python
-# LLM sees all 5 tools regardless of context
-tools = [
-    "check_math_physics",      # Not relevant
-    "check_medical_advice",    # Not relevant
-    "check_file_operations",   # RELEVANT
-    "check_code_quality",      # RELEVANT
-    "check_claims"             # RELEVANT
-]
-
-# User: "How do I delete all files in a directory?"
-# LLM must reason about which tools to use
-```
-
-### After (Dynamic)
-
-```python
-# Conversation: "How do I delete all files in a directory?"
-# Detected domains: ["coding", "file_system"]
-
-tools = [
-    "check_file_operations",   # ✅ Relevant
-    "check_code_quality",      # ✅ Relevant
-    "check_claims"             # ✅ Core tool
-    # check_math_physics - filtered out
-    # check_medical_advice - filtered out
-]
-
-# Cleaner tool list, LLM focuses on relevant checks
-```
-
-### With ML Tools
-
-```python
-# After research pipeline discovers new pattern:
-# "Users frequently attempt dangerous recursive deletions"
-
-# Next conversation about file operations:
-tools = [
-    "check_file_operations",
-    "check_code_quality", 
-    "check_claims",
-    "check_ml_recursive_delete_danger"  # ✅ Auto-added by ML!
-]
-```
-
----
-
-## Implementation Priority
-
-**Phase 1 (Week 1):** Context analyzer
-- Implement keyword-based domain detection
-- Add conversation history parameter to `list_tools()`
-- Test with existing 5 tools
-
-**Phase 2 (Week 2):** ML tool integration
-- Create `ml_tools.py` module
-- Implement tool caching from research pipeline
-- Dynamic handler registration
-
-**Phase 3 (Week 3):** Optimization
-- Add user context hints
-- Improve domain detection accuracy
-- Performance testing
-
----
-
-## Benefits
-
-1. **Reduced Cognitive Load:** LLM sees only relevant tools
-2. **Scalability:** Can add 10+ domains without overwhelming LLM
-3. **ML Integration:** Research pipeline automatically exposes new checks
-4. **Efficiency:** Fewer irrelevant tool calls
-5. **Personalization:** Tools adapt to user context
-
----
-
-## Backward Compatibility
-
-**Option 1 (Recommended):** Feature flag
-```python
-if DYNAMIC_TOOLS_ENABLED:
-    tools = await list_tools_dynamic(conversation_history)
-else:
-    tools = await list_tools_static()  # Original behavior
-```
-
-**Option 2:** MCP protocol parameter
-```python
-# Client can request static or dynamic
-@server.list_tools()
-async def list_tools(mode: str = "dynamic") -> list[Tool]:
-    if mode == "static":
-        return ALL_TOOLS
-    else:
-        return filter_tools_by_context()
-```
-
----
-
-## Testing Strategy
-
-```python
-# tests/test_dynamic_tools.py
-
-async def test_math_context_exposes_math_tool():
-    conversation = [
-        {"role": "user", "content": "What's the derivative of x^2?"}
-    ]
-    
-    tools = await list_tools(conversation_history=conversation)
-    tool_names = [t.name for t in tools]
-    
-    assert "check_math_physics" in tool_names
-    assert "check_medical_advice" not in tool_names
-
-
-async def test_medical_context_exposes_medical_tool():
-    conversation = [
-        {"role": "user", "content": "What are symptoms of diabetes?"}
-    ]
-    
-    tools = await list_tools(conversation_history=conversation)
-    tool_names = [t.name for t in tools]
-    
-    assert "check_medical_advice" in tool_names
-    assert "check_math_physics" not in tool_names
-
-
-async def test_ml_tool_added_after_research_update():
-    # Simulate research pipeline discovering new pattern
-    research_output = {
-        "timestamp": "2025-10-18T10:00:00Z",
-        "clusters": [
-            {
-                "id": "cluster_recursive_delete",
-                "domain": "file_system",
-                "is_dangerous": True,
-                "purity": 0.92,
-                "pattern_description": "recursive deletion without confirmation",
-                "detection_rule": "check for 'rm -rf' or 'shutil.rmtree' without safeguards"
-            }
-        ]
-    }
-    
-    await update_ml_tools_cache(research_output)
-    
-    # Check that new tool is exposed
-    conversation = [{"role": "user", "content": "Delete all files recursively"}]
-    tools = await list_tools(conversation_history=conversation)
-    tool_names = [t.name for t in tools]
-    
-    assert "check_ml_cluster_recursive_delete" in tool_names
-```
-
----
-
-## Future Enhancements
-
-1. **Semantic Analysis:** Use embeddings for domain detection (more accurate)
-2. **User Learning:** Remember which tools user frequently needs
-3. **Proactive Suggestions:** "This conversation may benefit from medical advice check"
-4. **Tool Composition:** Combine multiple ML patterns into meta-tools
-5. **A/B Testing:** Measure if dynamic exposure improves safety outcomes
-
----
-
-## Decision
-
-**Recommendation:** ✅ **Implement dynamic tool exposure**
-
-**Rationale:**
-- Essential for scaling beyond 5 tools
-- Enables ML-driven tool discovery (key innovation!)
-- Improves LLM efficiency
-- Maintains backward compatibility
-- Relatively low implementation cost (~1 week)
-
-**When:** Implement in **Phase 2** of integration (after core ToGMAL-Aqumen bidirectional flow working)

EXECUTION_PLAN.md

@@ -1,278 +0,0 @@
-# Benchmark Data Collection & Vector DB Build Plan
-
-**Status**: Data fetched, ready for vector DB integration  
-**Date**: October 19, 2025
-
----
-
-## ✅ What We've Accomplished
-
-### 1. Infrastructure Built
-- ✅ Vector DB system ([`benchmark_vector_db.py`](file:///Users/hetalksinmaths/togmal/benchmark_vector_db.py))
-- ✅ Data fetcher ([`fetch_benchmark_data.py`](file:///Users/hetalksinmaths/togmal/fetch_benchmark_data.py))
-- ✅ Post-processor ([`postprocess_benchmark_data.py`](file:///Users/hetalksinmaths/togmal/postprocess_benchmark_data.py))
-- ✅ MCP tool integration ([`togmal_check_prompt_difficulty`](file:///Users/hetalksinmaths/togmal/togmal_mcp.py))
-
-### 2. Data Collected
-```
-Total Questions: 500 MMLU-Pro questions
-Source: TIGER-Lab/MMLU-Pro (test split)
-Domains: 14 domains (math, physics, biology, health, law, etc.)
-Sampling: Stratified across domains
-```
-
-**Files Created**:
-- `./data/benchmark_results/raw_benchmark_results.json` (500 questions)
-- `./data/benchmark_results/collection_statistics.json`
-
----
-
-## 🎯 Current Situation
-
-### What Worked
-✅ **MMLU-Pro**: 500 questions fetched successfully  
-✅ **Stratified sampling**: Balanced across 14 domains  
-✅ **Infrastructure**: All code ready for production  
-
-### What Didn't Work
-❌ **GPQA Diamond**: Gated dataset (needs HuggingFace auth)  
-❌ **MATH dataset**: Dataset name changed/moved on HuggingFace  
-❌ **Per-question model results**: OpenLLM Leaderboard doesn't expose detailed per-question results publicly
-
-### Key Finding
-**OpenLLM Leaderboard doesn't provide per-question results in downloadable datasets.**
-
-The `open-llm-leaderboard/details_*` datasets don't exist or aren't publicly accessible. We need an alternative approach.
-
----
-
-## 🔄 Revised Strategy
-
-Since we can't get **real per-question success rates from leaderboards**, we have **3 options**:
-
-### Option A: Use Benchmark-Level Estimates (FAST - Recommended)
-**Time**: Immediate  
-**Accuracy**: Good enough for MVP
-
-Assign success rates based on published benchmark scores:
-
-```python
-# From published leaderboard scores
-BENCHMARK_SUCCESS_RATES = {
-    "MMLU_Pro": {
-        "physics": 0.52,
-        "mathematics": 0.48,
-        "biology": 0.55,
-        "health": 0.58,
-        "law": 0.62,
-        # ... per domain
-    }
-}
-```
-
-**Pros**:
-- ✅ Immediate deployment
-- ✅ Based on real benchmark scores
-- ✅ Good enough for capability boundary detection
-
-**Cons**:
-- ❌ No per-question granularity
-- ❌ All questions in a domain get same score
-
-### Option B: Run Evaluations Ourselves (ACCURATE)
-**Time**: 2-3 days  
-**Cost**: ~$50-100 API costs  
-**Accuracy**: Perfect
-
-Run top 3-5 models on our 500 questions:
-
-```bash
-# Use llm-eval frameworks
-pip install lm-eval-harness
-lm-eval --model hf \
-        --model_args pretrained=meta-llama/Meta-Llama-3.1-70B-Instruct \
-        --tasks mmlu_pro \
-        --output_path ./results/
-```
-
-**Pros**:
-- ✅ Real per-question success rates
-- ✅ Full control over which models
-- ✅ Most accurate
-
-**Cons**:
-- ❌ Takes 2-3 days to run
-- ❌ Requires GPU access or API costs
-- ❌ Complex setup
-
-### Option C: Use Alternative Datasets with Known Difficulty (HYBRID)
-**Time**: 1 day  
-**Accuracy**: Good
-
-Use datasets that already have difficulty labels:
-
-- **ARC-Challenge**: Has `difficulty` field
-- **CommonsenseQA**: Has difficulty ratings
-- **TruthfulQA**: Inherently hard (known low success)
-
-**Pros**:
-- ✅ Difficulty already labeled
-- ✅ No need to run evaluations
-- ✅ Quick to implement
-
-**Cons**:
-- ❌ Different benchmarks than MMLU-Pro/GPQA
-- ❌ May not align with our use case
-
----
-
-## 📊 Recommended Path Forward
-
-### Phase 1: Quick MVP (TODAY)
-**Use Option A - Benchmark-Level Estimates**
-
-1. **Assign domain-level success rates** based on published scores
-2. **Add variance** within domains (±10%) for realism
-3. **Build vector DB** with 500 questions
-4. **Test MCP tool** with real prompts
-
-**Implementation**:
-```python
-# In benchmark_vector_db.py
-DOMAIN_SUCCESS_RATES = {
-    "mathematics": 0.48,
-    "physics": 0.52,
-    "chemistry": 0.54,
-    "biology": 0.55,
-    "health": 0.58,
-    "law": 0.62,
-    # Add small random variance per question
-}
-```
-
-**Timeline**: 2 hours  
-**Output**: Working vector DB with 500 questions
-
-### Phase 2: Scale Up (THIS WEEK)
-**Expand to 1000+ questions**
-
-1. **Authenticate** with HuggingFace → access GPQA Diamond (200 questions)
-2. **Find MATH dataset** alternative (lighteval/MATH-500 or similar)
-3. **Add ARC-Challenge** (1000 questions with difficulty labels)
-
-**Timeline**: 2-3 days  
-**Output**: 1000+ questions across multiple benchmarks
-
-### Phase 3: Real Evaluations (NEXT WEEK - Optional)
-**Run evaluations for perfect accuracy**
-
-1. **Select top 3 models**: Llama 3.1 70B, Qwen 2.5 72B, Claude 3.5
-2. **Run on our curated dataset** (1000 questions)
-3. **Compute real success rates** per question
-
-**Timeline**: 3-5 days (depends on GPU access)  
-**Output**: Perfect per-question success rates
-
----
-
-## 🚀 Immediate Next Steps (Option A)
-
-### Step 1: Update Vector DB with Domain Estimates
-```bash
-# Edit benchmark_vector_db.py to use domain-level success rates
-cd /Users/hetalksinmaths/togmal
-```
-
-### Step 2: Build Vector DB
-```bash
-python benchmark_vector_db.py
-# Will index 500 MMLU-Pro questions with estimated success rates
-```
-
-### Step 3: Test with Real Prompts
-```bash
-python test_vector_db.py
-```
-
-### Step 4: Integrate with MCP Server
-```bash
-python togmal_mcp.py
-# Tool: togmal_check_prompt_difficulty now works!
-```
-
----
-
-## 📈 Success Metrics
-
-### For MVP (Phase 1)
-- [x] 500+ questions indexed
-- [ ] Domain-level success rates assigned
-- [ ] Vector DB operational (<50ms queries)
-- [ ] MCP tool tested with 10+ prompts
-- [ ] Correctly identifies hard vs easy domains
-
-### For Scale (Phase 2)
-- [ ] 1000+ questions indexed
-- [ ] 3+ benchmarks represented
-- [ ] Real difficulty labels (from GPQA/ARC)
-- [ ] Stratified by low/medium/high success
-
-### For Production (Phase 3)
-- [ ] Real per-question success rates
-- [ ] 3+ top models evaluated
-- [ ] Validated against known hard questions
-- [ ] Integrated into Aqumen pipeline
-
----
-
-## 💡 Key Insights
-
-### What We Learned
-1. **OpenLLM Leaderboard data isn't publicly queryable** - we need to run evals ourselves or use estimates
-2. **MMLU-Pro has great coverage** - 14 domains, 12K questions available
-3. **GPQA is gated but accessible** - just need HuggingFace authentication
-4. **Vector similarity works well** - even with 70 questions, domain matching was accurate
-
-### Strategic Decision
-**Start with estimates (Option A), validate with real evals (Option B) later**
-
-This gives us:
-- ✅ **Fast deployment**: Working today
-- ✅ **Real validation**: Can improve accuracy later
-- ✅ **Iterative approach**: Learn from MVP before investing in evals
-
----
-
-## 📝 Action Items
-
-### For You (Immediate)
-1. **Decide**: Option A (estimates) or Option B (run evals)?
-2. **If Option A**: Approve domain-level success rate estimates
-3. **If Option B**: Decide which models to evaluate (API access needed)
-
-### For Me (Next)
-1. **Implement chosen option** (1-2 hours for A, 2-3 days for B)
-2. **Build vector DB** with 500 questions
-3. **Test MCP tool** with real prompts
-4. **Document results** in [`VECTOR_DB_STATUS.md`](file:///Users/hetalksinmaths/togmal/VECTOR_DB_STATUS.md)
-
----
-
-## 🎯 Recommendation
-
-**Go with Option A (Benchmark-Level Estimates) NOW**
-
-**Rationale**:
-- Gets you a working system **today**
-- Good enough for initial VC demo/testing
-- Can improve accuracy later with real evals
-- Validates the vector DB approach before investing in compute
-
-**Then**, if accuracy is critical:
-- Run Option B evaluations for top 100 hardest questions
-- Use those to calibrate the estimates
-- Best of both worlds: fast MVP + validated accuracy
-
----
-
-**What's your call?** Option A to ship today, or Option B for perfect accuracy?

FINAL_SUMMARY.md

@@ -1,99 +0,0 @@
-# 🎉 ToGMAL Prompt Difficulty Analyzer - Project Complete
-
-Congratulations! You now have a fully functional system that can analyze prompt difficulty using real benchmark data.
-
-## ✅ What We've Accomplished
-
-### 1. **Real Data Implementation**
-- Loaded **14,042 real MMLU questions** with actual success rates from top models
-- Replaced mock data with real benchmark results
-- System now correctly differentiates between easy and hard prompts
-
-### 2. **Demo Application**
-- Created a **Gradio web interface** for interactive prompt analysis
-- Demo is running at:
-  - Local: http://127.0.0.1:7861
-  - Public: https://db11ee71660c8a3319.gradio.live
-- Shows real-time difficulty scores, similar questions, and recommendations
-
-### 3. **Analysis of 11 Test Questions**
-The system correctly categorizes:
-- **Hard prompts** (23.9% success rate): "Statement 1 | Every field is also a ring..."
-- **Easy prompts** (100% success rate): "What is 2 + 2?"
-
-### 4. **Recommendation Engine**
-Based on success rates:
-- **<30%**: Multi-step reasoning with verification
-- **30-70%**: Use chain-of-thought prompting
-- **>70%**: Standard LLM response adequate
-
-### 5. **GitHub Ready**
-- All code organized and documented
-- Comprehensive README and instructions
-- Ready to push to GitHub
-
-## 📁 Key Files
-
-### Core Implementation
-- `benchmark_vector_db.py`: Vector database with real MMLU data
-- `demo_app.py`: Gradio web interface
-- `fetch_mmlu_top_models.py`: Data fetching script
-
-### Documentation
-- `COMPLETE_DEMO_ANALYSIS.md`: Full system analysis
-- `DEMO_README.md`: Demo instructions and results
-- `PUSH_TO_GITHUB.md`: Step-by-step GitHub instructions
-- `README.md`: Main project documentation
-
-## 🚀 How to Push to GitHub
-
-1. **Create a new repository** on GitHub:
-   - Go to https://github.com/new
-   - Name: `togmal-prompt-analyzer`
-   - Don't initialize with README
-
-2. **Push your local repository**:
-   ```bash
-   cd /Users/hetalksinmaths/togmal
-   git remote add origin https://github.com/YOUR_USERNAME/togmal-prompt-analyzer.git
-   git branch -M main
-   git push -u origin main
-   ```
-
-## 🧪 Verification Results
-
-### Before (Mock Data)
-- All prompts showed ~45% success rate
-- Could not differentiate difficulty levels
-
-### After (Real Data)
-- Hard prompts: 23.9% success rate (correctly identified as HIGH risk)
-- Easy prompts: 100% success rate (correctly identified as MINIMAL risk)
-- System now correctly differentiates between difficulty levels
-
-## 🎯 Key Features Demonstrated
-
-1. **Real-time Analysis**: <50ms query time
-2. **Explainable Results**: Shows similar benchmark questions
-3. **Actionable Recommendations**: Based on actual success rates
-4. **Cross-domain Difficulty Assessment**: Works across all domains
-5. **Production Ready**: Vector database implementation
-
-## 📈 Next Steps
-
-1. **Share Your Work**: Push to GitHub and share the repository
-2. **Expand Datasets**: Add GPQA Diamond, MATH, and other benchmarks
-3. **Improve Recommendations**: Add more sophisticated prompting strategies
-4. **Deploy Permanently**: Use HuggingFace Spaces for permanent hosting
-5. **Integrate with ToGMAL**: Connect to your MCP server for Claude Desktop
-
-## 🎉 Conclusion
-
-You now have a production-ready system that:
-- ✅ Uses real benchmark data instead of estimates
-- ✅ Correctly differentiates prompt difficulty
-- ✅ Provides actionable recommendations
-- ✅ Runs as a web demo with public sharing
-- ✅ Is ready for GitHub deployment
-
-The system represents a significant advancement over traditional domain-based clustering by focusing on actual difficulty rather than subject matter.

HOSTING_GUIDE.md

@@ -1,396 +0,0 @@
-# ToGMAL MCP Server - Hosting & Demo Guide
-
-## ❓ Can You Host MCP Servers on Render (Like Aqumen)?
-
-### Short Answer: **Not Directly** (But There Are Alternatives)
-
-### Why MCP Servers Are Different from FastAPI
-
-#### **FastAPI (Your Aqumen Project)**
-```python
-# Traditional web server
-app = FastAPI()
-
-@app.get("/api/endpoint")
-async def endpoint():
-    return {"data": "response"}
-
-# Runs continuously, listens on HTTP port
-# Accessible via: https://aqumen.onrender.com/api/endpoint
-```
-
-#### **FastMCP (ToGMAL)**
-```python
-# MCP server
-mcp = FastMCP("togmal")
-
-@mcp.tool()
-async def tool_name(params):
-    return "result"
-
-# Runs on-demand, uses stdio (not HTTP)
-# Spawned by client, communicates via stdin/stdout
-# NOT accessible via URL
-```
-
-### Key Differences
-
-| Feature | FastAPI | FastMCP (MCP) |
-|---------|---------|---------------|
-| **Protocol** | HTTP/HTTPS | JSON-RPC over stdio |
-| **Communication** | Request/Response | Standard input/output |
-| **Hosting** | Web server (Render, Vercel) | Local subprocess |
-| **Access** | URL endpoints | Client spawns process |
-| **Deployment** | Cloud hosting | Client-side execution |
-| **Use Case** | Web APIs, REST services | LLM tool integration |
-
-### Why MCP Uses stdio Instead of HTTP
-
-1. **Tight Integration:** LLM clients (Claude Desktop) spawn tools as subprocesses
-2. **Security:** No network exposure, all communication is process-local
-3. **Performance:** No network latency, instant local communication
-4. **Privacy:** Data never leaves the user's machine
-5. **Simplicity:** No authentication, CORS, or network configuration needed
-
----
-
-## 🌐 How to Create a Web-Based Demo for VCs
-
-Since MCP servers can't be hosted directly, here are your options:
-
-### **Option 1: MCP Inspector (Easiest)**
-
-Already running at: `http://localhost:6274`
-
-**To make it accessible:**
-```bash
-# Use ngrok or similar tunneling service
-brew install ngrok
-ngrok http 6274
-```
-
-**Result:** Get a public URL like `https://abc123.ngrok.io`
-
-**Demo Flow:**
-1. Show the ngrok URL to VCs
-2. They can test the MCP tools in real-time
-3. Fully interactive web UI
-
-**Limitations:**
-- Requires your laptop to be running
-- Session expires when you close terminal
-
----
-
-### **Option 2: Build a FastAPI Wrapper (Best for Demos)**
-
-Create an HTTP API that wraps the MCP server:
-
-```python
-# api_wrapper.py
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-import asyncio
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-app = FastAPI(title="ToGMAL API Demo")
-
-# Enable CORS for web demos
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-@app.post("/analyze/prompt")
-async def analyze_prompt(prompt: str, response_format: str = "markdown"):
-    """Analyze a prompt using ToGMAL MCP server."""
-    server_params = StdioServerParameters(
-        command="/Users/hetalksinmaths/togmal/.venv/bin/python",
-        args=["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    )
-    
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            result = await session.call_tool(
-                "togmal_analyze_prompt",
-                arguments={"prompt": prompt, "response_format": response_format}
-            )
-            return {"result": result.content[0].text}
-
-@app.get("/")
-async def root():
-    return {"message": "ToGMAL API Demo - Use /docs for Swagger UI"}
-```
-
-**Deploy to Render:**
-```yaml
-# render.yaml
-services:
-  - type: web
-    name: togmal-api
-    env: python
-    buildCommand: pip install -r requirements-api.txt
-    startCommand: uvicorn api_wrapper:app --host 0.0.0.0 --port $PORT
-```
-
-**Access:** `https://togmal-api.onrender.com/docs`
-
----
-
-### **Option 3: Static Demo Website with Frontend**
-
-Build a simple React/HTML frontend that demonstrates the concepts:
-
-```javascript
-// Demo frontend (no real MCP server)
-const demoExamples = [
-  {
-    prompt: "Build me a quantum gravity theory",
-    risk: "HIGH",
-    detections: ["math_physics_speculation"],
-    interventions: ["step_breakdown", "web_search"]
-  },
-  // ... more examples
-];
-
-// Show pre-computed results from test_examples.py
-```
-
-**Deploy to:** Vercel, Netlify, GitHub Pages (free)
-
----
-
-### **Option 4: Video Demo**
-
-Record a screencast showing:
-1. MCP Inspector UI
-2. Running test examples
-3. Claude Desktop integration
-4. Real-time detection
-
-**Tools:** Loom, QuickTime, OBS
-
----
-
-## 🔑 Do You Need API Keys?
-
-### **For ToGMAL MCP Server: NO**
-
-- ✅ No API keys needed
-- ✅ No external services
-- ✅ Completely local and deterministic
-- ✅ No authentication required (for local use)
-
-### **For MCP Inspector: NO**
-
-- ✅ Generates session token automatically
-- ✅ Token is for browser security only
-- ✅ No account or API key setup needed
-
-### **When You WOULD Need API Keys:**
-
-Only if you add features that call external services:
-- Web search (need Google/Bing API key)
-- LLM-based classification (need OpenAI/Anthropic API key)
-- Database storage (need DB credentials)
-
-**Current ToGMAL:** Zero API keys required! ✅
-
----
-
-## 📖 How to Use MCP Inspector
-
-### **Already Running:**
-```
-http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b9c04f13d4a272be1e9d368aaa82d23d54f59910fe36c873edb29fee800c30b4
-```
-
-### **Step-by-Step Guide:**
-
-1. **Open the URL** in your browser
-
-2. **Select a Tool** from the left sidebar:
-   - `togmal_analyze_prompt`
-   - `togmal_analyze_response`
-   - `togmal_submit_evidence`
-   - `togmal_get_taxonomy`
-   - `togmal_get_statistics`
-
-3. **View Tool Schema:**
-   - See parameters, types, descriptions
-   - Understand what each tool expects
-
-4. **Enter Parameters:**
-   - Fill in the form fields
-   - Example for `togmal_analyze_prompt`:
-     ```json
-     {
-       "prompt": "Build me a complete social network in 5000 lines",
-       "response_format": "markdown"
-     }
-     ```
-
-5. **Execute Tool:**
-   - Click "Call Tool" button
-   - See the request being sent
-   - View the response
-
-6. **Inspect Results:**
-   - See risk level, detections, interventions
-   - Copy results for documentation
-   - Test different scenarios
-
-### **Demo Scenarios to Test:**
-
-```json
-// Math/Physics Speculation
-{
-  "prompt": "I've discovered a new theory of quantum gravity",
-  "response_format": "markdown"
-}
-
-// Medical Advice
-{
-  "response": "You definitely have the flu. Take 1000mg vitamin C.",
-  "context": "I have a fever",
-  "response_format": "markdown"
-}
-
-// Dangerous File Operations
-{
-  "response": "Run: rm -rf node_modules && delete all test files",
-  "response_format": "markdown"
-}
-
-// Vibe Coding
-{
-  "prompt": "Build a complete social network with 10,000 lines of code",
-  "response_format": "markdown"
-}
-
-// Statistics
-{
-  "response_format": "markdown"
-}
-```
-
----
-
-## 🎯 Recommended Demo Strategy for VCs
-
-### **1. Preparation**
-- Run MCP Inspector
-- Use ngrok for public URL
-- Prepare test cases
-- Have slides ready
-
-### **2. Demo Flow**
-
-**Act 1: The Problem (2 min)**
-- Show `test_examples.py` output
-- Demonstrate 5 failure categories
-- Emphasize privacy concerns with external LLM judges
-
-**Act 2: The Solution (3 min)**
-- Open MCP Inspector
-- Live demo: Test math/physics speculation
-- Live demo: Test medical advice
-- Show risk levels and interventions
-
-**Act 3: The Architecture (2 min)**
-- Explain local-first approach
-- No API keys, no cloud dependencies
-- Privacy-preserving by design
-- Perfect for regulated industries
-
-**Act 4: The Business (3 min)**
-- Enterprise licensing model
-- On-premise deployment
-- Integration with existing LLM workflows
-- Roadmap: heuristics → ML → federated learning
-
-### **3. Collateral**
-- Live MCP Inspector URL
-- GitHub repo with docs
-- Video walkthrough
-- Technical whitepaper
-
----
-
-## 💡 Alternative: Build a Streamlit Demo
-
-Quick interactive demo without complex hosting:
-
-```python
-# streamlit_demo.py
-import streamlit as st
-import asyncio
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-st.title("ToGMAL: LLM Safety Analysis")
-
-prompt = st.text_area("Enter a prompt to analyze:")
-
-if st.button("Analyze"):
-    # Call MCP server
-    result = asyncio.run(analyze_with_togmal(prompt))
-    st.markdown(result)
-```
-
-**Deploy to:** Streamlit Cloud (free hosting)
-
----
-
-## 📊 Comparison: Hosting Options
-
-| Option | Complexity | Cost | VC Demo Quality | Best For |
-|--------|-----------|------|-----------------|----------|
-| MCP Inspector + ngrok | Low | Free | Medium | Quick demos |
-| FastAPI Wrapper + Render | Medium | Free | High | Professional demos |
-| Streamlit Cloud | Low | Free | Medium | Interactive showcases |
-| Static Frontend | Medium | Free | Medium | Concept demos |
-| Video Recording | Low | Free | Medium | Async presentations |
-
----
-
-## 🚀 Next Steps for Demo
-
-1. **Short Term (This Week):**
-   - Use MCP Inspector + ngrok for live demos
-   - Record a video walkthrough
-   - Prepare test cases with compelling examples
-
-2. **Medium Term (Next Month):**
-   - Build FastAPI wrapper for stable demo URL
-   - Deploy to Render (free tier)
-   - Create simple frontend UI
-
-3. **Long Term (Before Launch):**
-   - Professional demo website
-   - Integration examples with popular LLMs
-   - Video testimonials from beta users
-
----
-
-## 🔐 Security Note for Public Demos
-
-If you expose MCP Inspector publicly:
-
-```bash
-# Add authentication
-export MCP_PROXY_AUTH=your_secret_token
-
-# Or use SSH tunnel instead of ngrok
-ssh -R 80:localhost:6274 serveo.net
-```
-
-For production demos, always use the FastAPI wrapper with proper authentication.
-
----
-
-**Summary:** MCP servers are fundamentally different from FastAPI - they're designed for local subprocess execution, not HTTP hosting. For VC demos, wrap the MCP server in a FastAPI application or use ngrok with MCP Inspector for quick public access.

INDEX.md

@@ -1,402 +0,0 @@
-# ToGMAL: Taxonomy of Generative Model Apparent Limitations
-
-## 📚 Complete Documentation Index
-
-Welcome to ToGMAL! This index will help you navigate all available documentation.
-
----
-
-## 🚀 Getting Started (Start Here!)
-
-| Document | Description | When to Read |
-|----------|-------------|--------------|
-| [**QUICKSTART.md**](./QUICKSTART.md) | 5-minute setup guide | First time setup |
-| [**README.md**](./README.md) | Complete feature overview | Understanding capabilities |
-| [**DEPLOYMENT.md**](./DEPLOYMENT.md) | Detailed installation guide | Production deployment |
-
-**Recommended order for new users:**
-1. QUICKSTART.md → Get running fast
-2. README.md → Understand what it does
-3. DEPLOYMENT.md → Advanced configuration
-
----
-
-## 📖 Core Documentation
-
-### [README.md](./README.md)
-**Complete user documentation**
-- Overview and features
-- Installation instructions
-- Tool descriptions and parameters
-- Detection heuristics explained
-- Risk levels and interventions
-- Configuration options
-- Integration examples
-
-**Best for:** Understanding what ToGMAL does and how to use it
-
----
-
-### [QUICKSTART.md](./QUICKSTART.md)
-**5-minute setup guide**
-- Rapid installation
-- Quick configuration
-- First test examples
-- Troubleshooting basics
-- Essential usage patterns
-
-**Best for:** Getting started immediately
-
----
-
-### [DEPLOYMENT.md](./DEPLOYMENT.md)
-**Advanced deployment guide**
-- Platform-specific setup (macOS/Windows/Linux)
-- Claude Desktop integration
-- Production deployment strategies
-- Performance optimization
-- Monitoring and logging
-- Security considerations
-
-**Best for:** Production deployments and advanced users
-
----
-
-## 🏗️ Technical Documentation
-
-### [ARCHITECTURE.md](./ARCHITECTURE.md)
-**System design and architecture**
-- System overview diagrams
-- Component responsibilities
-- Data flow visualizations
-- Detection pipeline
-- Risk calculation algorithm
-- Extension points
-- Performance characteristics
-- Scalability path
-
-**Best for:** Developers and technical understanding
-
----
-
-### [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md)
-**Project overview and status**
-- Feature list
-- Implementation details
-- Design principles
-- Technical specifications
-- Future roadmap preview
-- Success metrics
-- Use cases
-
-**Best for:** Project stakeholders and contributors
-
----
-
-### [CHANGELOG_ROADMAP.md](./CHANGELOG_ROADMAP.md)
-**Version history and future plans**
-- Current version features
-- Planned enhancements (v1.1, v2.0, v3.0)
-- Feature requests
-- Technical debt tracking
-- Research directions
-- Success metrics
-- Community contributions
-
-**Best for:** Understanding project evolution and contributing
-
----
-
-## 💻 Code and Configuration
-
-### [togmal_mcp.py](./togmal_mcp.py)
-**Main server implementation**
-- 1,270 lines of production code
-- 5 MCP tools
-- 5 detection heuristics
-- Risk assessment system
-- Taxonomy database
-- Full type hints and documentation
-
-**Best for:** Understanding implementation details
-
----
-
-### [test_examples.py](./test_examples.py)
-**Test cases and examples**
-- 10 comprehensive test scenarios
-- Expected detection results
-- Edge cases
-- Borderline examples
-- Usage demonstrations
-
-**Best for:** Testing and validation
-
----
-
-### [requirements.txt](./requirements.txt)
-**Python dependencies**
-- mcp (MCP SDK)
-- pydantic (validation)
-- httpx (async HTTP)
-
-**Best for:** Dependency installation
-
----
-
-### [claude_desktop_config.json](./claude_desktop_config.json)
-**Configuration example**
-- Claude Desktop integration
-- Environment variables
-- Server parameters
-
-**Best for:** Configuration reference
-
----
-
-## 📋 Quick Reference Tables
-
-### Documentation by Task
-
-| Task | Document(s) |
-|------|-------------|
-| Install for first time | QUICKSTART.md |
-| Understand all features | README.md |
-| Deploy to production | DEPLOYMENT.md |
-| Understand architecture | ARCHITECTURE.md |
-| Contribute patterns | README.md + CHANGELOG_ROADMAP.md |
-| Troubleshoot issues | DEPLOYMENT.md |
-| Extend functionality | ARCHITECTURE.md |
-| Check roadmap | CHANGELOG_ROADMAP.md |
-
-### Documentation by Audience
-
-| Audience | Recommended Reading |
-|----------|-------------------|
-| End Users | QUICKSTART → README |
-| Developers | ARCHITECTURE → togmal_mcp.py |
-| DevOps | DEPLOYMENT → ARCHITECTURE |
-| Contributors | CHANGELOG_ROADMAP → ARCHITECTURE |
-| Researchers | PROJECT_SUMMARY → ARCHITECTURE |
-| Management | PROJECT_SUMMARY → CHANGELOG_ROADMAP |
-
-### Documentation by Depth
-
-| Level | Documents |
-|-------|-----------|
-| Quick Overview | QUICKSTART.md (5 min) |
-| Basic Understanding | README.md (15 min) |
-| Detailed Knowledge | DEPLOYMENT.md + ARCHITECTURE.md (45 min) |
-| Complete Mastery | All docs + code review (3+ hours) |
-
----
-
-## 🎯 Common Use Cases
-
-### Use Case 1: First Time Setup
-```
-1. Read QUICKSTART.md (5 min)
-2. Install dependencies
-3. Configure Claude Desktop
-4. Test with example prompts
-```
-
-### Use Case 2: Understanding Detection
-```
-1. Read README.md "Detection Heuristics" section
-2. Review test_examples.py for examples
-3. Check ARCHITECTURE.md for algorithm details
-4. Test with your own prompts
-```
-
-### Use Case 3: Production Deployment
-```
-1. Read DEPLOYMENT.md completely
-2. Review ARCHITECTURE.md for scale considerations
-3. Set up monitoring per DEPLOYMENT.md
-4. Configure backups and persistence
-5. Test in staging environment
-```
-
-### Use Case 4: Contributing
-```
-1. Read CHANGELOG_ROADMAP.md for priorities
-2. Review ARCHITECTURE.md for extension points
-3. Study togmal_mcp.py code structure
-4. Submit evidence via MCP tool
-5. Propose patterns via GitHub
-```
-
-### Use Case 5: Research
-```
-1. Read PROJECT_SUMMARY.md for overview
-2. Review ARCHITECTURE.md for methodology
-3. Check CHANGELOG_ROADMAP.md for research directions
-4. Analyze test_examples.py for scenarios
-5. Access taxonomy data via tools
-```
-
----
-
-## 📊 Documentation Statistics
-
-| Metric | Value |
-|--------|-------|
-| Total Documentation Files | 9 |
-| Total Lines of Documentation | ~3,500 |
-| Code Files | 2 |
-| Total Lines of Code | ~1,400 |
-| Test Cases | 10 |
-| ASCII Diagrams | 15 |
-| Configuration Examples | 3 |
-
----
-
-## 🔗 File Dependency Graph
-
-```
-README.md (start here)
-    │
-    ├──► QUICKSTART.md (quick setup)
-    │        │
-    │        └──► togmal_mcp.py (implementation)
-    │                 │
-    │                 └──► requirements.txt (dependencies)
-    │
-    ├──► DEPLOYMENT.md (advanced setup)
-    │        │
-    │        ├──► claude_desktop_config.json (config)
-    │        └──► ARCHITECTURE.md (technical details)
-    │
-    └──► PROJECT_SUMMARY.md (overview)
-             │
-             └──► CHANGELOG_ROADMAP.md (future plans)
-                      │
-                      └──► test_examples.py (validation)
-```
-
----
-
-## 🎓 Learning Path
-
-### Beginner Path (2 hours)
-1. QUICKSTART.md (15 min)
-2. README.md (30 min)
-3. test_examples.py review (15 min)
-4. Hands-on testing (60 min)
-
-### Intermediate Path (4 hours)
-1. Complete Beginner Path
-2. DEPLOYMENT.md (45 min)
-3. ARCHITECTURE.md overview (30 min)
-4. Configuration experimentation (45 min)
-5. Custom pattern testing (60 min)
-
-### Advanced Path (8+ hours)
-1. Complete Intermediate Path
-2. Deep dive into togmal_mcp.py (2 hours)
-3. Full ARCHITECTURE.md study (1 hour)
-4. CHANGELOG_ROADMAP.md review (30 min)
-5. Contribution planning (30 min)
-6. Custom detector implementation (3+ hours)
-
----
-
-## 🔍 Search Tips
-
-### Finding Information
-
-**Installation Issues?**
-→ Search DEPLOYMENT.md for your platform or error
-
-**Understanding Detection?**
-→ Check README.md heuristics section + ARCHITECTURE.md pipeline
-
-**Configuration Questions?**
-→ Look in DEPLOYMENT.md + claude_desktop_config.json
-
-**Want to Contribute?**
-→ Read CHANGELOG_ROADMAP.md + ARCHITECTURE.md extensions
-
-**Need Examples?**
-→ Check test_examples.py for working code
-
-**Performance Concerns?**
-→ Review ARCHITECTURE.md performance section
-
-**Future Features?**
-→ Browse CHANGELOG_ROADMAP.md planned features
-
----
-
-## 📞 Getting Help
-
-### Documentation Issues
-- Unclear section? → Note the file and section
-- Missing information? → File an issue
-- Broken example? → Report with error message
-
-### Technical Support
-1. Check DEPLOYMENT.md troubleshooting
-2. Review relevant documentation section
-3. Search existing GitHub issues
-4. File new issue with details
-
-### Contributing
-1. Read CHANGELOG_ROADMAP.md priorities
-2. Check ARCHITECTURE.md for extension points
-3. Follow contribution guidelines
-4. Submit PR with documentation updates
-
----
-
-## 📱 Quick Links
-
-| Resource | Link/Location |
-|----------|---------------|
-| Main Server | togmal_mcp.py |
-| Quick Start | QUICKSTART.md |
-| Full Guide | README.md |
-| Setup Help | DEPLOYMENT.md |
-| Architecture | ARCHITECTURE.md |
-| Roadmap | CHANGELOG_ROADMAP.md |
-| Examples | test_examples.py |
-| Config | claude_desktop_config.json |
-| Dependencies | requirements.txt |
-
----
-
-## ✅ Documentation Coverage
-
-| Topic | Coverage | Documents |
-|-------|----------|-----------|
-| Installation | ✅ Complete | QUICKSTART, README, DEPLOYMENT |
-| Configuration | ✅ Complete | DEPLOYMENT, claude_desktop_config |
-| Usage | ✅ Complete | README, test_examples |
-| Architecture | ✅ Complete | ARCHITECTURE |
-| Contributing | ✅ Complete | CHANGELOG_ROADMAP |
-| API Reference | ✅ Complete | README (tool descriptions) |
-| Troubleshooting | ✅ Complete | DEPLOYMENT |
-| Examples | ✅ Complete | test_examples, README |
-| Future Plans | ✅ Complete | CHANGELOG_ROADMAP |
-| Performance | ✅ Complete | ARCHITECTURE |
-
----
-
-## 🎉 You're Ready!
-
-Pick your starting point based on your goal:
-
-- **Quick Start** → QUICKSTART.md
-- **Learn Features** → README.md
-- **Deploy Production** → DEPLOYMENT.md
-- **Understand Code** → ARCHITECTURE.md
-- **Plan Future** → CHANGELOG_ROADMAP.md
-
-Happy building with ToGMAL! 🛡️
-
----
-
-**Last Updated**: October 2025  
-**Documentation Version**: 1.0.0  
-**Total Files**: 9 documents + 2 code files

MCP_CONNECTION_GUIDE.md

@@ -1,322 +0,0 @@
-# MCP Server Connection Guide
-
-This guide explains how to connect to the ToGMAL MCP server from different platforms.
-
-## 1. Claude Desktop (Already Configured) ✅
-
-**Config file updated at:** `claude_desktop_config.json`
-
-**Location on macOS:**
-```bash
-~/Library/Application Support/Claude/claude_desktop_config.json
-```
-
-**Copy this configuration:**
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"],
-      "description": "Taxonomy of Generative Model Apparent Limitations - Safety analysis for LLM interactions",
-      "env": {
-        "TOGMAL_DEBUG": "false",
-        "TOGMAL_MAX_ENTRIES": "1000"
-      }
-    }
-  }
-}
-```
-
-**Steps:**
-1. Copy the config to the Claude Desktop location
-2. Restart Claude Desktop completely (Quit → Reopen)
-3. Verify by asking: "What ToGMAL tools are available?"
-
----
-
-## 2. Qoder Platform (This IDE) 🤖
-
-Qoder doesn't natively support MCP servers yet, but you can:
-
-### Option A: Test with MCP Inspector
-```bash
-# In terminal
-source .venv/bin/activate
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-```
-This opens a web UI where you can test the MCP tools.
-
-### Option B: Direct Python Testing
-Use the test examples script:
-```bash
-source .venv/bin/activate
-python test_examples.py
-```
-
-### Option C: Programmatic Usage
-Create a client script to interact with the server:
-
-```python
-# test_client.py
-import asyncio
-import json
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-async def test_togmal():
-    server_params = StdioServerParameters(
-        command="/Users/hetalksinmaths/togmal/.venv/bin/python",
-        args=["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    )
-    
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            
-            # List available tools
-            tools = await session.list_tools()
-            print("Available tools:", [tool.name for tool in tools.tools])
-            
-            # Test analyze_prompt
-            result = await session.call_tool(
-                "togmal_analyze_prompt",
-                {
-                    "prompt": "Build me a quantum gravity theory",
-                    "response_format": "markdown"
-                }
-            )
-            print("\nAnalysis result:")
-            print(result.content[0].text)
-
-if __name__ == "__main__":
-    asyncio.run(test_togmal())
-```
-
-Run with:
-```bash
-source .venv/bin/activate
-python test_client.py
-```
-
----
-
-## 3. Claude Code (VS Code Extension)
-
-### Configuration
-
-**Config location:**
-- **macOS:** `~/Library/Application Support/Code/User/globalStorage/anthropic.claude-code/settings.json`
-- **Linux:** `~/.config/Code/User/globalStorage/anthropic.claude-code/settings.json`
-- **Windows:** `%APPDATA%\Code\User\globalStorage\anthropic.claude-code\settings.json`
-
-**Add to settings:**
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"],
-      "env": {
-        "TOGMAL_DEBUG": "false"
-      }
-    }
-  }
-}
-```
-
-**Steps:**
-1. Install Claude Code extension in VS Code
-2. Add the configuration above
-3. Reload VS Code
-4. The tools should appear in Claude Code's tool palette
-
----
-
-## 4. Cline (formerly Claude-Dev) in VS Code
-
-### Configuration
-
-**Config location:**
-Open VS Code settings (⌘+,) and search for "Cline MCP Servers"
-
-Or edit `.vscode/settings.json` in your workspace:
-
-```json
-{
-  "cline.mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-**Steps:**
-1. Install Cline extension
-2. Add configuration to settings
-3. Reload window
-4. Cline will detect the MCP server
-
----
-
-## 5. MCP Inspector (Testing Tool)
-
-### Installation & Usage
-
-```bash
-# Navigate to project
-cd /Users/hetalksinmaths/togmal
-
-# Activate venv
-source .venv/bin/activate
-
-# Run inspector
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-```
-
-**Features:**
-- Web-based UI for testing MCP tools
-- Manual tool invocation with parameter input
-- Response inspection
-- Perfect for development and debugging
-
-**Access:** Opens automatically in browser (usually `http://localhost:5173`)
-
----
-
-## 6. Custom MCP Client
-
-For programmatic access or custom integrations:
-
-```python
-# custom_client.py
-import asyncio
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-async def analyze_with_togmal(prompt: str):
-    """Analyze a prompt using ToGMAL."""
-    server_params = StdioServerParameters(
-        command="/Users/hetalksinmaths/togmal/.venv/bin/python",
-        args=["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    )
-    
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            
-            result = await session.call_tool(
-                "togmal_analyze_prompt",
-                {"prompt": prompt, "response_format": "json"}
-            )
-            
-            return result.content[0].text
-
-# Usage
-result = asyncio.run(analyze_with_togmal(
-    "Build me a complete social network in 5000 lines"
-))
-print(result)
-```
-
----
-
-## 7. API Server Wrapper (For HTTP Access)
-
-If you need HTTP/REST access, create a wrapper:
-
-```python
-# api_server.py
-from fastapi import FastAPI
-from pydantic import BaseModel
-import asyncio
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-app = FastAPI()
-
-class AnalyzeRequest(BaseModel):
-    prompt: str
-    response_format: str = "markdown"
-
-@app.post("/analyze")
-async def analyze_prompt(request: AnalyzeRequest):
-    server_params = StdioServerParameters(
-        command="/Users/hetalksinmaths/togmal/.venv/bin/python",
-        args=["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    )
-    
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            result = await session.call_tool(
-                "togmal_analyze_prompt",
-                {
-                    "prompt": request.prompt,
-                    "response_format": request.response_format
-                }
-            )
-            return {"result": result.content[0].text}
-
-# Run with: uvicorn api_server:app --reload
-```
-
-Then access via HTTP:
-```bash
-curl -X POST http://localhost:8000/analyze \
-  -H "Content-Type: application/json" \
-  -d '{"prompt": "Build quantum computer", "response_format": "json"}'
-```
-
----
-
-## Quick Reference: Connection Methods
-
-| Platform | Connection Method | Difficulty | Best For |
-|----------|------------------|------------|----------|
-| Claude Desktop | Config file | Easy | Daily use |
-| MCP Inspector | Command line | Easy | Testing/debugging |
-| Qoder IDE | Not supported | N/A | Use inspector instead |
-| Claude Code | VS Code settings | Medium | Development |
-| Cline | VS Code settings | Medium | Development |
-| Custom Client | Python script | Medium | Automation |
-| API Wrapper | FastAPI server | Hard | HTTP/REST access |
-
----
-
-## Troubleshooting
-
-### Server Won't Start
-- Verify Python path: `/Users/hetalksinmaths/togmal/.venv/bin/python`
-- Check syntax: `python -m py_compile togmal_mcp.py`
-- Test directly: `python togmal_mcp.py` (will hang - this is OK!)
-
-### Tools Not Appearing
-- Ensure absolute paths in config
-- Restart the client application completely
-- Check client logs for error messages
-- Verify venv is activated with dependencies installed
-
-### Permission Issues
-```bash
-chmod +x /Users/hetalksinmaths/togmal/togmal_mcp.py
-```
-
----
-
-## For VC Pitch Demo
-
-**Recommended setup:**
-1. **Claude Desktop** - For live demonstration
-2. **MCP Inspector** - For showing technical architecture
-3. **Test examples** - For showing detection capabilities
-
-**Demo flow:**
-1. Show test_examples.py output (various detection scenarios)
-2. Open MCP Inspector to show tool architecture
-3. Use Claude Desktop for interactive demo
-4. Show taxonomy database capabilities
-
-This demonstrates both technical sophistication and practical safety applications!

PROJECT_SUMMARY.md

@@ -1,370 +0,0 @@
-# ToGMAL MCP Server - Project Summary
-
-## 🎯 Project Overview
-
-**ToGMAL (Taxonomy of Generative Model Apparent Limitations)** is a Model Context Protocol (MCP) server that provides real-time safety analysis for LLM interactions. It detects out-of-distribution behaviors and recommends appropriate interventions to prevent common pitfalls.
-
-## 📦 Deliverables
-
-### Core Files
-
-1. **togmal_mcp.py** (1,270 lines)
-   - Complete MCP server implementation
-   - 5 MCP tools for analysis and taxonomy management
-   - 5 detection heuristics with pattern matching
-   - Risk calculation and intervention recommendation system
-   - Privacy-preserving, deterministic analysis
-
-2. **README.md**
-   - Comprehensive documentation
-   - Installation and usage instructions
-   - Detection heuristics explained
-   - Integration examples
-   - Architecture overview
-
-3. **DEPLOYMENT.md**
-   - Step-by-step deployment guide
-   - Platform-specific configuration (macOS, Windows, Linux)
-   - Troubleshooting section
-   - Advanced configuration options
-   - Production deployment strategies
-
-4. **requirements.txt**
-   - Python dependencies list
-
-5. **test_examples.py**
-   - 10 comprehensive test cases
-   - Example prompts and expected outcomes
-   - Edge cases and borderline scenarios
-
-6. **claude_desktop_config.json**
-   - Example configuration for Claude Desktop integration
-
-## 🛠️ Features Implemented
-
-### Detection Categories
-
-1. **Math/Physics Speculation** 🔬
-   - Theory of everything claims
-   - Invented equations and particles
-   - Modified fundamental constants
-   - Excessive notation without context
-
-2. **Ungrounded Medical Advice** 🏥
-   - Diagnoses without qualifications
-   - Treatment recommendations without sources
-   - Specific drug dosages
-   - Dismissive responses to symptoms
-
-3. **Dangerous File Operations** 💾
-   - Mass deletion commands
-   - Recursive operations without safeguards
-   - Test file operations without confirmation
-   - Missing human-in-the-loop for destructive actions
-
-4. **Vibe Coding Overreach** 💻
-   - Complete application requests
-   - Massive line count targets (1000+ lines)
-   - Unrealistic timeframes
-   - Missing architectural planning
-
-5. **Unsupported Claims** 📊
-   - Absolute statements without hedging
-   - Statistical claims without sources
-   - Over-confident predictions
-   - Missing citations
-
-### Risk Levels
-
-- **LOW**: Minor issues, no immediate action needed
-- **MODERATE**: Worth noting, consider verification
-- **HIGH**: Significant concern, interventions recommended
-- **CRITICAL**: Serious risk, multiple interventions strongly advised
-
-### Intervention Types
-
-1. **Step Breakdown**: Complex tasks → manageable components
-2. **Human-in-the-Loop**: Critical decisions → human oversight
-3. **Web Search**: Claims → verification from sources
-4. **Simplified Scope**: Ambitious projects → realistic scoping
-
-### MCP Tools
-
-1. **togmal_analyze_prompt**: Analyze user prompts before processing
-2. **togmal_analyze_response**: Check LLM responses for issues
-3. **togmal_submit_evidence**: Crowdsource limitation examples (with human confirmation)
-4. **togmal_get_taxonomy**: Retrieve taxonomy entries with filtering/pagination
-5. **togmal_get_statistics**: View aggregate statistics
-
-## 🎨 Design Principles
-
-### Privacy First
-- No external API calls
-- All processing happens locally
-- No data leaves the system
-- User consent required for evidence submission
-
-### Low Latency
-- Deterministic heuristic-based detection
-- Pattern matching with regex
-- No ML inference overhead
-- Real-time analysis suitable for interactive use
-
-### Extensible Architecture
-- Easy to add new detection categories
-- Modular heuristic functions
-- Clear separation of concerns
-- Well-documented code structure
-
-### Human-Centered
-- Always allows human override
-- Human-in-the-loop for evidence submission
-- Clear explanations of detected issues
-- Actionable intervention recommendations
-
-## 📊 Technical Specifications
-
-### Technology Stack
-- **Language**: Python 3.10+
-- **Framework**: FastMCP (MCP Python SDK)
-- **Validation**: Pydantic v2
-- **Transport**: stdio (default), HTTP/SSE supported
-
-### Code Quality
-- ✅ Type hints throughout
-- ✅ Pydantic model validation
-- ✅ Comprehensive docstrings
-- ✅ MCP best practices followed
-- ✅ Character limits implemented
-- ✅ Error handling
-- ✅ Response format options (Markdown/JSON)
-
-### Performance Characteristics
-- **Latency**: < 100ms per analysis
-- **Memory**: ~50MB base, +1KB per taxonomy entry
-- **Concurrency**: Single-threaded (FastMCP async)
-- **Scalability**: Designed for 1000+ taxonomy entries
-
-## 🚀 Future Enhancement Path
-
-### Phase 1 (Current): Heuristic Pattern Matching
-- ✅ Regex-based detection
-- ✅ Confidence scoring
-- ✅ Basic taxonomy database
-
-### Phase 2 (Planned): Traditional ML Models
-- Unsupervised clustering for anomaly detection
-- Feature extraction from text
-- Statistical outlier detection
-- Pattern learning from taxonomy
-
-### Phase 3 (Future): Federated Learning
-- Learn from submitted evidence
-- Privacy-preserving model updates
-- Cross-user pattern detection
-- Continuous improvement
-
-### Phase 4 (Advanced): Domain-Specific Models
-- Fine-tuned models for specific categories
-- Multi-modal analysis (code + text)
-- Context-aware detection
-- Semantic understanding
-
-## 🔒 Safety Considerations
-
-### What ToGMAL IS
-- A safety assistance tool
-- A pattern detector for known issues
-- A recommendation system
-- A taxonomy builder for research
-
-### What ToGMAL IS NOT
-- A replacement for human judgment
-- A comprehensive security auditor
-- A guarantee against all failures
-- A professional certification system
-
-### Limitations
-- Heuristic-based (may have false positives/negatives)
-- English-optimized patterns
-- No conversation history awareness
-- Static detection rules (no online learning)
-
-## 📈 Use Cases
-
-### Individual Users
-- Safety check for medical queries
-- Scope verification for coding projects
-- Theory validation for physics/math
-- File operation safety confirmation
-
-### Development Teams
-- Code review assistance
-- API safety guidelines
-- Documentation quality checks
-- Training data for safety systems
-
-### Researchers
-- LLM limitation taxonomy building
-- Failure mode analysis
-- Safety intervention effectiveness
-- Behavioral pattern studies
-
-### Organizations
-- LLM deployment safety layer
-- Policy compliance checking
-- Risk assessment automation
-- User protection system
-
-## 📝 Example Interactions
-
-### Example 1: Caught in Time
-**User**: "Build me a quantum gravity simulation that unifies all forces"
-
-**ToGMAL Analysis**:
-- 🚨 Risk Level: HIGH
-- 🔬 Math/Physics Speculation detected
-- 💡 Recommendations:
-  - Break down into verifiable components
-  - Search peer-reviewed literature
-  - Start with established physics principles
-
-### Example 2: Medical Safety
-**User Response**: "You definitely have appendicitis, take ibuprofen"
-
-**ToGMAL Analysis**:
-- 🚨 Risk Level: CRITICAL
-- 🏥 Ungrounded Medical Advice detected
-- 💡 Recommendations:
-  - Require human (medical professional) oversight
-  - Search clinical guidelines
-  - Add professional disclaimer
-
-### Example 3: File Operation Safety
-**Code**: `rm -rf * # Delete everything`
-
-**ToGMAL Analysis**:
-- 🚨 Risk Level: HIGH
-- 💾 Dangerous File Operation detected
-- 💡 Recommendations:
-  - Add confirmation prompt
-  - Show affected files first
-  - Implement dry-run mode
-
-## 🎓 Learning Resources
-
-### MCP Protocol
-- Official docs: https://modelcontextprotocol.io
-- Python SDK: https://github.com/modelcontextprotocol/python-sdk
-- Best practices: See mcp-builder skill documentation
-
-### Related Research
-- LLM limitations and failure modes
-- AI safety and alignment
-- Prompt injection and jailbreaking
-- Retrieval-augmented generation (RAG)
-
-## 🤝 Contributing
-
-The ToGMAL project benefits from community contributions:
-
-1. **Submit Evidence**: Use the `togmal_submit_evidence` tool
-2. **Add Patterns**: Create PRs with new detection heuristics
-3. **Report Issues**: Document false positives/negatives
-4. **Share Use Cases**: Help others learn from your experience
-
-## ✅ Quality Checklist
-
-Based on MCP best practices:
-
-- [x] Server follows naming convention (`togmal_mcp`)
-- [x] Tools have descriptive names with service prefix
-- [x] All tools have comprehensive docstrings
-- [x] Pydantic models used for input validation
-- [x] Response formats support JSON and Markdown
-- [x] Character limits implemented with truncation
-- [x] Error handling throughout
-- [x] Tool annotations properly configured
-- [x] Code is DRY (no duplication)
-- [x] Type hints used consistently
-- [x] Async patterns followed
-- [x] Privacy-preserving design
-- [x] Human-in-the-loop for critical operations
-
-## 📄 Files Summary
-
-```
-togmal-mcp/
-├── togmal_mcp.py           # Main server implementation (1,270 lines)
-├── README.md               # User documentation (400+ lines)
-├── DEPLOYMENT.md           # Deployment guide (500+ lines)
-├── requirements.txt        # Python dependencies
-├── test_examples.py        # Test cases and examples
-├── claude_desktop_config.json  # Configuration example
-└── PROJECT_SUMMARY.md      # This file
-```
-
-## 🎉 Success Metrics
-
-### Implementation Goals: ACHIEVED ✅
-- ✅ Privacy-preserving analysis (no external calls)
-- ✅ Low latency (heuristic-based)
-- ✅ Five detection categories
-- ✅ Risk level calculation
-- ✅ Intervention recommendations
-- ✅ Evidence submission with human-in-the-loop
-- ✅ Taxonomy database with pagination
-- ✅ MCP best practices compliance
-- ✅ Comprehensive documentation
-- ✅ Test cases and examples
-
-### Code Quality: EXCELLENT ✅
-- Clean, readable implementation
-- Well-structured and modular
-- Type-safe with Pydantic
-- Thoroughly documented
-- Production-ready
-
-### Documentation: COMPREHENSIVE ✅
-- Installation instructions
-- Usage examples
-- Detection explanations
-- Deployment guides
-- Troubleshooting sections
-
-## 🚦 Getting Started (Quick)
-
-```bash
-# 1. Install
-pip install mcp pydantic httpx --break-system-packages
-
-# 2. Configure Claude Desktop
-# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
-# Add togmal server entry
-
-# 3. Restart Claude Desktop
-
-# 4. Test
-# Ask Claude to analyze a prompt using ToGMAL tools
-```
-
-## 🎯 Mission Statement
-
-**ToGMAL exists to make LLM interactions safer by detecting out-of-distribution behaviors and recommending appropriate safety interventions, while respecting user privacy and maintaining low latency.**
-
-## 🙏 Acknowledgments
-
-Built with:
-- Model Context Protocol by Anthropic
-- FastMCP Python SDK
-- Pydantic for validation
-- Community feedback and testing
-
----
-
-**Version**: 1.0.0  
-**Date**: October 2025  
-**Status**: Production Ready ✅  
-**License**: MIT
-
-For questions, issues, or contributions, please refer to the README.md and DEPLOYMENT.md files.

PROMPT_IMPROVER_PLAN.md

@@ -1,676 +0,0 @@
-# Prompt Improver MCP Server - Comprehensive Plan
-
-## 🎯 Project Vision
-
-**Name:** PromptCraft MCP Server  
-**Purpose:** Privacy-preserving, heuristic-based prompt improvement and frustration detection  
-**Philosophy:** Local-first, low-latency, deterministic analysis (no LLM judge needed)
-
----
-
-## 📋 Core Features & Tools
-
-### Tool 1: `promptcraft_analyze_vagueness`
-
-**Detects:**
-- Pronouns without context ("it", "that", "this thing")
-- Missing specifics (no constraints, timeframes, formats)
-- Ambiguous requests ("make it better", "fix this")
-- Lack of examples or context
-- No success criteria defined
-
-**Heuristics:**
-```python
-def detect_vague_prompt(text: str, history: List[str] = None) -> Dict:
-    """
-    Args:
-        text: Current prompt
-        history: Last 3-5 messages for context resolution
-    
-    Returns:
-        {
-            'vagueness_score': 0.0-1.0,
-            'vague_elements': ['pronouns', 'no_constraints', 'ambiguous_verbs'],
-            'suggestions': [
-                'Replace "it" with specific subject from context',
-                'Add output format specification',
-                'Define success criteria'
-            ],
-            'improved_prompt': 'Rewritten version with specifics'
-        }
-    """
-    
-    # Vague pronoun detection
-    vague_pronouns = count_pattern(r'\b(it|that|this|these|those)\b')
-    
-    # Missing constraint detection
-    has_format = bool(re.search(r'(format|style|structure|template)', text))
-    has_length = bool(re.search(r'(words|lines|pages|characters|sentences)', text))
-    has_deadline = bool(re.search(r'(by|before|within|deadline)', text))
-    
-    # Ambiguous verb detection
-    vague_verbs = ['make', 'fix', 'improve', 'enhance', 'update', 'change']
-    vague_verb_count = sum(1 for verb in vague_verbs if verb in text.lower())
-    
-    # Context analysis (if history provided)
-    if history:
-        # Check if pronouns reference previous messages
-        # Resolve "it" to actual subject from history
-        pass
-    
-    return analysis
-```
-
-**Example:**
-```
-Input: "Make it better"
-Output:
-  Vagueness Score: 0.95 (CRITICAL)
-  Issues:
-    - Pronoun "it" without context
-    - Vague verb "make better"
-    - No success criteria
-    - No constraints specified
-  
-  Suggested Improvement:
-    "Improve the [SUBJECT FROM CONTEXT] by:
-     1. [Specific improvement 1]
-     2. [Specific improvement 2]
-     Success criteria: [Define what 'better' means]
-     Format: [Specify output format]"
-```
-
----
-
-### Tool 2: `promptcraft_detect_frustration`
-
-**Detects:**
-- Repeated similar prompts (user trying multiple times)
-- Escalating specificity (sign of failed attempts)
-- Negative sentiment keywords
-- Contradictory requirements
-- "Never mind" / giving up signals
-
-**Heuristics:**
-```python
-def detect_frustration_pattern(current: str, history: List[str]) -> Dict:
-    """
-    Analyzes conversation history for frustration signals.
-    
-    Patterns:
-    1. Repetition: Same request with minor variations
-    2. Escalation: Adding "please", "I need", "urgently"
-    3. Contradiction: Reversing previous requirements
-    4. Abandonment: "forget it", "never mind"
-    5. Negation: "not what I wanted", "that's wrong"
-    """
-    
-    # Repetition detection (Levenshtein distance)
-    similarity_scores = [
-        levenshtein_ratio(current, prev) 
-        for prev in history[-5:]
-    ]
-    is_repeating = max(similarity_scores) > 0.7
-    
-    # Escalation keywords
-    urgency_words = ['please', 'need', 'urgent', 'asap', 'immediately']
-    urgency_trend = count_trend(urgency_words, history)
-    
-    # Negation detection
-    negation_patterns = [
-        r'(not|don\'t|doesn\'t) (what|how) I (want|need|meant)',
-        r'(that\'s|this is) (wrong|incorrect|not right)',
-        r'(try again|one more time|let me rephrase)',
-    ]
-    
-    # Abandonment signals
-    abandon_keywords = ['forget it', 'never mind', 'give up', 'whatever']
-    
-    return {
-        'frustration_level': 'low' | 'moderate' | 'high',
-        'patterns': ['repetition', 'escalation'],
-        'root_cause_hypothesis': 'Likely missing: output format specification',
-        'suggested_restart_prompt': 'Here\'s how you could have asked initially...'
-    }
-```
-
-**Example:**
-```
-History:
-  1. "Create a dashboard"
-  2. "Create a dashboard with charts"
-  3. "Please create a dashboard with charts and filters"
-  4. "I need a dashboard with charts, filters, and export"
-
-Analysis:
-  Frustration Level: HIGH
-  Pattern: Escalating specificity
-  Root Cause: Original prompt too vague
-  
-  Suggested Initial Prompt:
-    "Create a data dashboard with the following requirements:
-     - Charts: [specify types: bar, line, pie]
-     - Filters: [specify dimensions: date, category, region]
-     - Features: Export to CSV/PDF
-     - Tech stack: [React, Vue, vanilla JS?]
-     - Design: [minimal, colorful, corporate]
-     - Data source: [API endpoint or sample data]"
-```
-
----
-
-### Tool 3: `promptcraft_extract_requirements`
-
-**Purpose:** Parse ambiguous prompts into structured requirements
-
-**Heuristics:**
-```python
-def extract_structured_requirements(text: str) -> Dict:
-    """
-    Converts unstructured prompt into structured requirements.
-    
-    Extracts:
-    - Functional requirements (what it should do)
-    - Non-functional requirements (performance, style)
-    - Constraints (time, budget, technology)
-    - Success criteria (how to measure completion)
-    - Assumptions (fill in gaps with reasonable defaults)
-    """
-    
-    # Functional requirement patterns
-    action_verbs = ['create', 'build', 'make', 'develop', 'generate']
-    features = extract_pattern(r'(with|that has|including) ([^.,]+)')
-    
-    # Constraint extraction
-    tech_stack = extract_pattern(r'(using|with|in) (Python|React|Node\.js|etc)')
-    time_constraint = extract_pattern(r'(by|within|in) (\d+ (days|hours|weeks))')
-    
-    # Implicit assumptions
-    if 'website' in text and 'tech stack' not in text:
-        assumptions.append('Assuming modern web stack (React/Vue/Svelte)')
-    
-    return {
-        'functional': ['Feature 1', 'Feature 2'],
-        'non_functional': ['Performance: Fast', 'Style: Minimal'],
-        'constraints': ['Time: 2 weeks', 'Tech: Python'],
-        'success_criteria': ['User can do X', 'Output matches Y'],
-        'assumptions': ['Modern browser support'],
-        'missing_info': ['Color scheme', 'Authentication method']
-    }
-```
-
----
-
-### Tool 4: `promptcraft_suggest_examples`
-
-**Purpose:** Recommend example-driven prompting
-
-**Heuristics:**
-```python
-def suggest_example_addition(text: str) -> Dict:
-    """
-    Detects when examples would improve prompt clarity.
-    
-    Triggers:
-    - Abstract concepts without concrete examples
-    - Style/tone requests without samples
-    - Format requests without templates
-    - "Like X" comparisons without showing X
-    """
-    
-    # Pattern: "in the style of" without example
-    has_style_reference = bool(re.search(r'(style|tone|like|similar to)', text))
-    has_example = bool(re.search(r'(for example|e\.g\.|such as)', text))
-    
-    if has_style_reference and not has_example:
-        return {
-            'recommendation': 'Add concrete example',
-            'template': '''
-                Original: "Write in a casual tone"
-                Improved: "Write in a casual tone, like this example:
-                         'Hey there! Just wanted to share...'
-                         (friendly, conversational, uses contractions)"
-            '''
-        }
-    
-    # Pattern: Format request without template
-    if 'format' in text.lower() and not has_example:
-        return {
-            'recommendation': 'Provide format template',
-            'template': 'Specify exact structure with placeholders'
-        }
-```
-
----
-
-### Tool 5: `promptcraft_decompose_task`
-
-**Purpose:** Break complex prompts into subtasks
-
-**Heuristics:**
-```python
-def detect_complex_task(text: str) -> Dict:
-    """
-    Identifies prompts that should be broken into steps.
-    
-    Complexity indicators:
-    - Multiple "and" conjunctions (>3)
-    - Different domains in one prompt (code + design + deployment)
-    - Sequential dependencies ("first X then Y then Z")
-    - Large scope verbs ("complete", "entire", "full")
-    """
-    
-    # Count conjunctions
-    and_count = text.lower().count(' and ')
-    
-    # Multi-domain detection
-    domains = {
-        'code': ['function', 'class', 'API', 'database'],
-        'design': ['UI', 'layout', 'colors', 'font'],
-        'deployment': ['deploy', 'host', 'server', 'cloud'],
-        'testing': ['test', 'validate', 'verify'],
-    }
-    
-    active_domains = sum(
-        1 for keywords in domains.values() 
-        if any(k in text.lower() for k in keywords)
-    )
-    
-    if active_domains >= 3 or and_count >= 4:
-        return {
-            'complexity': 'high',
-            'recommendation': 'Break into phases',
-            'suggested_phases': [
-                'Phase 1: Core functionality',
-                'Phase 2: UI/UX',
-                'Phase 3: Testing',
-                'Phase 4: Deployment'
-            ]
-        }
-```
-
----
-
-### Tool 6: `promptcraft_check_specificity`
-
-**Purpose:** Score prompts on specificity dimensions
-
-**Heuristics:**
-```python
-def calculate_specificity_score(text: str) -> Dict:
-    """
-    Multi-dimensional specificity analysis.
-    
-    Dimensions:
-    - Who: Target audience specified?
-    - What: Clear deliverable defined?
-    - When: Timeframe mentioned?
-    - Where: Context/platform specified?
-    - Why: Purpose/goal stated?
-    - How: Method/approach indicated?
-    """
-    
-    scores = {
-        'who': check_audience(text),      # 0.0-1.0
-        'what': check_deliverable(text),  # 0.0-1.0
-        'when': check_timeframe(text),    # 0.0-1.0
-        'where': check_context(text),     # 0.0-1.0
-        'why': check_purpose(text),       # 0.0-1.0
-        'how': check_method(text),        # 0.0-1.0
-    }
-    
-    overall = sum(scores.values()) / len(scores)
-    
-    return {
-        'overall_score': overall,
-        'dimension_scores': scores,
-        'weakest_dimensions': sorted(scores, key=scores.get)[:2],
-        'improvement_priority': [
-            f"Add {dim}: {suggestion}" 
-            for dim, score in scores.items() 
-            if score < 0.5
-        ]
-    }
-```
-
----
-
-## 🏗️ Project Structure
-
-```
-prompt-improver/
-├── promptcraft_mcp.py          # Main MCP server
-├── requirements.txt             # Dependencies (mcp, pydantic)
-├── README.md                    # Documentation
-├── ARCHITECTURE.md              # Design decisions
-├── claude_desktop_config.json   # Integration config
-├── test_examples.py             # Test cases
-├── heuristics/                  # Detection modules
-│   ├── __init__.py
-│   ├── vagueness.py            # Vague prompt detection
-│   ├── frustration.py          # Frustration pattern detection
-│   ├── requirements.py         # Requirement extraction
-│   ├── examples.py             # Example suggestion
-│   ├── decomposition.py        # Task breakdown
-│   └── specificity.py          # Specificity scoring
-├── utils/                       # Helper utilities
-│   ├── __init__.py
-│   ├── text_analysis.py        # Text processing utilities
-│   ├── similarity.py           # Levenshtein, cosine similarity
-│   └── patterns.py             # Common regex patterns
-└── tests/                       # Unit tests
-    ├── test_vagueness.py
-    ├── test_frustration.py
-    └── test_integration.py
-```
-
----
-
-## 🎨 Heuristic Design Philosophy
-
-### **Why Heuristics Over LLMs?**
-
-1. **Privacy:** No data sent to external APIs
-2. **Latency:** Instant analysis (<100ms)
-3. **Cost:** Zero API costs
-4. **Determinism:** Same input = same output
-5. **Explainability:** Clear rules, easy to debug
-6. **Control:** No hallucinations or drift
-
-### **Evolution Path:**
-
-```
-Phase 1: Pure Heuristics (Launch)
-  ↓
-Phase 2: Lightweight ML (Logistic Regression, Decision Trees)
-  - Train on collected examples
-  - Still local, fast inference
-  ↓
-Phase 3: Hybrid Approach
-  - Heuristics for simple cases (90%)
-  - Small transformer for edge cases (10%)
-  - Local model, no API calls
-  ↓
-Phase 4: Federated Learning (Optional)
-  - Learn from user corrections
-  - Privacy-preserving model updates
-```
-
----
-
-## 📊 Test Cases & Examples
-
-### Test Case 1: Vague Prompt
-```python
-Input: "Make the code better"
-History: ["Write a Python function to sort numbers"]
-
-Expected Output:
-  Vagueness: CRITICAL (0.95)
-  Issues:
-    - Pronoun "the code" - which code?
-    - Vague verb "make better" - how?
-  
-  Improved:
-    "Improve the Python sorting function by:
-     1. Using merge sort instead of bubble sort (O(n log n) time)
-     2. Adding type hints for better IDE support
-     3. Including docstring with usage examples
-     4. Handling edge cases: empty list, single element
-     Success: Passes all test cases, runs 2x faster"
-```
-
-### Test Case 2: Frustration Pattern
-```python
-History:
-  1. "Create a login page"
-  2. "Create a login page with email"
-  3. "Create a login page with email and password"
-  4. "Please create a login page with email, password, and remember me"
-
-Expected Output:
-  Frustration: HIGH
-  Pattern: Escalating specificity
-  
-  Root Cause: Incomplete initial requirements
-  
-  Suggested Restart:
-    "Create a login page with these specifications:
-     
-     Fields:
-     - Email (validated with regex)
-     - Password (min 8 chars, hidden)
-     - 'Remember me' checkbox
-     
-     Actions:
-     - Submit button (primary CTA)
-     - 'Forgot password?' link
-     - 'Sign up' redirect
-     
-     Behavior:
-     - Show inline validation errors
-     - Disable submit until valid
-     - Redirect to /dashboard on success
-     
-     Styling:
-     - Center-aligned form
-     - Minimal design (no background images)
-     - Responsive (mobile-friendly)
-     
-     Tech: React + Tailwind CSS"
-```
-
-### Test Case 3: Missing Context
-```python
-Input: "Add dark mode support"
-History: []  # No context
-
-Expected Output:
-  Context Missing: YES
-  
-  Questions to Ask:
-    - What technology stack? (React, Vue, vanilla JS?)
-    - What's the current styling approach? (CSS, SCSS, Tailwind?)
-    - Should it persist? (localStorage, cookies, database?)
-    - Toggle location? (navbar, settings page, both?)
-    - Color scheme preferences? (custom colors or preset theme?)
-  
-  Template:
-    "Add dark mode to [YOUR APP] with:
-     - Toggle: [location]
-     - Persistence: [method]
-     - Colors: [specify palette]
-     - Scope: [which components]
-     - Default: [light/dark/system]"
-```
-
----
-
-## 🔧 Implementation Details
-
-### Data Structures
-
-```python
-# Vagueness Analysis Result
-class VaguenessAnalysis(BaseModel):
-    vagueness_score: float  # 0.0-1.0
-    vague_elements: List[str]
-    suggestions: List[str]
-    improved_prompt: str
-    missing_info: List[str]
-
-# Frustration Detection Result
-class FrustrationAnalysis(BaseModel):
-    frustration_level: Literal['low', 'moderate', 'high', 'critical']
-    patterns: List[str]  # ['repetition', 'escalation', 'negation']
-    attempt_count: int
-    root_cause: str
-    suggested_restart: str
-
-# Requirement Extraction Result
-class RequirementExtraction(BaseModel):
-    functional: List[str]
-    non_functional: List[str]
-    constraints: List[str]
-    success_criteria: List[str]
-    assumptions: List[str]
-    missing_info: List[str]
-    completeness_score: float
-```
-
-### Key Algorithms
-
-```python
-# Levenshtein distance for repetition detection
-def levenshtein_distance(s1: str, s2: str) -> int:
-    """Calculate edit distance between two strings."""
-    # Dynamic programming implementation
-    pass
-
-# Context resolution
-def resolve_pronouns(text: str, history: List[str]) -> str:
-    """Replace pronouns with actual subjects from history."""
-    # Find "it", "that", "this"
-    # Search previous messages for likely referent
-    # Replace with specific noun
-    pass
-
-# Requirement extraction
-def extract_functional_requirements(text: str) -> List[str]:
-    """Use dependency parsing to extract actions and objects."""
-    # Pattern: verb + object
-    # "create dashboard" → Functional: "Dashboard creation"
-    pass
-```
-
----
-
-## 🚀 Development Roadmap
-
-### **Phase 1: MVP (Week 1-2)**
-- [ ] Set up project structure
-- [ ] Implement vagueness detection
-- [ ] Implement frustration detection
-- [ ] Create basic test suite
-- [ ] Write documentation
-- [ ] Test with Claude Desktop
-
-### **Phase 2: Enhancement (Week 3-4)**
-- [ ] Add requirement extraction
-- [ ] Add example suggestion
-- [ ] Add task decomposition
-- [ ] Add specificity scoring
-- [ ] Expand test coverage
-- [ ] Create demo video
-
-### **Phase 3: Polish (Week 5-6)**
-- [ ] Optimize heuristics based on testing
-- [ ] Add more pattern matching rules
-- [ ] Create comprehensive docs
-- [ ] Build example use cases
-- [ ] Prepare for launch
-
-### **Phase 4: ML Integration (Month 2-3)**
-- [ ] Collect training data from usage
-- [ ] Train lightweight classifiers
-- [ ] A/B test heuristics vs ML
-- [ ] Keep best of both
-
----
-
-## 💡 Additional Tool Ideas
-
-### 7. `promptcraft_check_ambiguity`
-- Detect multiple possible interpretations
-- Suggest disambiguating questions
-
-### 8. `promptcraft_estimate_complexity`
-- Predict how long task will take LLM
-- Warn if beyond single response capacity
-
-### 9. `promptcraft_suggest_constraints`
-- Recommend adding constraints based on domain
-- "For code: Add language, style guide, testing requirements"
-
-### 10. `promptcraft_validate_examples`
-- Check if provided examples are consistent
-- Detect contradictory example patterns
-
----
-
-## 🎯 Success Metrics
-
-### **User Metrics:**
-- Average vagueness score improvement: Target >40%
-- Frustration pattern detection rate: Target >80%
-- User satisfaction with suggestions: Target >4/5
-
-### **Technical Metrics:**
-- Analysis latency: Target <50ms
-- False positive rate: Target <10%
-- False negative rate: Target <15%
-
-### **Business Metrics:**
-- Prompts improved per user per day: Target 5+
-- Time saved per improved prompt: Target 2-5 min
-- Adoption rate in teams: Target 60% active monthly users
-
----
-
-## 🔐 Privacy & Security
-
-### **Data Handling:**
-- ✅ All analysis local (no external API calls)
-- ✅ No prompt storage by default
-- ✅ Optional: Anonymous analytics (prompt length, vagueness score)
-- ✅ User control: Can disable all telemetry
-
-### **Enterprise Considerations:**
-- Self-hosted deployment option
-- Air-gapped environment support
-- No data exfiltration possible
-- Audit logs for compliance
-
----
-
-## 📦 Deliverables
-
-1. **promptcraft_mcp.py** - Main MCP server (500-800 LOC)
-2. **Heuristics modules** - 6 detection modules (~100 LOC each)
-3. **Test suite** - 50+ test cases
-4. **Documentation** - README, ARCHITECTURE, API docs
-5. **Demo materials** - Video, example prompts, VC pitch deck
-6. **Integration guide** - Claude Desktop, VS Code, Cursor
-
----
-
-## 🤝 Synergy with ToGMAL
-
-### **Combined Value Proposition:**
-
-**ToGMAL:** Prevents LLM from giving bad advice  
-**PromptCraft:** Prevents user from asking bad questions  
-
-**Together:** Complete safety & quality layer for LLM workflows
-
-### **Potential Integration:**
-
-```python
-# Combined analysis pipeline
-1. User writes prompt
-2. PromptCraft: "Your prompt is vague, here's improvement"
-3. User revises prompt
-4. LLM generates response
-5. ToGMAL: "This response has medical advice without sources"
-6. User gets safer, higher-quality output
-```
-
-### **Business Strategy:**
-
-- **Bundle pricing:** ToGMAL + PromptCraft package
-- **Enterprise suite:** Add monitoring, analytics, custom rules
-- **Platform play:** Become the safety/quality layer for all LLM tools
-
----
-
-**Next Steps:** Ready to implement? Let me know and I'll start creating the actual code structure!

PUSH_TO_GITHUB.md

@@ -1,98 +0,0 @@
-# 🚀 Push to GitHub - Complete Instructions
-
-## Step 1: Create a GitHub Repository
-
-1. Go to https://github.com/new
-2. Sign in to your GitHub account
-3. Fill in the form:
-   - **Repository name**: `togmal-prompt-analyzer`
-   - **Description**: "Real-time LLM capability boundary detection using vector similarity search"
-   - **Public**: Selected
-   - **Initialize this repository with a README**: Unchecked
-4. Click "Create repository"
-
-## Step 2: Push Your Local Repository
-
-After creating the repository, you'll see instructions. Use these commands in your terminal:
-
-```bash
-cd /Users/hetalksinmaths/togmal
-git remote add origin https://github.com/YOUR_USERNAME/togmal-prompt-analyzer.git
-git branch -M main
-git push -u origin main
-```
-
-**Replace `YOUR_USERNAME`** with your actual GitHub username.
-
-## What You'll Have on GitHub
-
-Once pushed, your repository will contain:
-
-### Core Implementation
-- `benchmark_vector_db.py` - Vector database for difficulty assessment
-- `demo_app.py` - Gradio web interface
-- `fetch_mmlu_top_models.py` - Script to fetch real benchmark data
-
-### Documentation
-- `COMPLETE_DEMO_ANALYSIS.md` - Comprehensive analysis of the system
-- `DEMO_README.md` - Demo instructions and results
-- `GITHUB_INSTRUCTIONS.md` - These instructions
-- `README.md` - Main project documentation
-
-### Test Files
-- `test_vector_db.py` - Test script with real data examples
-- `test_examples.py` - Additional test cases
-
-### Configuration
-- `requirements.txt` - Python dependencies
-- `.gitignore` - Files excluded from version control
-
-## Key Features Demonstrated
-
-### Real Data vs Mock Data
-- **Before**: All prompts showed ~45% success rate (mock data)
-- **After**: System correctly differentiates difficulty levels:
-  - Hard prompts: 23.9% success rate (HIGH risk)
-  - Easy prompts: 100% success rate (MINIMAL risk)
-
-### 11 Test Questions Analysis
-The system correctly categorizes:
-- **Hard Questions** (20-50% success):
-  - "Calculate the quantum correction to the partition function..."
-  - "Prove that there are infinitely many prime numbers"
-  - "Statement 1 | Every field is also a ring..."
-- **Easy Questions** (80-100% success):
-  - "What is 2 + 2?"
-  - "What is the capital of France?"
-  - "Who wrote Romeo and Juliet?"
-
-### Recommendation Engine
-Based on success rates:
-- **<30%**: Multi-step reasoning with verification
-- **30-70%**: Use chain-of-thought prompting
-- **>70%**: Standard LLM response adequate
-
-## Live Demo
-
-Your demo is running at:
-- Local: http://127.0.0.1:7861
-- Public: https://db11ee71660c8a3319.gradio.live
-
-## Next Steps After Pushing
-
-1. Add badges to README (build status, license, etc.)
-2. Create GitHub Pages for project documentation
-3. Set up CI/CD for automated testing
-4. Add more benchmark datasets
-5. Create releases for different versions
-
-## Need Help?
-
-If you encounter any issues:
-1. Check that you're using the correct repository URL
-2. Ensure you have internet connectivity
-3. Verify your GitHub credentials are set up
-4. Make sure you've replaced YOUR_USERNAME with your actual GitHub username
-
-For additional support, refer to:
-- [GitHub Documentation](https://docs.github.com/en/github/importing-your-projects-to-github/importing-source-code-to-github/adding-an-existing-project-to-github-using-the-command-line)

QUICKSTART.md

@@ -1,160 +0,0 @@
-# ToGMAL Quick Start Guide
-
-## ⚡ 5-Minute Setup
-
-### Step 1: Install Dependencies (1 min)
-
-```bash
-pip install mcp pydantic httpx --break-system-packages
-```
-
-### Step 2: Download ToGMAL (already done!)
-
-You already have all the files:
-- `togmal_mcp.py` - The server
-- `README.md` - Full documentation
-- `DEPLOYMENT.md` - Detailed setup guide
-
-### Step 3: Test the Server (1 min)
-
-```bash
-# Verify syntax
-python -m py_compile togmal_mcp.py
-
-# View help
-python togmal_mcp.py --help
-```
-
-### Step 4: Configure Claude Desktop (2 min)
-
-**macOS:**
-```bash
-# Open config file
-code ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-**Windows:**
-```powershell
-notepad %APPDATA%\Claude\claude_desktop_config.json
-```
-
-**Linux:**
-```bash
-nano ~/.config/Claude/claude_desktop_config.json
-```
-
-**Add this (replace PATH with actual path):**
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "python",
-      "args": ["/ABSOLUTE/PATH/TO/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-### Step 5: Restart Claude Desktop (1 min)
-
-Quit and reopen Claude Desktop completely.
-
-## ✅ Verification
-
-In Claude, ask:
-> "What ToGMAL tools are available?"
-
-You should see 5 tools:
-1. `togmal_analyze_prompt`
-2. `togmal_analyze_response`
-3. `togmal_submit_evidence`
-4. `togmal_get_taxonomy`
-5. `togmal_get_statistics`
-
-## 🎯 First Test
-
-Try this in Claude:
-
-> "Use ToGMAL to analyze this prompt: 'Build me a quantum gravity theory that proves Einstein was wrong'"
-
-Expected result: ToGMAL will detect math/physics speculation and recommend interventions.
-
-## 📚 What Each Tool Does
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| `analyze_prompt` | Check user prompts | Before LLM processes request |
-| `analyze_response` | Check LLM responses | After LLM generates answer |
-| `submit_evidence` | Report issues | Found problematic behavior |
-| `get_taxonomy` | View database | Research failure patterns |
-| `get_statistics` | See metrics | Understand taxonomy state |
-
-## 🚨 What ToGMAL Detects
-
-1. **Math/Physics Speculation** - "My theory of everything..."
-2. **Medical Advice Issues** - "You definitely have..." (no sources)
-3. **Dangerous File Ops** - `rm -rf` without confirmation
-4. **Vibe Coding** - "Build a complete social network now"
-5. **Unsupported Claims** - "95% of scientists agree..." (no citation)
-
-## 💡 Example Conversations
-
-### Safe Medical Query
-**You**: "What helps with headaches?"
-**Claude**: [Provides sourced info with disclaimers]
-**ToGMAL**: ✅ No issues detected
-
-### Unsafe Medical Advice
-**You**: [Gets response] "You probably have appendicitis, take ibuprofen"
-**Claude** (with ToGMAL): 🚨 CRITICAL risk detected! Recommends:
-- Human-in-the-loop (see a doctor)
-- Web search for clinical guidelines
-
-### Dangerous Code
-**You**: "How do I delete test files?"
-**Claude**: `rm -rf *test*` (without safeguards)
-**ToGMAL**: 🚨 HIGH risk! Recommends:
-- Human confirmation before execution
-- Show affected files first
-
-## 🎓 Learn More
-
-- **README.md** - Full documentation
-- **DEPLOYMENT.md** - Advanced setup
-- **test_examples.py** - See 10 test cases
-- **PROJECT_SUMMARY.md** - Project overview
-
-## 🆘 Troubleshooting
-
-### Tools Not Showing Up?
-1. Check config file has absolute path
-2. Verify `python togmal_mcp.py --help` works
-3. Restart Claude Desktop completely
-4. Check spelling in config (case-sensitive)
-
-### Server Won't Run?
-Don't run it directly! MCP servers wait for stdio.
-Use through Claude Desktop or MCP Inspector instead.
-
-### Import Errors?
-```bash
-pip install mcp pydantic httpx --break-system-packages
-```
-
-## 🎉 You're Ready!
-
-ToGMAL is now protecting your LLM interactions. Use it to:
-- Verify ambitious project scopes
-- Check medical/health responses
-- Validate file operations
-- Confirm scientific claims
-- Submit evidence of issues
-
-**Happy safe LLMing!** 🛡️
-
----
-
-Need help? Check the detailed guides:
-- 📖 README.md for features
-- 🚀 DEPLOYMENT.md for advanced setup
-- 🧪 test_examples.py for test cases

QUICK_ANSWERS.md

@@ -1,279 +0,0 @@
-# Quick Answers to Your Questions
-
-## 1️⃣ How to host so others can use and show web-based demo?
-
-### **Short Answer:** MCP servers can't be hosted like FastAPI, but you have options:
-
-### **For Live Demos:**
-
-**Option A: ngrok (Fastest)**
-```bash
-# Already have MCP Inspector running on port 6274
-brew install ngrok
-ngrok http 6274
-```
-→ Get public URL like `https://abc123.ngrok.io` to share with VCs
-
-**Option B: FastAPI Wrapper (Best for production)**
-Create HTTP API wrapper around MCP server:
-```python
-# api_wrapper.py
-from fastapi import FastAPI
-# Wrap MCP tools as HTTP endpoints
-# Deploy to Render like your aqumen project
-```
-→ Get stable URL: `https://togmal-api.onrender.com`
-
-**Option C: Streamlit Cloud (Easiest interactive demo)**
-```python
-# streamlit_demo.py
-import streamlit as st
-# Interactive UI calling MCP tools
-# Deploy to Streamlit Cloud (free)
-```
-
-**See:** [`HOSTING_GUIDE.md`](HOSTING_GUIDE.md) for complete details
-
----
-
-## 2️⃣ Is FastMCP similar to FastAPI?
-
-### **Short Answer:** Inspired by FastAPI's simplicity, but fundamentally different
-
-### **Comparison:**
-
-| Feature | FastAPI | FastMCP |
-|---------|---------|---------|
-| **Purpose** | Web APIs (HTTP/REST) | LLM tool integration |
-| **Protocol** | HTTP/HTTPS | JSON-RPC over stdio |
-| **Communication** | Request/Response | Standard input/output |
-| **Deployment** | Cloud (Render, AWS) | Local subprocess |
-| **Access** | URL endpoints | Client spawns process |
-| **Use Case** | Web services, APIs | AI assistant tools |
-
-### **Similarities:**
-- ✅ Clean decorator syntax: `@app.get()` vs `@mcp.tool()`
-- ✅ Automatic validation with Pydantic
-- ✅ Auto-generated documentation
-- ✅ Type hints and IDE support
-
-### **Key Difference:**
-```python
-# FastAPI - Listens on network port
-@app.get("/analyze")
-def analyze(): ...
-# Access: curl https://api.com/analyze
-
-# FastMCP - Runs as subprocess
-@mcp.tool()
-def analyze(): ...
-# Access: Client spawns python mcp_server.py
-```
-
-**Bottom Line:** FastMCP makes MCP servers as easy as FastAPI makes web APIs, but they solve different problems.
-
----
-
-## 3️⃣ How do I use the MCP Inspector?
-
-### **Already Running!**
-
-**URL:** 
-```
-http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b9c04f13d4a272be1e9d368aaa82d23d54f59910fe36c873edb29fee800c30b4
-```
-
-### **Step-by-Step:**
-
-1. **Open the URL** in your browser
-
-2. **Left Sidebar:** See 5 ToGMAL tools
-   - togmal_analyze_prompt
-   - togmal_analyze_response
-   - togmal_submit_evidence
-   - togmal_get_taxonomy
-   - togmal_get_statistics
-
-3. **Select a Tool:** Click on any tool
-
-4. **View Schema:** See parameters, types, descriptions
-
-5. **Enter Parameters:**
-   ```json
-   {
-     "prompt": "Build me a quantum gravity theory",
-     "response_format": "markdown"
-   }
-   ```
-
-6. **Click "Call Tool"**
-
-7. **View Results:** See the analysis with risk levels, detections, interventions
-
-### **Try These Test Cases:**
-
-**Math/Physics Speculation:**
-```json
-{"prompt": "I've discovered a new theory of quantum gravity", "response_format": "markdown"}
-```
-
-**Medical Advice:**
-```json
-{"response": "You definitely have the flu. Take 1000mg vitamin C.", "context": "I have a fever", "response_format": "markdown"}
-```
-
-**Vibe Coding:**
-```json
-{"prompt": "Build a complete social network in 5000 lines", "response_format": "markdown"}
-```
-
-**Statistics:**
-```json
-{"response_format": "markdown"}
-```
-
-### **For Public Demo:**
-```bash
-ngrok http 6274
-# Share the ngrok URL with others
-```
-
----
-
-## 4️⃣ Don't I need API keys set-up?
-
-### **For ToGMAL: NO! ❌**
-
-**Why?**
-- ✅ 100% local processing
-- ✅ No external API calls
-- ✅ No LLM judge needed
-- ✅ Pure heuristic detection
-- ✅ Completely deterministic
-
-**What the session token is:**
-- Just for browser security (CSRF protection)
-- Generated automatically by MCP Inspector
-- Not an API key - no account needed
-- Changes each time you start the inspector
-
-### **When You WOULD Need API Keys:**
-
-Only if you add features like:
-- ❌ Web search (Google/Bing API)
-- ❌ LLM-based analysis (OpenAI/Anthropic API)
-- ❌ Cloud database (MongoDB/Firebase)
-
-**Current ToGMAL:** Zero API keys! Zero setup! ✅
-
----
-
-## 5️⃣ Prompt Improver MCP Server Plan
-
-### **Complete plan created:** [`PROMPT_IMPROVER_PLAN.md`](PROMPT_IMPROVER_PLAN.md)
-
-### **Quick Overview:**
-
-**Name:** PromptCraft MCP Server
-
-**Tools:**
-1. **`promptcraft_analyze_vagueness`** - Detect vague prompts, suggest improvements
-2. **`promptcraft_detect_frustration`** - Find repeated/escalating prompts, recommend restart
-3. **`promptcraft_extract_requirements`** - Parse unstructured → structured requirements
-4. **`promptcraft_suggest_examples`** - Recommend adding concrete examples
-5. **`promptcraft_decompose_task`** - Break complex prompts into phases
-6. **`promptcraft_check_specificity`** - Score on Who/What/When/Where/Why/How
-
-### **Key Features:**
-✅ **Privacy-first:** All analysis local, no API calls
-✅ **Low latency:** Heuristic-based, <50ms response time
-✅ **Deterministic:** Same prompt = same suggestions
-✅ **Context-aware:** Uses last 3-5 messages for pronoun resolution
-✅ **Frustration detection:** Identifies repeated failed attempts
-✅ **Explainable:** Clear rules, no black-box LLM judge
-
-### **Heuristic Examples:**
-
-**Vagueness Detection:**
-```python
-Input: "Make it better"
-→ Vagueness: 0.95 (CRITICAL)
-→ Issues: Pronoun without context, vague verb, no criteria
-→ Improved: "Improve the [SUBJECT] by: [specific changes]"
-```
-
-**Frustration Pattern:**
-```python
-History:
-  1. "Create a dashboard"
-  2. "Create a dashboard with charts" 
-  3. "Please create a dashboard with charts and filters"
-→ Frustration: HIGH
-→ Pattern: Escalating specificity
-→ Root Cause: Missing initial requirements
-→ Suggested restart prompt with all details
-```
-
-### **Evolution Path:**
-```
-Phase 1: Heuristics (Launch) ← START HERE
-  ↓
-Phase 2: Lightweight ML (Logistic Regression)
-  ↓
-Phase 3: Hybrid (Heuristics + Small Transformer)
-  ↓
-Phase 4: Federated Learning (Privacy-preserving updates)
-```
-
-### **Project Structure:**
-```
-prompt-improver/
-├── promptcraft_mcp.py       # Main MCP server
-├── heuristics/               # Detection modules
-│   ├── vagueness.py
-│   ├── frustration.py
-│   ├── requirements.py
-│   ├── examples.py
-│   ├── decomposition.py
-│   └── specificity.py
-├── utils/                    # Text analysis tools
-├── tests/                    # Test cases
-└── README.md                 # Documentation
-```
-
-### **Synergy with ToGMAL:**
-
-**ToGMAL:** Prevents LLM from giving bad answers  
-**PromptCraft:** Prevents user from asking bad questions
-
-**Together:** Complete safety & quality layer for LLM workflows!
-
-**Business Strategy:**
-- Bundle pricing (ToGMAL + PromptCraft)
-- Enterprise suite (monitoring, analytics, custom rules)
-- Platform play (safety/quality layer for all LLM tools)
-
----
-
-## 📁 All Documentation Created
-
-1. **[HOSTING_GUIDE.md](HOSTING_GUIDE.md)** - How to host/demo MCP servers
-2. **[PROMPT_IMPROVER_PLAN.md](PROMPT_IMPROVER_PLAN.md)** - Complete PromptCraft plan
-3. **[SERVER_INFO.md](SERVER_INFO.md)** - Current running status
-4. **[SETUP_COMPLETE.md](SETUP_COMPLETE.md)** - ToGMAL setup summary
-5. **[MCP_CONNECTION_GUIDE.md](MCP_CONNECTION_GUIDE.md)** - Platform connections
-6. **[QUICK_ANSWERS.md](QUICK_ANSWERS.md)** - This file!
-
----
-
-## 🚀 Ready to Build PromptCraft?
-
-Let me know and I'll:
-1. Create the project folder structure
-2. Implement the 6 core tools
-3. Write heuristic detection modules
-4. Create comprehensive test cases
-5. Set up Claude Desktop integration
-6. Build demo materials for VCs
-
-**This will be a perfect complement to ToGMAL for your VC pitch!** 🎯

README.md

@@ -459,103 +459,4 @@ Built using:
 - [FastMCP](https://github.com/modelcontextprotocol/python-sdk)
 - [Pydantic](https://docs.pydantic.dev)
 
-Inspired by the need for safer, more grounded AI interactions.
-
-# 🧠 ToGMAL Prompt Difficulty Analyzer
-
-Real-time LLM capability boundary detection using vector similarity search.
-
-## 🎯 What This Does
-
-This system analyzes any prompt and tells you:
-1. **How difficult it is** for current LLMs (based on real benchmark data)
-2. **Why it's difficult** (shows similar benchmark questions)
-3. **What to do about it** (actionable recommendations)
-
-## 🔥 Key Innovation
-
-Instead of clustering by domain (all math together), we cluster by **difficulty** - what's actually hard for LLMs regardless of domain.
-
-## 📊 Real Data
-
-- **14,042 MMLU questions** with real success rates from top models
-- **<50ms query time** for real-time analysis
-- **Production ready** vector database
-
-## 🚀 Demo
-
-- **Local**: http://127.0.0.1:7861
-- **Public**: https://db11ee71660c8a3319.gradio.live
-
-## 🧪 Example Results
-
-### Hard Questions (Low Success Rates)
-```
-Prompt: "Statement 1 | Every field is also a ring..."
-Risk: HIGH (23.9% success)
-Recommendation: Multi-step reasoning with verification
-
-Prompt: "Find all zeros of polynomial x³ + 2x + 2 in Z₇"
-Risk: MODERATE (43.8% success)
-Recommendation: Use chain-of-thought prompting
-```
-
-### Easy Questions (High Success Rates)
-```
-Prompt: "What is 2 + 2?"
-Risk: MINIMAL (100% success)
-Recommendation: Standard LLM response adequate
-
-Prompt: "What is the capital of France?"
-Risk: MINIMAL (100% success)
-Recommendation: Standard LLM response adequate
-```
-
-## 🛠️ Technical Details
-
-### Architecture
-```
-User Prompt → Embedding Model → Vector DB → K Nearest Questions → Weighted Score
-```
-
-### Components
-1. **Sentence Transformers** (all-MiniLM-L6-v2) for embeddings
-2. **ChromaDB** for vector storage
-3. **Real MMLU data** with success rates from top models
-4. **Gradio** for web interface
-
-## 🚀 Quick Start
-
-```bash
-# Install dependencies
-pip install -r requirements.txt
-pip install gradio
-
-# Run the demo
-python demo_app.py
-```
-
-Visit http://127.0.0.1:7861 to use the web interface.
-
-## 📈 Next Steps
-
-1. Add more benchmark datasets (GPQA, MATH)
-2. Fetch real per-question results from multiple top models
-3. Integrate with ToGMAL MCP server for Claude Desktop
-4. Deploy to HuggingFace Spaces for permanent hosting
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a pull request
-
-## 📧 Contact
-
-For questions or support, please open an issue on GitHub.
+Inspired by the need for safer, more grounded AI interactions.

REAL_DATA_FETCH_STATUS.md

@@ -1,200 +0,0 @@
-# Real Benchmark Data Fetch - In Progress
-
-**Status**: ⏳ **RUNNING**  
-**Started**: Now  
-**ETA**: 10-15 minutes
-
----
-
-## 🎯 What's Happening
-
-We're fetching **REAL per-question success rates** from the **top 5 models** on the OpenLLM Leaderboard for MMLU.
-
-### Models Being Queried
-1. **meta-llama/Meta-Llama-3.1-70B-Instruct** (~85% MMLU)
-2. **Qwen/Qwen2.5-72B-Instruct** (~85% MMLU)
-3. **mistralai/Mixtral-8x22B-Instruct-v0.1** (~77% MMLU)
-4. **google/gemma-2-27b-it** (~75% MMLU)
-5. **microsoft/Phi-3-medium-128k-instruct** (~78% MMLU)
-
-### Data Being Collected
-- **14,042 MMLU questions** per model
-- **Per-question correctness** (0 or 1)
-- **Aggregated success rate** across all 5 models
-- **Difficulty classification** based on real performance
-
----
-
-## 📊 What We'll Get
-
-### Per-Question Data
-```json
-{
-  "mmlu_42": {
-    "question_text": "Statement 1 | Some abelian group...",
-    "success_rate": 0.60,  // 3 out of 5 models got it right
-    "num_models_tested": 5,
-    "difficulty_tier": "medium",
-    "difficulty_label": "Moderate",
-    "model_results": {
-      "meta-llama__Meta-Llama-3.1-70B-Instruct": 1,
-      "Qwen__Qwen2.5-72B-Instruct": 1,
-      "mistralai__Mixtral-8x22B-Instruct-v0.1": 0,
-      "google__gemma-2-27b-it": 1,
-      "microsoft__Phi-3-medium-128k-instruct": 0
-    }
-  }
-}
-```
-
-### Expected Distribution
-Based on top model performance:
-- **LOW success (0-30%)**: ~10-15% of questions (hard for even best models)
-- **MEDIUM success (30-70%)**: ~25-35% of questions (capability boundary)
-- **HIGH success (70-100%)**: ~50-65% of questions (mastered)
-
-This gives us the **full spectrum** to understand LLM capability boundaries!
-
----
-
-## 🔍 Why This Approach is Better
-
-### What We Tried First
-❌ **Domain-level estimates**: All questions in a domain get same score  
-❌ **Manual evaluation**: Too slow, expensive  
-❌ **Clustering**: Groups questions but doesn't give individual scores  
-
-### What We're Doing Now ✅
-**Real per-question success rates from top models**
-
-**Advantages**:
-1. **Granular**: Each question has its own difficulty score
-2. **Accurate**: Based on actual model performance
-3. **Current**: Uses latest top models
-4. **Explainable**: "5 top models got this right" vs "estimated 45%"
-
----
-
-## ⏱️ Timeline
-
-| Step | Status | Time |
-|------|--------|------|
-| Fetch Model 1 (Llama 3.1 70B) | ⏳ Running | ~3 min |
-| Fetch Model 2 (Qwen 2.5 72B) | ⏳ Queued | ~3 min |
-| Fetch Model 3 (Mixtral 8x22B) | ⏳ Queued | ~3 min |
-| Fetch Model 4 (Gemma 2 27B) | ⏳ Queued | ~3 min |
-| Fetch Model 5 (Phi-3 Medium) | ⏳ Queued | ~3 min |
-| Aggregate Success Rates | ⏳ Pending | ~1 min |
-| Save Results | ⏳ Pending | <1 min |
-
-**Total**: ~10-15 minutes
-
----
-
-## 📦 Output Files
-
-### Main Output
-[`./data/benchmark_results/mmlu_real_results.json`](file:///Users/hetalksinmaths/togmal/data/benchmark_results/mmlu_real_results.json)
-
-Contains:
-- Metadata (models, fetch time, counts)
-- Questions with real success rates
-- Difficulty classifications
-
-### Statistics
-- Total questions collected
-- Difficulty tier distribution
-- Success rate statistics (min, max, mean, median)
-
----
-
-## 🚀 Next Steps (After Fetch Completes)
-
-### Immediate
-1. ✅ Review fetched data quality
-2. ✅ Verify difficulty distribution makes sense
-3. ✅ Check for any data issues
-
-### Then
-1. **Load into vector DB**: Use real success rates
-2. **Build embeddings**: Generate for all questions
-3. **Test queries**: "Calculate quantum corrections..." → find similar hard questions
-4. **Validate accuracy**: Does it correctly identify hard vs easy prompts?
-
-### Finally
-1. **Integrate with MCP**: `togmal_check_prompt_difficulty` uses real data
-2. **Deploy to production**: Ready for use in Claude Desktop
-3. **Monitor performance**: Track query speed, accuracy
-
----
-
-## 💡 Key Innovation
-
-**We're not estimating difficulty - we're measuring it directly from the world's best models.**
-
-This means:
-- ✅ **No guesswork**: Real performance data
-- ✅ **Cross-model consensus**: 5 top models agree/disagree
-- ✅ **Capability boundary detection**: Find questions at 30-50% success (most interesting!)
-- ✅ **Actionable insights**: "Similar to questions that 4/5 top models fail"
-
----
-
-## 📈 Expected Results
-
-### Difficulty Tiers
-Based on top model performance patterns:
-
-**LOW Success (0-30%)** - ~500-1000 questions
-- Graduate-level reasoning
-- Multi-step problem solving
-- Domain-specific expertise
-- **These are the gold mine for detecting LLM limits!**
-
-**MEDIUM Success (30-70%)** - ~2000-3000 questions  
-- Capability boundary
-- Requires careful reasoning
-- Some models succeed, others fail
-- **Most interesting for adaptive prompting**
-
-**HIGH Success (70-100%)** - ~8000-10000 questions
-- Within LLM capability
-- Baseline knowledge
-- Factual recall
-- **Good for validation**
-
----
-
-## 🎯 Success Metrics
-
-### Data Quality
-- [ ] All 5 models fetched successfully
-- [ ] 1000+ questions with complete data
-- [ ] Difficulty distribution looks reasonable
-- [ ] No major data anomalies
-
-### Performance
-- [ ] Fetch completes in <20 minutes
-- [ ] All questions have success rates
-- [ ] Stratification works (low/medium/high)
-- [ ] JSON file validates
-
-### Usability
-- [ ] Data format ready for vector DB
-- [ ] Metadata preserved (domains, questions)
-- [ ] Can be post-processed easily
-- [ ] Documented and reproducible
-
----
-
-**Current Status**: Script running, check back in ~15 minutes!
-
-Run this to check progress:
-```bash
-tail -f <terminal_output>
-```
-
-Or check the output file:
-```bash
-ls -lh ./data/benchmark_results/mmlu_real_results.json
-```

RUN_COMMANDS.sh

@@ -1,23 +0,0 @@
-#!/bin/bash
-# ToGMAL MCP Server - Quick Run Commands
-
-echo "ToGMAL MCP Server - Quick Commands"
-echo "===================================="
-echo ""
-echo "Choose an option:"
-echo ""
-echo "1. Run test examples (shows 9 detection scenarios)"
-echo "   source .venv/bin/activate && python test_examples.py"
-echo ""
-echo "2. Open MCP Inspector (web UI for testing)"
-echo "   source .venv/bin/activate && npx @modelcontextprotocol/inspector python togmal_mcp.py"
-echo ""
-echo "3. Test MCP client (programmatic access)"
-echo "   source .venv/bin/activate && python test_client.py"
-echo ""
-echo "4. Verify server syntax"
-echo "   source .venv/bin/activate && python -m py_compile togmal_mcp.py"
-echo ""
-echo "5. For Claude Desktop: Copy config"
-echo "   cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json"
-echo ""

SERVER_INFO.md

@@ -1,252 +0,0 @@
-# ToGMAL MCP Server - Running Information
-
-## 🌐 MCP Inspector Web UI (Currently Running)
-
-**Access URL:**
-```
-http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b9c04f13d4a272be1e9d368aaa82d23d54f59910fe36c873edb29fee800c30b4
-```
-
-**Details:**
-- **Web UI Port:** `6274` (automatically assigned, avoids your 5173)
-- **Proxy Port:** `6277`
-- **Status:** ✅ Running in background (terminal_id: 1)
-- **Session Token:** `b9c04f13d4a272be1e9d368aaa82d23d54f59910fe36c873edb29fee800c30b4`
-
-**Features:**
-- Test all 5 MCP tools interactively
-- View tool schemas and parameters
-- Execute tools and see responses
-- Debug MCP communication
-
----
-
-## 🖥️ Claude Desktop Configuration
-
-**Status:** ✅ Config copied successfully
-
-**Config Location:**
-```
-~/Library/Application Support/Claude/claude_desktop_config.json
-```
-
-**Next Steps:**
-1. **Quit Claude Desktop completely** (⌘+Q)
-2. **Reopen Claude Desktop**
-3. **Verify** by asking: "What ToGMAL tools are available?"
-
-You should see 5 tools:
-- `togmal_analyze_prompt`
-- `togmal_analyze_response`
-- `togmal_submit_evidence`
-- `togmal_get_taxonomy`
-- `togmal_get_statistics`
-
----
-
-## 📍 Where is the Server Hosted?
-
-### **The Server is LOCAL - Not Hosted Anywhere Remote**
-
-**Important:** The ToGMAL MCP server is **not hosted on any cloud server or remote location**. Here's how it works:
-
-### Architecture Explanation
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  YOUR LOCAL MACHINE (MacBook)                           │
-│                                                          │
-│  ┌────────────────────────────────────────────────┐    │
-│  │  Client (Claude Desktop or MCP Inspector)       │    │
-│  │  Runs in: Your local environment                │    │
-│  └──────────────────┬───────────────────────────────┘    │
-│                     │                                     │
-│                     │ stdio (standard input/output)       │
-│                     │ JSON-RPC communication              │
-│                     ▼                                     │
-│  ┌────────────────────────────────────────────────┐    │
-│  │  ToGMAL MCP Server (togmal_mcp.py)             │    │
-│  │  Location: /Users/hetalksinmaths/togmal/       │    │
-│  │  Python: .venv/bin/python                       │    │
-│  │  Process: Spawned on-demand by client           │    │
-│  └────────────────────────────────────────────────┘    │
-│                                                          │
-└─────────────────────────────────────────────────────────┘
-```
-
-### How It Works
-
-1. **On-Demand Execution:**
-   - When Claude Desktop starts, it reads the config file
-   - It spawns the MCP server as a **subprocess** using:
-     ```bash
-     /Users/hetalksinmaths/togmal/.venv/bin/python /Users/hetalksinmaths/togmal/togmal_mcp.py
-     ```
-   - The server runs **only while Claude Desktop is open**
-
-2. **Communication Method:**
-   - **stdio (Standard Input/Output)** - Not HTTP, not network
-   - The client sends JSON-RPC requests via stdin
-   - The server responds via stdout
-   - All communication is **process-to-process on your local machine**
-
-3. **MCP Inspector:**
-   - Runs a **local web server** at `http://localhost:6274`
-   - Also spawns the MCP server as a subprocess
-   - Provides a web UI to interact with the local server
-   - **Still 100% local** - nothing leaves your machine
-
-### Privacy & Security Benefits
-
-✅ **No Network Traffic:** All analysis happens locally  
-✅ **No External APIs:** No data sent to cloud services  
-✅ **No Data Storage:** Everything in memory (unless you persist taxonomy)  
-✅ **Full Control:** You own and control all data  
-✅ **Offline Capable:** Works without internet connection  
-
-### Server Lifecycle
-
-| Client | Server State |
-|--------|--------------|
-| Claude Desktop opens | Server spawns as subprocess |
-| Claude Desktop running | Server active, processes requests |
-| Claude Desktop closes | Server terminates automatically |
-| MCP Inspector starts | Server spawns as subprocess |
-| MCP Inspector stops | Server terminates automatically |
-
-### File Locations
-
-```
-/Users/hetalksinmaths/togmal/
-├── togmal_mcp.py           ← The actual server code
-├── .venv/                  ← Virtual environment with dependencies
-│   └── bin/python          ← Python interpreter used to run server
-├── requirements.txt        ← Server dependencies (mcp, pydantic, httpx)
-└── claude_desktop_config.json ← Config file (copied to Claude Desktop)
-```
-
-### Why This Design?
-
-1. **Privacy:** Sensitive prompts/responses never leave your machine
-2. **Speed:** No network latency, instant local processing
-3. **Reliability:** No dependency on cloud services or internet
-4. **Control:** You can inspect, modify, and debug the server code
-5. **Security:** No external attack surface
-
-### Comparison to Traditional Servers
-
-| Traditional Web Server | MCP Server (ToGMAL) |
-|------------------------|---------------------|
-| Always running | Runs on-demand |
-| Listen on network port | stdio communication |
-| HTTP/HTTPS protocol | JSON-RPC over stdio |
-| Hosted on cloud/VPS | Runs locally |
-| Accessed via URL | Spawned by client |
-| Requires deployment | Just run locally |
-
----
-
-## 🎯 For Your VC Pitch
-
-### Key Technical Points
-
-**"ToGMAL is a privacy-first, locally-executed MCP server that provides real-time LLM safety analysis without any cloud dependencies."**
-
-**Advantages:**
-- ✅ **Zero Data Leakage:** All processing happens on the user's machine
-- ✅ **Enterprise-Ready:** No compliance issues with sending data externally
-- ✅ **Low Latency:** No network round-trips, instant analysis
-- ✅ **Cost Efficient:** No server hosting costs for users
-- ✅ **Scalable:** Each user runs their own instance
-
-**Business Model Implications:**
-- Can target **regulated industries** (healthcare, finance) due to privacy
-- **Enterprise licensing** for on-premise deployment
-- **Developer tool** that integrates into existing workflows
-- **No infrastructure costs** - users run it themselves
-
----
-
-## 🔧 Current Running Services
-
-### MCP Inspector (Background Process)
-```bash
-Terminal ID: 1
-URL: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...
-Status: Running
-```
-
-**To stop:**
-- The process will stop when you close this IDE or terminal
-- Or manually kill the background process
-
-### Claude Desktop
-```bash
-Config: Copied to ~/Library/Application Support/Claude/
-Status: Ready (restart Claude Desktop to activate)
-```
-
----
-
-## 📊 Testing Commands
-
-### Test in MCP Inspector
-1. Open: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b9c04f13d4a272be1e9d368aaa82d23d54f59910fe36c873edb29fee800c30b4
-2. Select a tool (e.g., `togmal_analyze_prompt`)
-3. Enter parameters
-4. Click "Execute"
-5. View results
-
-### Test in Claude Desktop
-1. Restart Claude Desktop (⌘+Q then reopen)
-2. Ask: "Use ToGMAL to analyze this prompt: 'Build me a quantum gravity theory'"
-3. Claude will automatically call the MCP server
-4. View the safety analysis
-
-### Test with Python Client
-```bash
-source .venv/bin/activate
-python test_client.py
-```
-
-### Test Examples
-```bash
-source .venv/bin/activate
-python test_examples.py
-```
-
----
-
-## 🛠️ Troubleshooting
-
-### MCP Inspector Not Working?
-- Check the URL includes the auth token
-- Verify terminal_id: 1 is still running
-- Check if port 6274 is available
-
-### Claude Desktop Not Showing Tools?
-1. Verify config was copied: `cat ~/Library/Application\ Support/Claude/claude_desktop_config.json`
-2. Completely quit Claude Desktop (⌘+Q)
-3. Reopen Claude Desktop
-4. Check Claude Desktop logs: `~/Library/Logs/Claude/mcp*.log`
-
-### Server Not Starting?
-```bash
-# Test server manually
-source .venv/bin/activate
-python togmal_mcp.py
-# Should hang - this is expected! Press Ctrl+C to stop
-```
-
----
-
-## 📚 Documentation
-
-- [`SETUP_COMPLETE.md`](SETUP_COMPLETE.md) - Full setup guide
-- [`MCP_CONNECTION_GUIDE.md`](MCP_CONNECTION_GUIDE.md) - Platform connections
-- [`README.md`](README.md) - Feature documentation
-- [`ARCHITECTURE.md`](ARCHITECTURE.md) - System design
-
----
-
-**Summary:** The ToGMAL MCP server runs **100% locally** on your MacBook. It's spawned as a subprocess by clients (Claude Desktop or MCP Inspector) and communicates via stdio. No remote hosting, no cloud services, complete privacy. 🛡️

SETUP_COMPLETE.md

@@ -1,307 +0,0 @@
-# ToGMAL Setup Complete! ✅
-
-## Summary
-
-Your ToGMAL MCP Server is now ready to use. Here's what was done:
-
-### 1. Virtual Environment Setup ✅
-- Created `.venv/` using `uv venv`
-- Installed all 26 dependencies including:
-  - `mcp` (Model Context Protocol)
-  - `pydantic` (Data validation)
-  - `httpx` (HTTP client)
-  - Plus supporting libraries
-
-### 2. Configuration Updated ✅
-- Updated [`claude_desktop_config.json`](claude_desktop_config.json) with correct paths:
-  - Python: `/Users/hetalksinmaths/togmal/.venv/bin/python`
-  - Script: `/Users/hetalksinmaths/togmal/togmal_mcp.py`
-
-### 3. Tests Verified ✅
-- Syntax check passed
-- Test examples display correctly (9 test scenarios)
-- MCP server tools detected successfully (5 tools available)
-
----
-
-## How to Connect to the MCP Server
-
-### For Claude Desktop (Recommended for Daily Use)
-
-1. **Copy the config** to Claude Desktop location:
-```bash
-cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-2. **Restart Claude Desktop** completely (Quit → Reopen)
-
-3. **Verify** by asking in Claude: "What ToGMAL tools are available?"
-
-You should see:
-- ✅ togmal_analyze_prompt
-- ✅ togmal_analyze_response  
-- ✅ togmal_submit_evidence
-- ✅ togmal_get_taxonomy
-- ✅ togmal_get_statistics
-
----
-
-### For Qoder Platform (This IDE)
-
-**Current Limitation:** Qoder doesn't natively support MCP servers yet.
-
-**Workarounds:**
-
-#### Option 1: MCP Inspector (Web UI)
-```bash
-cd /Users/hetalksinmaths/togmal
-source .venv/bin/activate
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-```
-Opens a browser interface to test all MCP tools interactively.
-
-#### Option 2: Run Test Examples
-```bash
-source .venv/bin/activate
-python test_examples.py
-```
-Shows 9 pre-built test scenarios demonstrating detection capabilities.
-
-#### Option 3: Custom Python Client
-The included [`test_client.py`](test_client.py) shows how to programmatically call the MCP server:
-```bash
-source .venv/bin/activate
-python test_client.py
-```
-
-**Note:** There's a parameter wrapping issue with FastMCP that affects direct client calls. The server works perfectly when called through Claude Desktop or the MCP Inspector.
-
----
-
-### For Claude Code (VS Code Extension)
-
-1. **Install Claude Code** extension in VS Code
-
-2. **Add configuration** to VS Code settings:
-   - Open Settings (⌘+,)
-   - Search for "MCP Servers"
-   - Or edit `settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    }
-  }
-}
-```
-
-3. **Reload VS Code**
-
----
-
-### For Cline (VS Code Extension)
-
-Similar to Claude Code:
-
-```json
-{
-  "cline.mcpServers": {
-    "togmal": {
-      "command": "/Users/hetalksinmaths/togmal/.venv/bin/python",
-      "args": ["/Users/hetalksinmaths/togmal/togmal_mcp.py"]
-    }
-  }
-}
-```
-
----
-
-## Test Commands Run
-
-### ✅ Syntax Validation
-```bash
-source .venv/bin/activate
-python -m py_compile togmal_mcp.py
-```
-**Result:** No syntax errors found
-
-### ✅ Test Examples
-```bash
-source .venv/bin/activate
-python test_examples.py
-```
-**Result:** All 9 test scenarios display correctly:
-1. Math/Physics Speculation Detection
-2. Ungrounded Medical Advice Detection
-3. Dangerous File Operations Detection
-4. Vibe Coding Overreach Detection
-5. Unsupported Claims Detection
-6. Safe Prompt (no detection)
-7. Safe Response with Sources (no detection)
-8. Mixed Issues (multiple detections)
-9. Borderline Medical (properly handled)
-
-### ✅ MCP Client Test
-```bash
-source .venv/bin/activate
-python test_client.py
-```
-**Result:** Server connects successfully, lists 5 tools, statistics tool works correctly
-
----
-
-## What ToGMAL Does
-
-**ToGMAL** (Taxonomy of Generative Model Apparent Limitations) is an MCP server that provides **real-time safety analysis** for LLM interactions.
-
-### Detection Categories
-
-1. **🔬 Math/Physics Speculation**
-   - Theory of everything claims
-   - Invented equations or particles
-   - Ungrounded quantum gravity theories
-
-2. **🏥 Ungrounded Medical Advice**
-   - Diagnoses without qualifications
-   - Treatment recommendations without sources
-   - Missing disclaimers or citations
-
-3. **💾 Dangerous File Operations**
-   - Mass deletion commands
-   - Recursive operations without safeguards
-   - No human-in-the-loop confirmation
-
-4. **💻 Vibe Coding Overreach**
-   - Overly ambitious scope (complete social networks, etc.)
-   - Unrealistic line counts (1000+ lines)
-   - No architectural planning
-
-5. **📊 Unsupported Claims**
-   - Absolute statements without hedging
-   - Statistical claims without sources
-   - Over-confident predictions
-
-### Risk Levels
-
-- **LOW**: Minor issues, no intervention needed
-- **MODERATE**: Worth noting, consider verification
-- **HIGH**: Significant concern, interventions recommended
-- **CRITICAL**: Serious risk, multiple interventions strongly advised
-
-### Intervention Types
-
-- **Step Breakdown**: Complex tasks → verifiable components
-- **Human-in-the-Loop**: Critical decisions → human oversight
-- **Web Search**: Claims → verify against sources
-- **Simplified Scope**: Ambitious projects → realistic scoping
-
----
-
-## For Your VC Pitch 🚀
-
-As a solo founder in Singapore pitching to VCs, here's how to position ToGMAL:
-
-### Demo Flow
-
-1. **Show the Problem**
-   ```bash
-   python test_examples.py | head -80
-   ```
-   Demonstrates various failure modes LLMs can exhibit
-
-2. **Show the Detection**
-   - Open MCP Inspector to show real-time analysis
-   - Or use Claude Desktop with live examples
-
-3. **Show the Intervention**
-   - Highlight how ToGMAL recommends safety interventions
-   - Emphasize privacy-preserving (all local, no API calls)
-   - Show taxonomy building for continuous improvement
-
-### Key Selling Points
-
-✅ **Privacy-First**: All analysis is deterministic and local
-✅ **Real-Time**: Low-latency heuristic detection
-✅ **Extensible**: Easy to add new detection patterns
-✅ **Human-Centered**: Recommendations, not enforcement
-✅ **Crowdsourced**: Taxonomy builds from submitted evidence
-✅ **Production-Ready**: Clean architecture, tested, documented
-
-### Technical Sophistication
-
-- Built on Model Context Protocol (cutting-edge standard)
-- Pydantic validation for type safety
-- FastMCP for efficient server implementation
-- Clear upgrade path (heuristics → ML → federated learning)
-
----
-
-## Next Steps
-
-### Immediate (For Testing)
-
-```bash
-# Test the server functionality
-source .venv/bin/activate
-python test_examples.py
-
-# Or open MCP Inspector
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-```
-
-### For Daily Use
-
-1. Copy config to Claude Desktop
-2. Restart Claude
-3. Use ToGMAL tools in conversations
-
-### For Development
-
-- See [`ARCHITECTURE.md`](ARCHITECTURE.md) for system design
-- See [`DEPLOYMENT.md`](DEPLOYMENT.md) for advanced configuration
-- See [`MCP_CONNECTION_GUIDE.md`](MCP_CONNECTION_GUIDE.md) for connection options
-
----
-
-## Files Created/Updated
-
-✅ Updated: `claude_desktop_config.json` (correct paths)
-✅ Created: `MCP_CONNECTION_GUIDE.md` (comprehensive connection guide)
-✅ Created: `test_client.py` (programmatic MCP client example)
-✅ Created: `SETUP_COMPLETE.md` (this file)
-
----
-
-## Quick Reference
-
-```bash
-# Activate venv
-source .venv/bin/activate
-
-# Run tests
-python test_examples.py
-
-# Open MCP Inspector
-npx @modelcontextprotocol/inspector python togmal_mcp.py
-
-# Test client (has parameter wrapping issue)
-python test_client.py
-
-# Check syntax
-python -m py_compile togmal_mcp.py
-```
-
----
-
-## Questions?
-
-- **Architecture**: See [`ARCHITECTURE.md`](ARCHITECTURE.md)
-- **Deployment**: See [`DEPLOYMENT.md`](DEPLOYMENT.md)
-- **Quick Start**: See [`QUICKSTART.md`](QUICKSTART.md)
-- **Full Docs**: See [`README.md`](README.md)
-- **Connections**: See [`MCP_CONNECTION_GUIDE.md`](MCP_CONNECTION_GUIDE.md)
-
-**Your ToGMAL MCP Server is ready to protect LLM interactions!** 🛡️

VECTOR_DB_STATUS.md

@@ -1,239 +0,0 @@
-# ✅ Vector Database: Successfully Deployed
-
-**Date**: October 19, 2025  
-**Status**: **PRODUCTION READY**
-
----
-
-## 🎉 What's Working
-
-### Core System
-- ✅ **ChromaDB** initialized at `./data/benchmark_vector_db/`
-- ✅ **Sentence Transformers** (all-MiniLM-L6-v2) generating embeddings
-- ✅ **70 MMLU-Pro questions** indexed with success rates
-- ✅ **Real-time similarity search** working (<20ms per query)
-- ✅ **MCP tool integration** ready in `togmal_mcp.py`
-
-### Current Database Stats
-```
-Total Questions: 70
-Source: MMLU-Pro (validation set)
-Domains: 14 (math, physics, biology, chemistry, health, law, etc.)
-Success Rate: 45% (estimated - will update with real scores)
-```
-
----
-
-## 🚀 Quick Test Results
-
-```bash
-$ python test_vector_db.py
-
-📝 Prompt: Calculate the Schwarzschild radius for a black hole
-   Risk: MODERATE
-   Success Rate: 45.0%
-   Similar to: MMLU_Pro (physics)
-   ✓ Correctly identified physics domain
-
-📝 Prompt: Diagnose a patient with chest pain
-   Risk: MODERATE
-   Success Rate: 45.0%
-   Similar to: MMLU_Pro (health)
-   ✓ Correctly identified medical domain
-```
-
-**Key Observation**: Vector similarity is correctly mapping prompts to relevant domains!
-
----
-
-## 📊 What We Learned
-
-### Dataset Access Issues (Solved)
-1. **GPQA Diamond**: ❌ Gated dataset - needs HuggingFace authentication
-   - Solution: `huggingface-cli login` (requires account)
-   - Alternative: Use MMLU-Pro for now (very hard too)
-
-2. **MATH**: ❌ Dataset naming changed on HuggingFace
-   - Solution: Find correct dataset path
-   - Alternative: Already have 70 hard questions
-
-3. **MMLU-Pro**: ✅ **Working perfectly!**
-   - 70 validation questions loaded
-   - Cross-domain coverage
-   - Clear schema
-
-### Success Rates (Next Step)
-- Currently using **estimated 45%** for MMLU-Pro
-- **Next**: Fetch real per-question results from OpenLLM Leaderboard
-  - Top 3 models: Llama 3.1 70B, Qwen 2.5 72B, Mixtral 8x22B
-  - Compute actual success rates per question
-
----
-
-## 🔧 MCP Tool Ready
-
-### `togmal_check_prompt_difficulty`
-
-**Status**: ✅ Integrated in `togmal_mcp.py`
-
-**Usage**:
-```python
-# Via MCP
-result = await togmal_check_prompt_difficulty(
-    prompt="Calculate quantum corrections...",
-    k=5
-)
-
-# Returns:
-{
-    "risk_level": "MODERATE",
-    "weighted_success_rate": 0.45,
-    "similar_questions": [...],
-    "recommendation": "Use chain-of-thought prompting"
-}
-```
-
-**Test it**:
-```bash
-# Start MCP server
-python togmal_mcp.py
-
-# Or via HTTP facade
-curl -X POST http://127.0.0.1:6274/call-tool \
-  -d '{"tool": "togmal_check_prompt_difficulty", "arguments": {"prompt": "Prove P != NP"}}'
-```
-
----
-
-## 📈 Next Steps (Priority Order)
-
-### Immediate (High Value)
-1. **Authenticate with HuggingFace** to access GPQA Diamond
-   ```bash
-   huggingface-cli login
-   # Then re-run: python benchmark_vector_db.py
-   ```
-
-2. **Fetch real success rates** from OpenLLM Leaderboard
-   - Already coded in `_fetch_gpqa_model_results()`
-   - Just needs dataset access
-
-3. **Expand MMLU-Pro to 1000 questions**
-   - Currently sampled 70 from validation
-   - Full dataset has 12K questions
-
-### Enhancement (Medium Priority)
-4. **Add alternative datasets** (no auth required):
-   - ARC-Challenge (reasoning)
-   - HellaSwag (commonsense)
-   - TruthfulQA (factuality)
-
-5. **Domain-specific filtering**:
-   ```python
-   db.query_similar_questions(
-       prompt="Medical diagnosis question",
-       domain_filter="health"
-   )
-   ```
-
-### Research (Low Priority)
-6. **Track capability drift** monthly
-7. **A/B test** vector DB vs heuristics on real prompts
-8. **Integrate with Aqumen** for adversarial question generation
-
----
-
-## 💡 Key Insights
-
-### Why This Works Despite Small Dataset
-Even with 70 questions, the vector DB is **highly effective** because:
-
-1. **Semantic embeddings** capture meaning, not just keywords
-   - "Schwarzschild radius" → correctly matched to physics
-   - "Diagnose patient" → correctly matched to health
-
-2. **Cross-domain coverage**
-   - 14 domains represented
-   - Each domain has 5 representative questions
-
-3. **Weighted similarity** reduces noise
-   - Closest matches get higher weight
-   - Distant matches contribute less
-
-### Production Readiness
-- ✅ **Fast**: <20ms per query
-- ✅ **Reliable**: No external API calls (fully local)
-- ✅ **Explainable**: Returns actual similar questions
-- ✅ **Maintainable**: Just add more questions to improve
-
----
-
-## 🎯 For Your VC Pitch
-
-### Technical Innovation
-> "We built a vector similarity system that detects when prompts are beyond LLM capability boundaries by comparing them to 70+ graduate-level benchmark questions across 14 domains. Unlike static heuristics, this provides real-time, explainable risk assessments."
-
-### Scalability Story
-> "Starting with 70 questions from MMLU-Pro, we can scale to 10,000+ questions from GPQA, MATH, and LiveBench. Each additional question improves accuracy with zero re-training."
-
-### Business Value
-> "This prevents LLMs from confidently answering questions they'll get wrong, reducing hallucination risk in production systems. For Aqumen, it enables difficulty-calibrated assessments that separate experts from novices."
-
----
-
-## 📦 Files Created
-
-### Core Implementation
-- [`benchmark_vector_db.py`](file:///Users/hetalksinmaths/togmal/benchmark_vector_db.py) (596 lines)
-- [`togmal_mcp.py`](file:///Users/hetalksinmaths/togmal/togmal_mcp.py) (updated with new tool)
-
-### Testing & Docs
-- [`test_vector_db.py`](file:///Users/hetalksinmaths/togmal/test_vector_db.py) (55 lines)
-- [`VECTOR_DB_SUMMARY.md`](file:///Users/hetalksinmaths/togmal/VECTOR_DB_SUMMARY.md) (337 lines)
-- [`VECTOR_DB_STATUS.md`](file:///Users/hetalksinmaths/togmal/VECTOR_DB_STATUS.md) (this file)
-
-### Setup
-- [`setup_vector_db.sh`](file:///Users/hetalksinmaths/togmal/setup_vector_db.sh) (automated setup)
-- [`requirements.txt`](file:///Users/hetalksinmaths/togmal/requirements.txt) (updated with dependencies)
-
----
-
-## ✅ Deployment Checklist
-
-- [x] Dependencies installed (`sentence-transformers`, `chromadb`, `datasets`)
-- [x] Vector database built (70 questions indexed)
-- [x] Embeddings generated (all-MiniLM-L6-v2)
-- [x] MCP tool integrated (`togmal_check_prompt_difficulty`)
-- [x] Testing script working
-- [ ] HuggingFace authentication (for GPQA access)
-- [ ] Real success rates from leaderboard
-- [ ] Expanded to 1000+ questions
-- [ ] Integrated with Claude Desktop
-- [ ] A/B tested in production
-
----
-
-## 🚀 Ready to Use!
-
-**The vector database is fully functional and ready for production testing.**
-
-**Next action**: Authenticate with HuggingFace to unlock GPQA Diamond (the hardest dataset), or continue with current 70 MMLU-Pro questions.
-
-**To test now**:
-```bash
-cd /Users/hetalksinmaths/togmal
-python test_vector_db.py
-```
-
-**To use in MCP**:
-```bash
-python togmal_mcp.py
-# Then use togmal_check_prompt_difficulty tool
-```
-
----
-
-**Status**: 🟢 **OPERATIONAL**  
-**Performance**: ⚡ **<20ms per query**  
-**Accuracy**: 🎯 **Domain matching validated**  
-**Next**: 📈 **Scale to 1000+ questions**

VECTOR_DB_SUMMARY.md

@@ -1,336 +0,0 @@
-# Vector Database for Difficulty-Based Prompt Assessment
-
-## 🎯 What We Built
-
-A **vector similarity search system** that replaces static clustering with real-time difficulty assessment by:
-
-1. **Indexing hardest benchmark datasets** (GPQA Diamond, MMLU-Pro, MATH)
-2. **Finding similar questions** via cosine similarity in embedding space
-3. **Computing weighted difficulty scores** based on benchmark success rates
-4. **Providing explainable risk assessments** for any prompt
-
----
-
-## 📊 Datasets Included (Ranked by Difficulty)
-
-### 1. **GPQA Diamond** ⭐ (Hardest)
-- **Size**: 198 expert-written questions
-- **Topics**: Graduate-level Physics, Biology, Chemistry
-- **Difficulty**: GPT-4 gets ~50%, most models <30%
-- **Dataset**: `Idavidrein/gpqa` (gpqa_diamond split)
-- **Why**: Google-proof questions that even PhD holders struggle with
-
-### 2. **MMLU-Pro** (Very Hard)
-- **Size**: 12,000 questions across 14 domains
-- **Topics**: Math, Science, Law, Engineering, Business
-- **Difficulty**: 10 choices vs 4 (reduces guessing), ~45% success
-- **Dataset**: `TIGER-Lab/MMLU-Pro`
-- **Why**: Broader coverage than standard MMLU, harder problems
-
-### 3. **MATH** (Competition Mathematics)
-- **Size**: 12,500 problems
-- **Topics**: Algebra, Geometry, Number Theory, Calculus
-- **Difficulty**: GPT-4 ~50%, requires multi-step reasoning
-- **Dataset**: `hendrycks/competition_math`
-- **Why**: Tests complex mathematical reasoning chains
-
----
-
-## 🚀 How It Works
-
-### Architecture
-```
-User Prompt → Embedding Model → Vector DB → K Nearest Questions → Weighted Score
-                    ↓                                ↓
-            all-MiniLM-L6-v2              (cosine similarity)
-```
-
-### Example Flow
-```python
-prompt = "Calculate the quantum correction for a 3D harmonic oscillator"
-
-# 1. Embed prompt
-embedding = model.encode(prompt)
-
-# 2. Find 5 nearest benchmark questions
-nearest = [
-    {"source": "GPQA", "success_rate": 0.12, "similarity": 0.87},
-    {"source": "MATH", "success_rate": 0.18, "similarity": 0.82},
-    {"source": "GPQA", "success_rate": 0.09, "similarity": 0.79},
-    {"source": "MMLU-Pro", "success_rate": 0.23, "similarity": 0.75},
-    {"source": "GPQA", "success_rate": 0.15, "similarity": 0.73}
-]
-
-# 3. Compute weighted difficulty
-weighted_success = (0.12*0.87 + 0.18*0.82 + ...) / (0.87 + 0.82 + ...)
-                 = 0.14 (14% success rate)
-
-# 4. Return risk assessment
-{
-    "risk_level": "CRITICAL",
-    "weighted_success_rate": 0.14,
-    "explanation": "Similar to questions with <10% success rate",
-    "recommendation": "Break into steps, use tools, human-in-the-loop"
-}
-```
-
----
-
-## 📦 Files Created
-
-### Core Implementation
-- **`benchmark_vector_db.py`** (596 lines)
-  - `BenchmarkVectorDB` class
-  - Dataset loaders (GPQA, MMLU-Pro, MATH)
-  - Embedding generation (Sentence Transformers)
-  - ChromaDB integration
-  - Query interface with weighted difficulty
-
-### Integration
-- **`togmal_mcp.py`** (updated)
-  - New MCP tool: `togmal_check_prompt_difficulty(prompt, k=5)`
-  - Added to `togmal_list_tools_dynamic` response
-
-### Setup
-- **`setup_vector_db.sh`**
-  - Automated setup script
-  - Installs dependencies
-  - Builds initial database
-
-### Dependencies (added to `requirements.txt`)
-- `sentence-transformers>=2.2.0` - Embeddings
-- `chromadb>=0.4.0` - Vector database
-- `datasets>=2.14.0` - HuggingFace dataset loading
-
----
-
-## ⚡ Quick Start
-
-### Step 1: Install Dependencies & Build Database
-```bash
-cd /Users/hetalksinmaths/togmal
-chmod +x setup_vector_db.sh
-./setup_vector_db.sh
-```
-
-This will:
-- Install `sentence-transformers`, `chromadb`, `datasets`
-- Download GPQA Diamond, MMLU-Pro, MATH datasets
-- Generate embeddings for ~2000 questions
-- Store in `./data/benchmark_vector_db/`
-
-**Expected time**: 5-10 minutes
-
-### Step 2: Test the Vector DB
-```bash
-python benchmark_vector_db.py
-```
-
-Expected output:
-```
-Loading GPQA Diamond dataset...
-Loaded 198 questions from GPQA Diamond
-
-Loading MMLU-Pro dataset...
-Loaded 1000 questions from MMLU-Pro
-
-Generating embeddings (this may take a few minutes)...
-Indexed 1698 questions
-
-Testing with example prompts:
-  Prompt: Calculate the quantum correction...
-    Risk Level: CRITICAL
-    Weighted Success Rate: 12%
-    Recommendation: Break into steps, use tools
-```
-
-### Step 3: Use in MCP Server
-```bash
-# Start the server
-python togmal_mcp.py
-
-# Or via HTTP facade
-curl -X POST http://127.0.0.1:6274/call-tool \
-  -H "Content-Type: application/json" \
-  -d '{
-    "tool": "togmal_check_prompt_difficulty",
-    "arguments": {
-      "prompt": "Prove that P != NP",
-      "k": 5
-    }
-  }'
-```
-
----
-
-## 🔍 MCP Tool: `togmal_check_prompt_difficulty`
-
-### Parameters
-```python
-prompt: str           # Required - the user's prompt/question
-k: int = 5           # Optional - number of similar questions to retrieve
-domain_filter: str   # Optional - filter by domain (e.g., 'physics')
-```
-
-### Response Schema
-```json
-{
-  "similar_questions": [
-    {
-      "question_id": "gpqa_diamond_42",
-      "question_text": "Calculate the ground state...",
-      "source": "GPQA_Diamond",
-      "domain": "physics",
-      "success_rate": 0.12,
-      "difficulty_score": 0.88,
-      "similarity": 0.87
-    }
-  ],
-  "weighted_difficulty_score": 0.82,
-  "weighted_success_rate": 0.18,
-  "avg_similarity": 0.79,
-  "risk_level": "HIGH",
-  "explanation": "Very hard - similar to questions with <30% success rate",
-  "recommendation": "Multi-step reasoning with verification, consider web search",
-  "database_stats": {
-    "total_questions": 1698,
-    "sources": {"GPQA_Diamond": 198, "MMLU_Pro": 1000, "MATH": 500}
-  }
-}
-```
-
-### Risk Levels
-- **MINIMAL** (>70% success): LLMs handle well
-- **LOW** (50-70%): Moderate difficulty, within capability
-- **MODERATE** (30-50%): Hard, at capability boundary
-- **HIGH** (<30%): Very hard, likely to struggle
-- **CRITICAL** (<10%): Nearly impossible for current LLMs
-
----
-
-## 🎯 Why Vector DB > Clustering
-
-### Traditional Clustering Approach ❌
-```python
-# Problem: Forces everything into fixed buckets
-clusters = kmeans.fit(questions)  # Creates 5 clusters
-new_prompt → assign to cluster 3 → "hard"
-
-Issues:
-- Arbitrary cluster boundaries
-- New prompts forced into wrong cluster
-- No explainability (why cluster 3?)
-- Requires re-clustering for updates
-```
-
-### Vector Similarity Approach ✅
-```python
-# Solution: Direct comparison to known examples
-new_prompt → find 5 nearest questions → weighted average
-              ↓
-        [GPQA: 12%, MATH: 18%, GPQA: 9%, ...]
-              ↓
-        Weighted: 14% success → CRITICAL risk
-
-Advantages:
-- No arbitrary boundaries
-- Works for any prompt
-- Explainable ("87% similar to GPQA physics Q42")
-- Real-time updates (just add to DB)
-- Confidence weighted by similarity
-```
-
----
-
-## 📈 Next Steps
-
-### Immediate (High Priority)
-1. ✅ **Built**: Core vector DB with GPQA, MMLU-Pro, MATH
-2. ✅ **Integrated**: MCP tool `togmal_check_prompt_difficulty`
-3. 🔄 **TODO**: Get real per-question success rates from OpenLLM leaderboard
-
-### Enhancement (Medium Priority)
-4. **Add more datasets**:
-   - LiveBench (contamination-free)
-   - IFEval (instruction following)
-   - DABStep (data analysis)
-
-5. **Improve success rate accuracy**:
-   ```python
-   # Load per-model results from HuggingFace leaderboard
-   models = ["meta-llama__Meta-Llama-3-70B-Instruct", ...]
-   for model in models:
-       results = load_dataset(f"open-llm-leaderboard/details_{model}")
-       # Compute per-question success across 100+ models
-   ```
-
-6. **Domain-specific filtering**:
-   ```python
-   db.query_similar_questions(
-       prompt="Diagnose this medical case",
-       domain_filter="medicine"  # Only compare to medical questions
-   )
-   ```
-
-### Advanced (Low Priority)
-7. **Track capability drift**: Re-compute success rates monthly
-8. **Hybrid approach**: Use clustering to organize vector space regions
-9. **Multi-modal**: Add code benchmarks (HumanEval, MBPP)
-
----
-
-## 🔬 Research Applications
-
-### For ToGMAL
-- **Proactive warnings**: "This prompt is 89% similar to GPQA questions with 8% success"
-- **Difficulty calibration**: Adjust interventions based on similarity scores
-- **Pattern discovery**: Identify emerging hard question types
-
-### For Aqumen (Adversarial Testing)
-- **Target generation**: Create questions at 20-30% success (capability boundary)
-- **Difficulty tuning**: Adjust assessment hardness based on user performance
-- **Gap analysis**: Find underrepresented hard topics in current assessments
-
-### For Grant Applications
-- **Novel contribution**: "First vector-based LLM capability boundary detector"
-- **Quantifiable impact**: "Identifies prompts beyond LLM capability with 85% accuracy"
-- **Practical deployment**: "Integrated into production MCP server for Claude Desktop"
-
----
-
-## 💡 Key Innovation Summary
-
-**Instead of asking "What cluster does this belong to?"**
-**We ask "What are the 5 most similar questions we've tested?"**
-
-This is:
-- ✅ More accurate (no forced clustering)
-- ✅ More explainable ("87% similar to this exact GPQA question")
-- ✅ More flexible (works for any prompt)
-- ✅ More maintainable (just add to DB, no re-training)
-
-The clustering work was valuable research, but **vector similarity is the production solution**.
-
----
-
-## 📚 References
-
-### Datasets
-- GPQA: https://huggingface.co/datasets/Idavidrein/gpqa
-- MMLU-Pro: https://huggingface.co/datasets/TIGER-Lab/MMLU-Pro
-- MATH: https://huggingface.co/datasets/hendrycks/competition_math
-
-### Models
-- Sentence Transformers: https://www.sbert.net/
-- all-MiniLM-L6-v2: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2
-
-### Vector DB
-- ChromaDB: https://www.trychroma.com/
-
----
-
-## 🎉 Status
-
-**COMPLETE**: Vector database system ready for production use!
-
-Next: Run `./setup_vector_db.sh` to build the database and start using `togmal_check_prompt_difficulty` in your MCP workflows.