algomath-extract 1.0.0

package/README.md

@@ -0,0 +1,260 @@
+# AlgoMath Framework
+
+**AlgoMath** transforms mathematical algorithm descriptions from PDFs and text files into executable Python code through an intuitive workflow integrated with opencode.
+
+**Core Value:** Mathematicians can reliably convert complex algorithmic descriptions from research papers into correct, reproducible, executable code with minimal manual intervention.
+
+---
+
+## Installation
+
+### Quick Install
+```bash
+npx algomath@latest
+```
+
+The installer will:
+1. Check for Python 3.11+ (auto-install guidance if missing)
+2. Install to OpenCode (and optionally Claude Code)
+3. Install Python dependencies (pdfplumber, pydantic)
+
+### Manual Install
+```bash
+# Global install
+npm install -g algomath
+
+# Or local install per-project
+npm install algomath
+```
+
+---
+
+## Quick Start
+
+### 1. Extract Algorithm from PDF
+```bash
+/algo-extract research_paper.pdf
+```
+This will:
+- Extract text from the PDF
+- Parse the algorithm using LLM
+- Structure it into steps
+- Save to `.algomath/algorithms/{name}/`
+
+### 2. Generate Python Code
+```bash
+/algo-generate
+```
+Generates executable Python code with:
+- Type hints for mathematical clarity
+- Docstrings explaining the algorithm
+- Executable code from structured steps
+
+### 3. Execute Code
+```bash
+/algo-run
+```
+Safely executes in sandboxed environment with:
+- Timeout protection (30s default)
+- Output capture
+- Error handling
+
+### 4. Verify Results
+```bash
+/algo-verify
+```
+Verifies correctness with:
+- Execution status check
+- Algorithm explanation
+- Edge case detection
+
+---
+
+## Available Commands
+
+| Command | Purpose | Mode |
+|---------|---------|------|
+| `/algo-extract <file>` | Extract algorithm from PDF/text | Interactive |
+| `/algo-generate` | Generate Python code | Auto |
+| `/algo-run` | Execute code | Auto |
+| `/algo-verify` | Verify results | Interactive |
+| `/algo-status` | Show current state | Info |
+| `/algo-list` | List saved algorithms | Info |
+| `/algo-help` | Show help | Info |
+
+---
+
+## Workflow Modes
+
+### Step-by-Step (Default)
+```bash
+/algo-extract research.pdf
+```
+- Prompts at each stage
+- Shows extracted text for review
+- Shows structured steps for editing
+- User controls the process
+
+### Auto Mode
+```bash
+/algo-extract --auto research.pdf
+```
+- Extracts without prompts
+- Saves automatically
+- Fastest path
+
+### Step Explanation
+```bash
+/algo-verify --step 3
+```
+Explains step 3 in detail.
+
+---
+
+## Architecture
+
+```
+PDF/Text → Extract → Steps → Generate → Code → Run → Verify
+    │         │         │          │        │      │
+    │         │         │          │        │      └─ Explanation
+    │         │         │          │        │         Edge cases
+    │         │         │          │        └─ Sandbox execution
+    │         │         │          │           Output capture
+    │         │         │          └─ Python generation
+    │         │         │             Type hints
+    │         │         │             Docstrings
+    │         │         └─ LLM parsing
+    │         │            Mathematical notation
+    │         └─ Text extraction
+    │            PDF/Text files
+    │            Auto-detection
+    └─ Your research paper
+```
+
+---
+
+## Features
+
+### PDF Processing
+- Extracts text from text-based PDFs
+- Supports `.txt`, `.md` files
+- Auto-detects file type
+- Handles encoding issues
+
+### Algorithm Extraction
+- LLM-powered parsing
+- Identifies inputs, outputs, steps
+- Handles mathematical notation
+- Supports loops, conditionals, assignments
+
+### Code Generation
+- Template-based (fast, reliable)
+- LLM-enhanced (for complex expressions)
+- Type hints included
+- Docstrings explain algorithm
+- Standard library only
+
+### Safe Execution
+- Subprocess isolation
+- Timeout protection (30s default)
+- Resource limits
+- No filesystem escape
+- Output capture
+
+### Verification
+- Execution status check
+- Results comparison
+- Natural language explanation
+- Edge case detection
+- Diagnostic mode for failures
+
+---
+
+## Directory Structure
+
+```
+.algomath/
+├── algorithms/
+│   └── {algorithm-name}/
+│       ├── metadata.json       # Algorithm info
+│       ├── source.txt          # Original text
+│       ├── steps.json          # Structured steps
+│       ├── generated.py        # Python code
+│       ├── execution.log       # Run results
+│       └── verification.log    # Verification
+└── context.py                  # State management
+```
+
+---
+
+## State Machine
+
+```
+IDLE → EXTRACTED → STEPS → CODE → EXECUTED → VERIFIED
+```
+
+- Resume from any state
+- Multiple algorithms in progress
+- Git versioning per algorithm
+- Cross-session persistence
+
+---
+
+## Dependencies
+
+### Python
+- Python 3.11+
+- pdfplumber (PDF text extraction)
+- pydantic (data validation)
+
+### Node.js (for installer)
+- chalk (terminal colors)
+- inquirer (interactive prompts)
+- commander (CLI framework)
+
+---
+
+## Example
+
+```bash
+# Extract from paper
+/algo-extract "research_paper.pdf" --name "dijkstra"
+
+# Review extracted steps
+/algo-status
+
+# Generate code
+/algo-generate
+
+# Run the algorithm
+/algo-run
+
+# Verify it worked
+/algo-verify
+
+# Done!
+```
+
+---
+
+## Configuration
+
+Set in `.algomath/config.json`:
+
+```json
+{
+  "mode": "step-by-step",
+  "timeout": 30,
+  "parallel": true
+}
+```
+
+---
+
+## License
+
+MIT License - see LICENSE file
+
+---
+
+**AlgoMath** - Making algorithm implementation reliable.

