A sophisticated desktop application for authoring, validating, and visualizing Formal Reasoning Mode (FRM) problem descriptions with equation-first mathematical modeling and AI-powered novelty assurance.
Features • Quick Start • Architecture • Screenshots • Contributing
FRM Desktop is a cutting-edge Electron + React application designed for mechanism-level, equation-first reasoning in the AI era. It provides a comprehensive workspace for building sophisticated mathematical models across multiple domains including medicine, biology, engineering, AI, and more.
The application features AI-powered novelty assurance, Model Context Protocol (MCP) integration, and real-time communication logging to ensure every model you build remains schema-compliant, novel, and ready for AI consumption. The system is driven entirely by the enhanced frm_schema.json specification with comprehensive novelty assessment capabilities.
- 📝 Schema-Driven Editor - Intuitive form editor with real-time validation feedback
- 🔍 Live AJV Validation - Instant validation against enhanced FRM JSON Schema with novelty assurance
- 🧮 Equation-First Modeling - Built for ODE, PDE, DAE, SDE, and hybrid systems with novelty tagging
- 🤖 AI Schema Generator - Generate domain-specific schemas using configurable OpenAI API integration
- 📊 Interactive Visualization - Real-time model visualization and analysis
- 🌙 Modern UI - Beautiful dark/light theme with smooth animations and lazy loading
- 🔧 Multi-Domain Support - 30+ domains including AI, astrophysics, climate science, quantum computing
- 📐 Mathematical Rendering - KaTeX integration for beautiful equation display
- 💾 Import/Export - JSON-based problem sharing and collaboration
- ⚡ Performance Optimized - Lazy-loaded components, validation caching, and efficient state management
- 🛡️ Type Safety - Full TypeScript support with generated schema types and runtime type guards
- 🔗 MCP Integration - Model Context Protocol server for AI tool integration
- 📡 Real-time Communication - Live communication logging and monitoring panel
- 🎯 Novelty Assurance - AI-powered novelty assessment with similarity metrics and redundancy checking
- ⏱️ Generation Timer - Real-time timer display during schema generation with precise duration tracking
- 📋 Generation Logging - Comprehensive logging of each generation including model, domain, sub-domain, and duration
- 📝 Monaco Editor - Professional code editor with syntax highlighting and IntelliSense
- 🔄 Schema Migration - Built-in tools for schema version migration and updates
- 🐛 Schema Debugging - Comprehensive debugging utilities for schema validation
- 📋 Clipboard Integration - Advanced copy/paste functionality for schema elements
- ⚡ Build Optimization - Advanced code splitting and chunk optimization
- 🛡️ Error Boundaries - Robust error handling with graceful degradation
- 📊 Virtualized Lists - High-performance rendering for large datasets
- AI-Powered Novelty Detection - Integrated similarity assessment using cosine embeddings, ROUGE-L, and NovAScore
- Comprehensive Citation Management - Full citation tracking with coverage analysis and conflict detection
- Evidence Mapping - Systematic evidence tracking linking claims to supporting citations
- Redundancy Prevention - Automated detection of duplicate work with configurable thresholds
- MCP Server Implementation - Built-in MCP server for AI tool integration
- Real-time Communication Logging - Live monitoring of AI interactions and tool calls
- Tool Validation - Comprehensive validation of FRM documents through MCP tools
- Performance Monitoring - Real-time statistics and connection status tracking
- Validation Caching - LRU-style caching with 90% performance improvement for repeated operations
- Lazy Loading - Component-level lazy loading for faster initial load times
- Memory Management - Optimized memory usage with WeakMap caching and cleanup
- Type Guard Optimization - Runtime type validation with performance monitoring
- Domain Selector - Comprehensive domain selection with 30+ scientific domains
- Communication Panel - Real-time monitoring of AI interactions and system events
- Enhanced Validation - Detailed error reporting with context-aware suggestions
- Modern UI Components - Radix UI components with smooth animations and accessibility
- Node.js 18+
- npm 9+
# Clone the repository
git clone https://github.com/DesmondForward/formal-reasoning-mode.git
cd formal-reasoning-mode
# Install dependencies
npm install
# Start development server
npm run devThe development script starts both the Vite dev server and Electron, providing hot-reload for rapid development.
# Build for production
npm run build
# Create desktop packages
npm run dist # All platforms
npm run dist:win # Windows only
npm run dist:mac # macOS only
npm run dist:linux # Linux only| Layer | Technology | Purpose |
|---|---|---|
| 🖥️ Desktop | Electron 38 | Cross-platform desktop runtime |
| ⚛️ Frontend | React 18 + TypeScript 5.3.3 | Modern UI with type safety |
| 🎨 Styling | Tailwind CSS 3.4.0 + Framer Motion | Responsive design with animations |
| 🔍 Validation | AJV 8.12.0 + json-schema-to-ts | Schema validation and type generation |
| 🧮 Math | KaTeX 0.16.9 + react-katex | Mathematical equation rendering |
| 🔧 Build | Vite 7.1.7 | Fast development and optimized builds |
| 🤖 AI Integration | Configurable OpenAI API | AI-powered schema generation |
| 🔗 MCP | Model Context Protocol | AI tool integration and communication |
| 📊 State Management | React Hooks + Context | Efficient state management with caching |
- Monaco Editor - Professional code editing with syntax highlighting
- Radix UI - Accessible, unstyled UI components
- Axios - HTTP client for API communication
- Zod - Runtime type validation and schema parsing
- PostCSS - CSS processing and optimization
- Cross-env - Cross-platform environment variable handling
📁 FRM Desktop/
├── 📁 main/ # Electron main process
│ ├── main.ts # Main process entry point
│ ├── preload.ts # Secure preload script
│ └── 📁 mcp/ # Model Context Protocol server
│ └── frmMcpServer.ts # MCP server implementation
├── 📁 src/ # React renderer application
│ ├── 📁 components/ # React components
│ │ ├── 📁 editors/ # Specialized form editors
│ │ │ ├── NoveltyAssuranceEditor.tsx # Novelty assessment editor
│ │ │ ├── InputEditor.tsx # Input specification editor
│ │ │ ├── ModelingEditor.tsx # Mathematical modeling editor
│ │ │ ├── MethodSelectionEditor.tsx # Method selection editor
│ │ │ ├── SolutionAnalysisEditor.tsx # Solution analysis editor
│ │ │ ├── ValidationEditor.tsx # Validation editor
│ │ │ └── OutputContractEditor.tsx # Output contract editor
│ │ ├── 📁 ui/ # Reusable UI components
│ │ ├── SchemaEditor.tsx # Main schema editor
│ │ ├── ValidationPanel.tsx # Real-time validation
│ │ ├── VisualizationPanel.tsx # Model visualization
│ │ ├── CommunicationLogPanel.tsx # Real-time communication monitoring
│ │ ├── VirtualizedEventList.tsx # High-performance event rendering
│ │ ├── ErrorBoundary.tsx # Error handling component
│ │ └── DomainSelector.tsx # Domain selection component
│ ├── 📁 hooks/ # Custom React hooks
│ │ ├── useCommunication.ts # Communication monitoring
│ │ ├── useValidation.ts # Validation with caching
│ │ ├── useFRMData.ts # Data management
│ │ └── useTheme.ts # Theme management
│ ├── 📁 data/ # Schema definitions and types
│ ├── 📁 utils/ # Utility functions
│ │ ├── typeGuards.ts # Runtime type validation
│ │ ├── validation.ts # Validation utilities
│ │ ├── schemaMigration.ts # Schema migration tools
│ │ ├── schemaDebug.ts # Schema debugging utilities
│ │ ├── schemaGenerator.ts # AI schema generation
│ │ └── clipboard.ts # Clipboard utilities
│ └── App.tsx # Application root
├── 📄 frm_schema.json # Enhanced FRM JSON Schema with novelty assurance
└── 📄 package.json # Dependencies and scripts
Create a .env.local file for development. Copy from .env.example and configure your preferred AI provider:
# AI Provider Configuration
# Set AI_PROVIDER to one of: openai, google, anthropic
AI_PROVIDER=openai
# OpenAI Configuration (for AI example generation)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5.5
OPENAI_API_URL=https://api.openai.com/v1/responses
OPENAI_REASONING_EFFORT=medium
OPENAI_TEXT_VERBOSITY=low
# Google Gemini Configuration
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_MODEL=gemini-2.5-pro
GOOGLE_API_URL=https://generativelanguage.googleapis.com/v1beta
# Anthropic Claude Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages
# Development
VITE_DEV_SERVER_URL=http://localhost:3000Supported AI Providers:
- OpenAI: GPT-5.5, GPT-5.4, GPT-5.2, GPT-5, GPT-4o, GPT-4o-mini, GPT-4-turbo
- Google: Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite, Gemini 1.5 Pro, Gemini 1.5 Flash
- Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku
The application is fully driven by frm_schema.json. To extend or modify the schema:
- Update
frm_schema.jsonwith your changes - Regenerate TypeScript types:
npm run generate-types - The UI will automatically adapt to schema changes
- Launch FRM Desktop
- Select a domain from the dropdown (medicine, biology, engineering, etc.)
- Generate a schema or start from scratch
- Edit the schema sections (Best for Professionals):
- Metadata: Problem ID, domain, version
- Input: Problem summary, known quantities, unknowns
- Modeling: Equations, variables, model class
- Method Selection: Solution methods and justification
- Validation: Quality metrics and checks
- Output Contract: Required sections and formatting
- Novelty Assurance: Novelty assessment and citation management
// Generate a medicine domain schema
const example = await generateSchemaProblem({
domain: 'medicine',
scenarioHint: 'epidemic modeling with vaccination'
})// Real-time validation
const validation = useValidation(frmSchema)
const isValid = validation.isValid
const errors = validation.errors| Domain | Description | Example Use Cases |
|---|---|---|
| 🤖 Artificial Intelligence | AI/ML models, neural networks, and intelligent systems | Deep learning, reinforcement learning, optimization |
| 🌌 Astrophysics | Celestial mechanics, stellar dynamics, and cosmic phenomena | Stellar evolution, orbital mechanics, cosmology |
| 🤖 Autonomous Systems | Robotics, autonomous vehicles, and self-governing systems | Path planning, control systems, decision making |
| 🧬 Biology | Biological systems and processes | Population dynamics, enzyme kinetics, gene regulation |
| ⚗️ Chemical Engineering | Process design, reactor engineering, and chemical systems | Reactor design, process optimization, kinetics |
| 🧪 Chemistry | Chemical reactions and processes | Reaction kinetics, molecular dynamics, catalysis |
| 🌍 Climate Science | Climate modeling, carbon dynamics, and environmental systems | Climate change, ecosystem dynamics, pollution |
| 💻 Coding | Software engineering and computational problems | Algorithm design, system architecture, performance optimization |
| 💰 Computational Finance | Financial modeling and quantitative analysis | Risk assessment, portfolio optimization, derivatives |
| 🛡️ Cybersecurity | Security systems and threat modeling | Cryptography, network security, threat analysis |
| 📊 Data Science | Data analysis and machine learning | Statistical modeling, predictive analytics, data mining |
| 💰 Economics | Economic modeling and analysis | Market dynamics, policy impact, resource allocation |
| ⚡ Energy Systems | Energy generation, storage, and distribution | Renewable energy, grid optimization, storage systems |
| 🏭 Engineering | Engineering systems and control | Control systems, structural analysis, optimization |
| 🌊 Fluid Dynamics | Fluid flow and transport phenomena | CFD, turbulence modeling, heat transfer |
| 🌊 Fluid Mechanics | Fluid behavior and properties | Viscous flow, compressible flow, multiphase systems |
| 🌍 Geosciences | Earth sciences and geological processes | Seismic modeling, climate patterns, geological formations |
| 🔬 General | General-purpose mathematical and scientific problems | Cross-domain applications, fundamental research |
| 🧱 Materials Science | Material properties and behavior | Material design, phase transitions, mechanical properties |
| 🧮 Mathematics | Pure and applied mathematical problems | Mathematical proofs, numerical methods, optimization |
| 🏥 Medicine | Medical and healthcare applications | Disease modeling, drug kinetics, treatment optimization |
| 📏 Metrology | Measurement science and standards | Calibration, uncertainty quantification, measurement systems |
| 🧠 Neuroscience | Brain and nervous system modeling | Neural networks, cognitive modeling, brain dynamics |
| 🌐 Network Science | Network analysis and graph theory | Social networks, infrastructure networks, information flow |
| ⚛️ Physics | Physical systems and phenomena | Quantum mechanics, thermodynamics, electromagnetism |
| 🏥 Public Health | Population health and epidemiology | Disease spread, health policy, population dynamics |
| ⚛️ Quantum Computing | Quantum systems and algorithms | Quantum algorithms, error correction, optimization |
| 🌱 Renewable Energy | Sustainable energy systems | Solar modeling, wind energy, energy storage |
| 🤖 Robotics | Robotic systems and automation | Motion planning, sensor fusion, autonomous navigation |
| 📡 Signal Processing | Signal analysis and processing | Audio processing, image analysis, communication systems |
| 👥 Social Science | Social systems and human behavior | Social dynamics, policy analysis, behavioral modeling |
| 🚀 Space Technology | Space systems and aerospace engineering | Orbital mechanics, spacecraft design, mission planning |
| 🧬 Synthetic Biology | Engineered biological systems | Synthetic circuits, metabolic engineering, bio-design |
| 🧬 Systems Biology | Biological system integration | Multi-scale modeling, biological networks, systems analysis |
- ✅ Type Safety - Generated TypeScript types from JSON Schema with runtime type guards
- ✅ Real-time Validation - AJV validation with detailed error reporting and caching
- ✅ Schema Evolution - Automatic UI updates when schema changes
- ✅ Import/Export - Full schema compliance for data portability
- ✅ Novelty Assessment - AI-powered novelty detection with similarity metrics
- ✅ Redundancy Checking - Automated detection of duplicate or similar work
- ✅ Citation Management - Comprehensive citation tracking and validation
- ✅ Evidence Tracking - Systematic evidence mapping for novelty claims
- Lazy Loading - Components load on-demand to reduce initial bundle size
- Validation Caching - LRU cache for validation results with 90% performance improvement
- Code Splitting - Intelligent chunking for optimal loading performance
- Memory Management - WeakMap caching and automatic cleanup
- Virtualized Rendering - High-performance rendering for large datasets
- Chunk Optimization - Manual chunk configuration for optimal loading
- Tree Shaking - Dead code elimination for smaller bundles
- Asset Optimization - Compressed assets and optimized images
- Cross-platform Compatibility - Cross-env for consistent environment handling
- Design - Plan your schema structure and requirements
- Implement - Use the Monaco editor for precise schema editing
- Validate - Real-time validation with detailed error reporting
- Debug - Use built-in debugging utilities for schema issues
- Migrate - Apply schema migrations for version updates
- Configure - Set up OpenAI API credentials
- Generate - Use AI to generate domain-specific schemas
- Validate - Ensure generated schemas pass validation
- Refine - Iterate on AI-generated content
- Monitor - Track AI interactions via communication panel
For detailed troubleshooting information, see SETUP.md.
- Schema errors on import: The file must satisfy
frm_schema.json; the app reports validation details in the Validation panel - Electron window stays blank: Ensure the Vite dev server (port 3000 by default) is running and reachable
- TypeScript errors: Run
npm run buildto surface compile issues introduced by schema changes - MCP connection issues: Check the Communication Log Panel for connection status and error details
- AI generation fails: Verify your OpenAI API key is correctly set in
.env.localand restart the application - Performance issues: The app uses lazy loading and caching; initial load may take a moment for large schemas
We welcome contributions! Here's how to get started:
# Fork and clone the repository
git clone https://github.com/DesmondForward/formal-reasoning-mode.git
cd formal-reasoning-mode
# Install dependencies
npm install
# Start development server
npm run dev- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes with clear, descriptive commits
- Test your changes thoroughly
- Submit a pull request with a detailed description
- TypeScript for type safety
- ESLint for code quality
- Prettier for code formatting
- Conventional Commits for commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
- Formal Reasoning Mode - The underlying methodology and schema
- OpenAI - For AI-powered example generation
- Electron - For cross-platform desktop capabilities
- React - For the modern UI framework
- Tailwind CSS - For the beautiful design system
- 📖 Documentation: Wiki (Coming Soon)
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions (Coming Soon)
Built with ❤️ for the future of mathematical modeling and AI reasoning