package/bin/algo-extract.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * AlgoMath Extract Command
+ * 
+ * Extract algorithm from mathematical text using interactive prompts
+ * Usage: /algo-extract
+ * 
+ * This command will:
+ * 1. Prompt user for mathematical text (or accept from clipboard/file)
+ * 2. Extract structured algorithm steps
+ * 3. Save to context
+ */
+
+const { Command } = require('commander');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const ora = require('ora');
+const { spawn } = require('child_process');
+const path = require('path');
+
+const program = new Command();
+
+program
+  .name('algo-extract')
+  .description('Extract algorithm from mathematical text')
+  .option('-t, --text <text>', 'Mathematical text describing the algorithm')
+  .option('-n, --name <name>', 'Optional name for the algorithm')
+  .option('-f, --file <file>', 'Read text from file')
+  .option('--clipboard', 'Read text from clipboard')
+  .action(async (options) => {
+    console.log(chalk.blue.bold('╔════════════════════════════════════════╗'));
+    console.log(chalk.blue.bold('║     AlgoMath - Extract Algorithm       ║'));
+    console.log(chalk.blue.bold('╚════════════════════════════════════════╝'));
+    console.log();
+
+    try {
+      let text = options.text;
+      let name = options.name;
+
+      // If no text provided, prompt interactively
+      if (!text && !options.file && !options.clipboard) {
+        const answers = await inquirer.prompt([
+          {
+            type: 'editor',
+            name: 'text',
+            message: 'Paste the mathematical text describing the algorithm:',
+            validate: (input) => input.trim().length > 0 || 'Text is required'
+          },
+          {
+            type: 'input',
+            name: 'name',
+            message: 'Algorithm name (optional):',
+            default: ''
+          }
+        ]);
+        text = answers.text;
+        name = answers.name || null;
+      } else if (options.file) {
+        const fs = require('fs');
+        text = fs.readFileSync(options.file, 'utf8');
+      }
+
+      // Validate we have text
+      if (!text || text.trim().length === 0) {
+        console.error(chalk.red('Error: No text provided'));
+        process.exit(1);
+      }
+
+      // Show extraction progress
+      const spinner = ora('Extracting algorithm...').start();
+
+      // Call Python extraction
+      const pythonScript = path.join(__dirname, '..', 'src', 'cli', 'cli_entry.py');
+      const pythonArgs = ['extract', text];
+      if (name) {
+        pythonArgs.push('--name', name);
+      }
+
+      const result = await runPython(pythonScript, pythonArgs);
+      
+      spinner.succeed('Extraction complete!');
+      
+      // Parse and display results
+      const output = JSON.parse(result);
+      displayResult(output);
+
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+function runPython(script, args) {
+  return new Promise((resolve, reject) => {
+    const python = spawn('python3', [script, ...args], {
+      cwd: path.join(__dirname, '..')
+    });
+
+    let output = '';
+    let error = '';
+
+    python.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    python.stderr.on('data', (data) => {
+      error += data.toString();
+    });
+
+    python.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(error || `Python process exited with code ${code}`));
+      } else {
+        resolve(output);
+      }
+    });
+  });
+}
+
+function displayResult(output) {
+  console.log();
+  console.log(chalk.green.bold('✓ Algorithm extracted successfully'));
+  console.log();
+  
+  if (output.algorithm) {
+    console.log(chalk.cyan('Algorithm:'), output.algorithm.name || '(unnamed)');
+    console.log(chalk.cyan('Steps:'), output.algorithm.steps?.length || 0);
+    console.log();
+    
+    if (output.next_steps) {
+      console.log(chalk.gray('Next steps:'));
+      output.next_steps.forEach(step => {
+        console.log(chalk.gray(`  • ${step}`));
+      });
+    }
+  }
+  
+  console.log();
+  console.log(chalk.blue('Use /algo-generate to generate code from these steps'));
+}
+
+program.parse();

package/bin/algo-generate.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * AlgoMath Generate Command
+ * 
+ * Generate Python code from extracted algorithm steps
+ * Usage: /algo-generate
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const { spawn } = require('child_process');
+const path = require('path');
+
+const program = new Command();
+
+program
+  .name('algo-generate')
+  .description('Generate Python code from extracted algorithm steps')
+  .action(async () => {
+    console.log(chalk.blue.bold('╔════════════════════════════════════════╗'));
+    console.log(chalk.blue.bold('║    AlgoMath - Generate Algorithm       ║'));
+    console.log(chalk.blue.bold('╚════════════════════════════════════════╝'));
+    console.log();
+
+    try {
+      const spinner = ora('Generating code...').start();
+
+      const pythonScript = path.join(__dirname, '..', 'src', 'cli', 'cli_entry.py');
+      const result = await runPython(pythonScript, ['generate']);
+      
+      spinner.succeed('Code generation complete!');
+      
+      const output = JSON.parse(result);
+      displayResult(output);
+
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+function runPython(script, args) {
+  return new Promise((resolve, reject) => {
+    const python = spawn('python3', [script, ...args], {
+      cwd: path.join(__dirname, '..')
+    });
+
+    let output = '';
+    let error = '';
+
+    python.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    python.stderr.on('data', (data) => {
+      error += data.toString();
+    });
+
+    python.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(error || `Python process exited with code ${code}`));
+      } else {
+        resolve(output);
+      }
+    });
+  });
+}
+
+function displayResult(output) {
+  console.log();
+  
+  if (output.status === 'success') {
+    console.log(chalk.green.bold('✓ Code generated successfully'));
+    console.log();
+    console.log(chalk.cyan('Generated:'), output.files?.length || 0, 'file(s)');
+    console.log(chalk.cyan('Algorithm:'), output.algorithm || '(unnamed)');
+    console.log();
+    
+    if (output.next_steps) {
+      console.log(chalk.gray('Next steps:'));
+      output.next_steps.forEach(step => {
+        console.log(chalk.gray(`  • ${step}`));
+      });
+    }
+  } else {
+    console.log(chalk.yellow('⚠'), output.message);
+    if (output.next_steps) {
+      console.log();
+      console.log(chalk.gray('Next steps:'));
+      output.next_steps.forEach(step => {
+        console.log(chalk.gray(`  • ${step}`));
+      });
+    }
+  }
+  
+  console.log();
+  console.log(chalk.blue('Use /algo-run to execute the generated code'));
+}
+
+program.parse();

package/bin/algo-help.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * algo-help command
+ * 
+ * Usage: npx algomath help
+ */
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length > 0) {
+    showCommandHelp(args[0]);
+  } else {
+    showGeneralHelp();
+  }
+}
+
+function showGeneralHelp() {
+  console.log('\n╔════════════════════════════════════════════════════╗');
+  console.log('║ AlgoMath Framework ║');
+  console.log('║ Mathematical Algorithm Extraction & Code ║');
+  console.log('╚════════════════════════════════════════════════════╝\n');
+
+  console.log('DESCRIPTION');
+  console.log('  Extract algorithms from papers/text and generate executable code.\n');
+
+  console.log('COMMANDS');
+  console.log('  /algo-extract <file>  Extract algorithm from PDF or text file');
+  console.log('  /algo-generate        Generate Python code from extracted algorithm');
+  console.log('  /algo-run             Execute the generated code');
+  console.log('  /algo-verify          Verify results and check correctness');
+  console.log('  /algo-status          Check system status');
+  console.log('  /algo-list            List saved algorithms');
+  console.log('  /algo-help            Show this help\n');
+
+  console.log('WORKFLOW');
+  console.log('  PDF/Text → Extract → Generate → Run → Verify\n');
+
+  console.log('EXAMPLES');
+  console.log('  /algo-extract paper.pdf');
+  console.log('  /algo-extract algorithm.txt --steps 5 --auto\n');
+  console.log('  /algo-generate --name quicksort');
+  console.log('  /algo-run --input "[3,1,4,1,5]"\n');
+  console.log('  /algo-verify --steps\n');
+
+  console.log('FOR MORE INFORMATION');
+  console.log('  /algo-help <command>  - Show help for a specific command\n');
+}
+
+function showCommandHelp(command) {
+  const helpTexts = {
+    extract: `algo-extract <file>
+  
+Extract algorithm from PDF or text file.
+
+Arguments:
+  file              Path to PDF or text file
+
+Options:
+  --steps N         Number of steps (default: auto-detect)
+  --auto            Auto mode (skip review points)
+  --name NAME       Algorithm name
+
+Examples:
+  /algo-extract paper.pdf
+  /algo-extract algo.txt --steps 10 --name mergesort`,
+
+    generate: `algo-generate
+  
+Generate Python code from extracted algorithm.
+
+Options:
+  --name NAME       Algorithm name
+  --template TYPE   Template: standard, scientific, educational (default: standard)
+  --output FILE     Output file (default: auto-generated)
+
+Examples:
+  /algo-generate
+  /algo-generate --name quicksort --template educational`,
+
+    run: `algo-run
+  
+Execute the generated code.
+
+Options:
+  --input DATA      Input data for the algorithm
+  --file FILE       Read input from file
+  --timeout N       Timeout in seconds (default: 30)
+
+Examples:
+  /algo-run
+  /algo-run --input "[5, 2, 8, 1, 9]"
+  /algo-run --file input.json`,
+
+    verify: `algo-verify
+  
+Verify algorithm correctness and results.
+
+Options:
+  --steps           Verify each step
+  --explain         Explain the algorithm
+  --edge-cases      Check edge cases
+  --compare FILE    Compare with reference implementation
+
+Examples:
+  /algo-verify
+  /algo-verify --steps --explain`,
+
+    status: `algo-status
+  
+Check AlgoMath installation status.`,
+
+    list: `algo-list
+  
+List saved algorithms.`,
+
+    help: `algo-help [command]
+  
+Show help information.
+
+Examples:
+  /algo-help
+  /algo-help extract`
+  };
+
+  const cmd = command.replace(/^algo-/, '').replace(/^\//, '');
+  if (helpTexts[cmd]) {
+    console.log('\n' + helpTexts[cmd] + '\n');
+  } else {
+    console.log(`\nUnknown command: ${command}\n`);
+    console.log('Available commands: extract, generate, run, verify, status, list, help\n');
+  }
+}
+
+main();

package/bin/algo-list.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * algo-list command
+ * 
+ * Usage: npx algomath list
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+async function main() {
+  console.log('\n╔════════════════════════════════════════════════════╗');
+  console.log('║ Saved Algorithms ║');
+  console.log('╚════════════════════════════════════════════════════╝\n');
+
+  const homeDir = require('os').homedir();
+  const algorithmsDir = path.join(homeDir, '.algomath', 'algorithms');
+  
+  if (!fs.existsSync(algorithmsDir)) {
+    console.log('No algorithms found.\n');
+    console.log('Try extracting your first algorithm:');
+    console.log('  /algo-extract path/to/paper.pdf\n');
+    process.exit(0);
+  }
+  
+  const algorithms = fs.readdirSync(algorithmsDir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      const filepath = path.join(algorithmsDir, f);
+      const data = JSON.parse(fs.readFileSync(filepath, 'utf8'));
+      return {
+        name: f.replace('.json', ''),
+        created: data.created || 'Unknown',
+        steps: data.steps ? data.steps.length : 0
+      };
+    });
+  
+  if (algorithms.length === 0) {
+    console.log('No algorithms found.\n');
+    console.log('Try extracting your first algorithm:');
+    console.log('  /algo-extract path/to/paper.pdf\n');
+  } else {
+    console.log(`Found ${algorithms.length} algorithm(s):\n`);
+    algorithms.forEach(algo => {
+      console.log(`  ${algo.name}`);
+      console.log(`    Created: ${algo.created}`);
+      console.log(`    Steps: ${algo.steps}`);
+      console.log();
+    });
+    console.log('To load an algorithm:');
+    console.log('  /algo-run <algorithm-name>\n');
+  }
+}
+
+main();