{ "meta": { "document_type": "Product Requirements Document", "version": "1.0.0", "project_codename": "SymClaw", "tagline": "Open-Source Symbolic Computing for the Agentic Age", "created": "2026-02-12", "authors": ["Omar (Founder/CEO, HPC-AI Platform)"], "status": "Draft — Architecture Review" }, "executive_summary": { "vision": "Build an open-source, high-performance symbolic mathematics engine in Rust that integrates with OpenClaw to deliver an AI-agentic, multi-channel scientific computing assistant — a Mathematica-class system that scientists can deploy on commodity hardware with one command.", "problem_statement": [ "Mathematica is closed-source, expensive ($395/yr student, $2,495 perpetual), and locked to Wolfram's cloud.", "Existing open-source CAS tools (SymPy, Maxima, SageMath) lack modern agentic AI integration and are not performance-optimized for edge/embedded deployment.", "Scientists and researchers need a conversational, always-available math assistant that runs on their own infrastructure — from a Raspberry Pi cluster to a GPU workstation.", "No existing system combines symbolic computing + equality saturation optimization + agentic AI routing + multi-channel delivery (WhatsApp, Telegram, iOS, web)." ], "target_outcome": "A researcher messages 'derive the Navier-Stokes energy functional with respect to velocity field u' on Telegram and receives the symbolic result, LaTeX rendering, and an interactive parameter explorer pushed to their phone's Canvas — all computed on their own hardware." }, "stakeholders": { "primary_users": [ { "persona": "Graduate Researcher (Physics/Math/Engineering)", "pain_points": ["Can't afford Mathematica", "Needs CAS while away from desk", "Wants reproducible, version-controlled computations"], "value_prop": "Free, self-hosted CAS accessible from any messaging app with persistent memory" }, { "persona": "Home Lab Hobbyist / Developer", "pain_points": ["Wants to run compute on own hardware", "Interested in Rust/WASM performance", "Enjoys tinkering with infrastructure"], "value_prop": "One-command deployment on Pi cluster with Tailscale remote access" }, { "persona": "Open Science Lab / University Group", "pain_points": ["Budget constraints", "Need collaboration features", "Vendor lock-in concerns"], "value_prop": "MIT-licensed, self-hosted, reproducible research infrastructure" } ], "secondary_users": [ "K-12 / undergraduate students learning calculus and algebra", "Data scientists needing symbolic preprocessing before ML pipelines", "Engineers doing control theory / signal processing work" ] }, "architecture": { "overview": "Three-layer architecture: Rust Symbolic Engine (compute) → OpenClaw Skill Bridge (agentic orchestration) → Multi-Channel Delivery (user surface)", "layers": [ { "name": "Layer 1: symclaw-core (Rust Crate)", "responsibility": "Deterministic symbolic evaluation, simplification, differentiation, integration, linear algebra, and equation solving", "technology": { "language": "Rust (edition 2024)", "key_crates": [ {"name": "egg", "version": "0.10+", "purpose": "E-graph equality saturation for optimal simplification"}, {"name": "proptest", "version": "1.x", "purpose": "Property-based testing for mathematical correctness"}, {"name": "serde", "version": "1.x", "purpose": "Serialization for AST interchange"}, {"name": "wasm-bindgen", "version": "0.2+", "purpose": "WASM compilation target for browser/mobile"}, {"name": "rayon", "version": "1.x", "purpose": "Data parallelism for cluster computation"}, {"name": "num", "version": "0.4+", "purpose": "Arbitrary precision arithmetic"}, {"name": "nalgebra", "version": "0.33+", "purpose": "Linear algebra operations"}, {"name": "latex-rs or custom", "version": "latest", "purpose": "LaTeX output rendering"} ], "compile_targets": [ "x86_64-unknown-linux-gnu (primary — Pi cluster, servers)", "aarch64-unknown-linux-gnu (Raspberry Pi 4/5 native)", "wasm32-unknown-unknown (browser, OpenClaw Canvas)", "x86_64-apple-darwin / aarch64-apple-darwin (macOS dev)" ] }, "components": { "ast": { "description": "Core expression tree representation", "design": { "enum_name": "Expr", "variants": [ "Num(Rational) — exact rational arithmetic", "Float(f64) — IEEE 754 when exact isn't needed", "Symbol(String) — named variables", "Add(Vec>) — n-ary addition (flattened)", "Mul(Vec>) — n-ary multiplication (flattened)", "Pow(Arc, Arc) — exponentiation", "Func(FuncName, Vec>) — sin, cos, log, exp, etc.", "Derivative(Arc, Symbol, usize) — d^n/dx^n", "Integral(Arc, Symbol, Option<(Arc, Arc)>) — definite/indefinite", "Matrix(Vec>>) — symbolic matrices", "Eq(Arc, Arc) — equations", "Set(BTreeSet>) — solution sets", "Piecewise(Vec<(Arc, Arc)>) — conditional expressions", "Sum(Arc, Symbol, Arc, Arc) — sigma notation", "Product(Arc, Symbol, Arc, Arc) — pi notation", "Limit(Arc, Symbol, Arc, LimitDirection) — limits", "Tensor(TensorData) — future: tensor algebra" ], "notes": [ "Use Arc (not Box) for thread-safe sharing across rayon parallel iterators and cluster nodes", "Implement Hash and Eq for expression deduplication / e-graph integration", "Canonical ordering: sort commutative operands for deterministic comparison", "Consider interning symbols via string interner crate for memory efficiency" ] } }, "rewriter": { "description": "Rule-based symbolic transformation engine", "subsystems": [ { "name": "Pattern Matcher", "approach": "Rust match arms + custom pattern DSL for rewrite rules", "example_rules": [ "Derivative(Sin(x), x) → Cos(x)", "Derivative(Cos(x), x) → Neg(Sin(x))", "Derivative(Pow(x, Num(n)), x) → Mul(Num(n), Pow(x, Num(n-1)))", "Derivative(Mul(f, g), x) → Add(Mul(Derivative(f, x), g), Mul(f, Derivative(g, x)))", "Add(x, Num(0)) → x", "Mul(x, Num(1)) → x", "Mul(x, Num(0)) → Num(0)", "Pow(x, Num(0)) → Num(1)", "Pow(x, Num(1)) → x", "Log(Exp(x)) → x", "Exp(Log(x)) → x" ] }, { "name": "Equality Saturation Engine (egg integration)", "approach": "Define Expr as an egg Language, run equality saturation with cost-based extraction", "benefits": [ "Finds globally optimal simplification, not just greedy local rewrites", "Handles commutative/associative rewriting without combinatorial explosion", "Enables 'explain' mode — shows step-by-step derivation to user" ], "implementation_notes": [ "Define custom CostFunction that prefers: constants > symbols > simple ops > complex ops", "Implement ConstantFolding as an e-class Analysis", "Set iteration limits and e-graph size limits to prevent runaway on complex expressions", "Use egg's explain API to generate human-readable proof steps" ] }, { "name": "Simplifier", "stages": [ "1. Flatten: Convert nested Add/Mul to n-ary form", "2. Canonicalize: Sort operands, normalize signs", "3. Fold Constants: Evaluate purely numeric subexpressions", "4. Apply Algebraic Identities: trig, log, exponential identities", "5. Equality Saturation: Run egg for global optimization", "6. Extract: Pull out the lowest-cost equivalent expression" ] } ] }, "solver": { "description": "Equation solving and root finding", "capabilities": [ "Polynomial root finding (quadratic formula, cubic/quartic via Cardano/Ferrari)", "System of linear equations (Gaussian elimination on symbolic matrices)", "Transcendental equation solving (Newton-Raphson with symbolic Jacobian)", "Inequality solving and interval arithmetic", "ODE solving (separable, linear first-order, second-order constant coefficient)" ] }, "calculus": { "description": "Differentiation, integration, limits, series", "capabilities": [ "Symbolic differentiation (chain rule, product rule, quotient rule, implicit diff)", "Symbolic integration (table lookup, substitution, integration by parts, partial fractions)", "Taylor/Maclaurin series expansion", "Limits (L'Hôpital's rule, squeeze theorem patterns)", "Multivariate calculus (gradient, divergence, curl, Laplacian)" ] }, "linear_algebra": { "description": "Symbolic matrix operations", "capabilities": [ "Determinant (Leibniz formula for small, LU for large)", "Eigenvalue/eigenvector computation", "Matrix inversion, transpose, trace", "Characteristic polynomial", "SVD (symbolic where tractable, numeric fallback)" ] }, "output": { "formats": [ {"name": "LaTeX", "purpose": "Rendering in Canvas, PDF generation, Jupyter"}, {"name": "MathML", "purpose": "Web accessibility, browser rendering"}, {"name": "ASCII", "purpose": "Terminal/CLI output, Telegram messages"}, {"name": "JSON AST", "purpose": "Programmatic consumption, inter-process"}, {"name": "Wolfram Language", "purpose": "Interop with existing Mathematica users (stretch goal)"}, {"name": "Python/SymPy", "purpose": "Export to Python ecosystem"} ] }, "parser": { "description": "Input expression parsing", "formats": [ "Natural language (via LLM preprocessing in OpenClaw layer): 'derive x squared' → Derivative(Pow(x, 2), x)", "Infix notation: 'd/dx(x^2 + 3*x)'", "S-expression: (derivative (+ (pow x 2) (* 3 x)) x)", "LaTeX input: '\\frac{d}{dx}(x^2 + 3x)'" ], "implementation": "Use nom or pest crate for parser combinators" } } }, { "name": "Layer 2: symclaw-openclaw (OpenClaw Skill)", "responsibility": "Bridge between the Rust engine and OpenClaw's agentic framework — NL intent parsing, tool invocation, visualization, and session management", "technology": { "runtime": "Node.js (OpenClaw host process) calling Rust engine via WASM or subprocess RPC", "interop_options": [ { "name": "WASM (preferred for single-node)", "approach": "Compile symclaw-core to WASM, load via @aspect-build/aspect or wasm-pack, call from OpenClaw skill JS", "pros": "Zero-copy, in-process, fast startup, works in browser Canvas", "cons": "WASM limitations (no threads without SharedArrayBuffer, memory limits)" }, { "name": "Subprocess RPC (preferred for cluster)", "approach": "Run symclaw-core as a native binary, communicate via JSON-RPC over stdin/stdout or Unix socket", "pros": "Full Rust performance, threading, GPU access, can distribute across Pi cluster", "cons": "IPC overhead, process management complexity" }, { "name": "HTTP Microservice (optional)", "approach": "Run symclaw-core as an Axum/Actix web server, OpenClaw skill calls via HTTP", "pros": "Language-agnostic, easy to scale, standard tooling", "cons": "Network overhead, another process to manage" } ] }, "components": { "skill_definition": { "file": "SKILL.md", "frontmatter": { "name": "symclaw", "description": "Symbolic mathematics engine — differentiation, integration, simplification, equation solving, plotting, and interactive parameter exploration", "metadata": { "openclaw": { "requires": { "bins": ["symclaw-engine"], "env": [], "config": [] }, "primaryEnv": null } } }, "capabilities_exposed": [ "/math — Evaluate/simplify a mathematical expression", "/derive wrt — Symbolic differentiation", "/integrate wrt — Symbolic integration", "/solve for — Solve equations", "/plot [range] — Generate plot and push to Canvas", "/manipulate — Interactive parameter exploration on Canvas", "/latex — Render expression as LaTeX", "/explain — Show step-by-step simplification with egg proofs", "/matrix — Matrix operations", "/series about order — Taylor series expansion" ] }, "tool_functions": [ { "name": "math_eval", "description": "Core evaluation — parse input, run through engine, return result + LaTeX", "input": {"expression": "string", "output_format": "latex|ascii|json|mathml"}, "output": {"result": "string", "latex": "string", "steps": "string[]", "errors": "string[]"} }, { "name": "math_plot", "description": "Generate plot data from symbolic expression", "input": {"expression": "string", "variable": "string", "range": "[number, number]", "samples": "number"}, "output": {"plot_data": "{ x: number[], y: number[] }", "svg": "string", "canvas_html": "string"} }, { "name": "math_manipulate", "description": "Push interactive parameter explorer to Canvas/mobile node", "input": {"expression": "string", "parameters": [{"name": "string", "min": "number", "max": "number", "step": "number", "default": "number"}]}, "output": {"canvas_payload": "A2UI JSONL", "surface_id": "string"} }, { "name": "math_explain", "description": "Show derivation steps using egg's explain API", "input": {"expression": "string", "target": "string (optional — what to simplify to)"}, "output": {"steps": [{"rule": "string", "before": "string", "after": "string"}], "latex_steps": "string"} } ], "nlp_intent_mapping": { "description": "Map natural language math requests to engine calls. OpenClaw's LLM handles this, but the SKILL.md provides structured examples.", "examples": [ {"input": "What's the derivative of sin(x^2)?", "tool": "math_eval", "expression": "d/dx(sin(x^2))"}, {"input": "Simplify (x^2 - 1) / (x - 1)", "tool": "math_eval", "expression": "simplify((x^2 - 1) / (x - 1))"}, {"input": "Solve x^2 + 5x + 6 = 0", "tool": "math_eval", "expression": "solve(x^2 + 5*x + 6 = 0, x)"}, {"input": "Plot sin(x) from -pi to pi", "tool": "math_plot", "expression": "sin(x)", "range": [-3.14159, 3.14159]}, {"input": "Show me how x^3 - 3x^2 + 3x - 1 simplifies", "tool": "math_explain", "expression": "x^3 - 3*x^2 + 3*x - 1"}, {"input": "Let me explore how a affects a*sin(b*x)", "tool": "math_manipulate", "expression": "a*sin(b*x)"} ] }, "canvas_integration": { "description": "A2UI-based interactive math surfaces", "surfaces": [ { "name": "Scientist's Dashboard", "components": [ "Expression input with LaTeX preview", "Result display with step-by-step expansion", "Interactive 2D/3D plot (using Plotly.js or D3 in Canvas)", "Parameter sliders (Manipulate mode)", "History sidebar with previous computations", "Export buttons (PDF, LaTeX, Python)" ] }, { "name": "Manipulate Surface", "components": [ "Dynamic sliders for each parameter", "Real-time plot update as sliders move", "Expression display showing current parameter values", "Snapshot button to capture current state" ], "implementation": "A2UI JSONL pushes Slider + Plot components; Canvas JS calls back to symclaw-core WASM for re-evaluation on slider change" } ] }, "session_management": { "description": "Persist computation state across messages", "approach": [ "Use OpenClaw's JSONL transcript for audit trail of all computations", "Store named expressions in MEMORY.md: 'User defined f(x) = x^2 + 3x - 7'", "Support 'assume' declarations: 'Assume x > 0' persists in session context", "Variable bindings carry across messages within a session" ] } } }, { "name": "Layer 3: symclaw-infra (Deployment)", "responsibility": "One-command deployment, cluster orchestration, remote access", "components": { "docker": { "images": [ { "name": "symclaw-engine", "base": "rust:slim-bookworm (build) → debian:bookworm-slim (runtime)", "contents": "Compiled symclaw-core binary + CLI", "size_target": "< 50MB" }, { "name": "symclaw-gateway", "base": "node:22-slim", "contents": "OpenClaw Gateway + symclaw skill + WASM module", "size_target": "< 200MB" } ], "compose": { "services": { "gateway": { "image": "symclaw-gateway", "ports": ["18789:18789"], "volumes": ["~/.openclaw:/root/.openclaw", "~/.symclaw:/root/.symclaw"], "environment": ["ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}"] }, "engine": { "image": "symclaw-engine", "deploy": { "replicas": "auto (matches available cores)", "resources": {"limits": {"cpus": "4", "memory": "2G"}} } }, "webchat": { "image": "symclaw-gateway", "command": "openclaw webchat", "ports": ["3000:3000"] } } } }, "nix": { "flake": { "inputs": ["nixpkgs", "rust-overlay", "flake-utils"], "outputs": { "packages": ["symclaw-core", "symclaw-cli", "symclaw-wasm"], "devShells": ["Full development environment with Rust, Node, cargo-watch, wasm-pack"], "nixosModules": ["systemd service for Gateway + Engine"] } }, "benefits": "Reproducible builds, declarative deployment, NixOS integration for Pi cluster" }, "raspberry_pi_cluster": { "topology": { "control_node": "Pi 5 (8GB) — runs OpenClaw Gateway + Tailscale", "compute_nodes": "Pi 4/5 (4-8GB each) — run symclaw-engine instances", "networking": "Tailscale mesh or local VLAN", "load_balancing": "Round-robin via OpenClaw multi-agent routing or custom dispatcher" }, "deployment": { "approach": "Nix flakes + deploy-rs for fleet management", "one_command": "symclaw deploy --cluster pi@192.168.1.{10..14}" }, "performance_notes": [ "Pi 5 ARM Cortex-A76 handles typical symbolic algebra in < 100ms", "Equality saturation on complex expressions may need 2-5 seconds — use async/streaming response", "For heavy computations, route to x86 workstation (RTX 5090 node) via Tailscale", "WASM fallback allows computation in browser if all cluster nodes are busy" ] }, "tailscale": { "integration": "OpenClaw has built-in Tailscale Serve/Funnel support", "modes": [ "Serve (tailnet-only): Access from any device on your Tailscale network", "Funnel (public, auth-gated): Access from anywhere with password protection" ], "use_cases": [ "Access 'Science Assistant' from phone while at conference", "Share computation results with collaborator on same tailnet", "Remote development — SSH into Pi cluster from anywhere" ] }, "gpu_acceleration": { "description": "Optional GPU offload for numeric-heavy operations", "targets": [ "CUDA (RTX 5090 in Omar's homelab) — numeric linear algebra, ODE solvers", "Vulkan compute (cross-platform fallback)", "WebGPU (browser Canvas for client-side plotting)" ], "integration": "Feature-gated in symclaw-core: cargo build --features cuda" } } } ] }, "implementation_plan": { "methodology": "Iterative development with 2-week sprints, each ending in a deployable artifact", "phases": [ { "phase": "Phase 0: Foundation", "duration": "2 weeks", "objective": "Project scaffolding, CI/CD, development environment", "deliverables": [ { "id": "P0.1", "task": "Initialize Rust workspace with cargo workspaces", "details": [ "Create workspace: symclaw/ with members: core/, cli/, wasm/, openclaw-skill/", "Set up Cargo.toml with shared dependencies and feature flags", "Configure clippy, rustfmt, deny.toml for lint/audit" ] }, { "id": "P0.2", "task": "CI/CD pipeline", "details": [ "GitHub Actions: test (x86 + aarch64 cross), clippy, fmt, build WASM, build Docker images", "Nightly: property-based test suite with proptest (longer run times)", "Release: cargo-dist for binary releases, wasm-pack publish, Docker Hub push" ] }, { "id": "P0.3", "task": "Development environment", "details": [ "Nix flake with devShell: Rust nightly, wasm-pack, Node 22, cargo-watch, mold linker", "VS Code workspace with rust-analyzer, WASM debugging config", ".envrc for direnv integration" ] }, { "id": "P0.4", "task": "Documentation skeleton", "details": [ "mdBook setup for user-facing docs", "Architecture Decision Records (ADR) directory", "CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE (MIT + Apache 2.0 dual)" ] } ], "exit_criteria": "cargo test passes on x86 and aarch64, WASM builds, CI green" }, { "phase": "Phase 1: Engine Core — Arithmetic & Algebra", "duration": "4 weeks (Sprints 1-2)", "objective": "Core AST, parser, simplifier, and basic algebra", "sprints": [ { "sprint": "Sprint 1 (Weeks 3-4)", "deliverables": [ { "id": "P1.1", "task": "Expr AST implementation", "details": [ "Implement Expr enum with Num, Float, Symbol, Add, Mul, Pow, Func, Neg", "Implement Display (pretty-print), Debug, Hash, Eq, PartialEq, Clone", "Arc-wrapped recursive types with From/Into conversions for ergonomics", "Canonical ordering for commutative operations" ], "acceptance": "Can construct and display: 3*x^2 + 2*x - 7" }, { "id": "P1.2", "task": "Parser (infix notation)", "details": [ "Implement Pratt parser or use pest/nom for: numbers, symbols, +, -, *, /, ^, (, ), function calls", "Operator precedence: ^(right-assoc) > unary- > */÷ > +-", "Implicit multiplication: 2x, 3(x+1), xy", "Built-in constants: pi, e, i" ], "acceptance": "parse('3*x^2 + sin(2*pi*x) - 1/2') returns correct AST" }, { "id": "P1.3", "task": "Constant folding & basic simplification", "details": [ "Evaluate numeric subexpressions: 2 + 3 → 5, 6/4 → 3/2", "Identity rules: x + 0, x * 1, x * 0, x^0, x^1", "Flatten nested Add/Mul, combine like terms" ], "acceptance": "simplify('x + 0 + 3 + 2') returns 'x + 5'" } ] }, { "sprint": "Sprint 2 (Weeks 5-6)", "deliverables": [ { "id": "P1.4", "task": "Egg integration — equality saturation simplifier", "details": [ "Define Expr as egg::Language (implement Language trait)", "Implement core rewrite rules as egg::Rewrite", "Implement ConstantFolding analysis", "Cost function: prefer fewer nodes, lower operation complexity", "Runner with iteration limit (100) and node limit (10000)" ], "acceptance": "egg simplifies (x^2 - 1)/(x - 1) to (x + 1)" }, { "id": "P1.5", "task": "LaTeX output", "details": [ "Implement to_latex() for all Expr variants", "Proper fraction rendering: \\frac{a}{b}", "Function rendering: \\sin, \\cos, \\ln, \\sqrt", "Matrix rendering: \\begin{pmatrix}...\\end{pmatrix}" ], "acceptance": "to_latex(Pow(x, Div(1, 2))) returns '\\sqrt{x}'" }, { "id": "P1.6", "task": "CLI (symclaw-cli)", "details": [ "REPL with readline support (rustyline)", "Commands: simplify, eval, latex, quit", "History, tab completion for functions", "Pipe support: echo 'x^2 + 2*x + 1' | symclaw simplify" ], "acceptance": "Interactive REPL that simplifies expressions and shows LaTeX" }, { "id": "P1.7", "task": "Property-based test suite", "details": [ "proptest strategies for generating random Expr trees", "Invariant: simplify(e).eval(x=random) ≈ e.eval(x=random) for all x", "Invariant: parse(display(e)) == e (round-trip)", "Invariant: simplify(simplify(e)) == simplify(e) (idempotence)" ], "acceptance": "1000+ property tests pass with no numerical drift > 1e-10" } ] } ], "exit_criteria": "CLI can parse, simplify, and LaTeX-render polynomial and trigonometric expressions" }, { "phase": "Phase 2: Engine Core — Calculus & Solving", "duration": "4 weeks (Sprints 3-4)", "objective": "Differentiation, integration, equation solving, series", "sprints": [ { "sprint": "Sprint 3 (Weeks 7-8)", "deliverables": [ { "id": "P2.1", "task": "Symbolic differentiation", "details": [ "Power rule, constant rule, sum rule", "Product rule, quotient rule, chain rule", "Trig derivatives: sin, cos, tan, arcsin, arccos, arctan", "Exponential/log derivatives", "Higher-order derivatives: d^n/dx^n", "Partial derivatives for multivariate expressions" ], "acceptance": "d/dx(sin(x^2)) correctly returns 2*x*cos(x^2)" }, { "id": "P2.2", "task": "Equation solver", "details": [ "Linear equations: ax + b = 0", "Quadratic formula: ax^2 + bx + c = 0 (exact roots, complex support)", "Polynomial factoring (rational root theorem, synthetic division)", "Systems of linear equations (symbolic Gaussian elimination)" ], "acceptance": "solve(x^2 - 5*x + 6 = 0) returns {x = 2, x = 3}" } ] }, { "sprint": "Sprint 4 (Weeks 9-10)", "deliverables": [ { "id": "P2.3", "task": "Symbolic integration", "details": [ "Power rule integration", "Trig integrals (table lookup)", "Substitution (u-sub with pattern matching)", "Integration by parts (LIATE heuristic)", "Partial fractions for rational functions", "Definite integrals with limit evaluation" ], "acceptance": "integrate(x*exp(x), x) returns x*exp(x) - exp(x) + C" }, { "id": "P2.4", "task": "Series expansion", "details": [ "Taylor series about a point", "Maclaurin series (Taylor about 0)", "Order control: expand to n terms", "Remainder estimation" ], "acceptance": "taylor(sin(x), x, 0, 5) returns x - x^3/6 + x^5/120" }, { "id": "P2.5", "task": "Limits", "details": [ "Direct substitution", "L'Hôpital's rule for 0/0 and ∞/∞", "One-sided limits", "Limits at infinity" ], "acceptance": "limit(sin(x)/x, x, 0) returns 1" }, { "id": "P2.6", "task": "WASM compilation & test", "details": [ "Ensure all Phase 1-2 code compiles to wasm32-unknown-unknown", "wasm-bindgen exports for: parse, simplify, differentiate, integrate, solve, to_latex", "Size budget: < 2MB gzipped WASM", "Browser test harness with wasm-pack test --headless --chrome" ], "acceptance": "WASM module loads in browser, solves quadratic equation in < 50ms" } ] } ], "exit_criteria": "CLI handles calculus homework-level problems correctly; WASM compiles and runs in browser" }, { "phase": "Phase 3: OpenClaw Integration", "duration": "3 weeks (Sprints 5-6)", "objective": "Fully functional OpenClaw skill with Canvas visualization", "sprints": [ { "sprint": "Sprint 5 (Weeks 11-12)", "deliverables": [ { "id": "P3.1", "task": "SKILL.md authoring", "details": [ "Write comprehensive SKILL.md with YAML frontmatter", "Document all commands with examples", "Gate on symclaw-engine binary or WASM availability", "Include install instructions in metadata.openclaw.requires" ], "acceptance": "OpenClaw loads skill, shows /math in autocomplete" }, { "id": "P3.2", "task": "Tool implementation (Node.js wrapper)", "details": [ "Implement math_eval, math_plot, math_explain tool functions", "WASM loading: dynamic import of symclaw.wasm", "Subprocess fallback: spawn symclaw-cli with JSON I/O", "Error handling: parse errors, computation timeouts, overflow", "Streaming for long computations: send partial results" ], "acceptance": "Telegram message 'derive sin(x^2)' returns '2x·cos(x²)' + LaTeX image" }, { "id": "P3.3", "task": "LaTeX rendering to image", "details": [ "Use MathJax or KaTeX server-side rendering to SVG/PNG", "Embed in Telegram/WhatsApp messages as image attachment", "Fallback: ASCII art for channels that don't support images" ], "acceptance": "WhatsApp user sees beautifully rendered math formulas" } ] }, { "sprint": "Sprint 6 (Week 13)", "deliverables": [ { "id": "P3.4", "task": "Canvas — Scientist's Dashboard", "details": [ "HTML/CSS/JS Canvas surface with: input field, result display, plot area", "Plot rendering using Plotly.js or Chart.js loaded from CDN", "LaTeX rendering in-browser via KaTeX", "A2UI JSONL push for dynamic updates", "Responsive layout for mobile (iOS/Android node Canvas)" ], "acceptance": "User asks to plot sin(x); Canvas shows interactive plot on phone" }, { "id": "P3.5", "task": "Canvas — Manipulate mode", "details": [ "Parameter extraction from expression (detect free symbols not being plotted)", "A2UI Slider components pushed to Canvas", "Real-time re-evaluation: slider onChange triggers WASM recalculation in Canvas JS", "Plot updates at 30fps as slider moves" ], "acceptance": "User says 'manipulate a*sin(b*x)'; phone shows sliders for a, b with live plot" }, { "id": "P3.6", "task": "Session memory integration", "details": [ "Store defined functions in MEMORY.md: 'f(x) = x^2 + 3x - 7'", "Recall across messages: 'now differentiate f'", "Assumption tracking: 'assume x > 0' affects simplification", "Computation history: 'show last 5 results'" ], "acceptance": "Multi-turn conversation maintains mathematical context" } ] } ], "exit_criteria": "End-to-end flow: Telegram → OpenClaw → Engine → Canvas works for calculus problems" }, { "phase": "Phase 4: Infrastructure & Deployment", "duration": "2 weeks (Sprint 7)", "objective": "One-command deployment, cluster support, Tailscale, CI/CD for releases", "deliverables": [ { "id": "P4.1", "task": "Docker Compose stack", "details": [ "Multi-stage Dockerfile for symclaw-engine (Rust build → slim runtime)", "Dockerfile for symclaw-gateway (Node + OpenClaw + skill + WASM)", "docker-compose.yml with engine, gateway, webchat services", "Health checks, restart policies, resource limits", "ARM64 multi-arch builds for Raspberry Pi" ], "acceptance": "docker compose up -d brings full stack on x86 and ARM" }, { "id": "P4.2", "task": "Nix flake", "details": [ "flake.nix with packages, devShells, nixosModules", "Cross-compilation to aarch64 via crane or naersk", "NixOS module: services.symclaw.enable = true", "Cachix binary cache for pre-built artifacts" ], "acceptance": "nix run github:symclaw/symclaw starts the full stack" }, { "id": "P4.3", "task": "Pi cluster deployment tooling", "details": [ "Ansible or deploy-rs playbook for fleet deployment", "Auto-discovery of compute nodes on local network", "Load balancing: dispatch heavy computations to least-loaded node", "Monitoring: Prometheus metrics from engine (eval latency, memory, e-graph size)" ], "acceptance": "symclaw deploy --cluster deploys to 4 Pi nodes in < 5 minutes" }, { "id": "P4.4", "task": "Tailscale integration", "details": [ "Document OpenClaw's built-in Tailscale Serve/Funnel config", "Provide symclaw-specific tailscale config snippet", "Test: access from phone on different network" ], "acceptance": "Access Scientist's Dashboard from phone on cellular while Gateway runs on home Pi" }, { "id": "P4.5", "task": "openclaw onboard integration", "details": [ "Publish symclaw skill to ClawHub", "Support openclaw onboard wizard extension: auto-detect Rust toolchain, offer to install engine", "One-command: openclaw skill install symclaw" ], "acceptance": "New user can install and use SymClaw in < 10 minutes" } ], "exit_criteria": "One-command install works on macOS, Linux (x86 + ARM), and Docker" }, { "phase": "Phase 5: Polish, Testing & Alpha Release", "duration": "3 weeks (Sprints 8-9)", "objective": "Comprehensive testing, documentation, community prep, V0.1 Alpha release", "deliverables": [ { "id": "P5.1", "task": "Comprehensive test suite", "details": { "unit_tests": [ "Every rewrite rule tested individually with known input/output", "Parser round-trip: parse(display(parse(input))) == parse(input)", "LaTeX output matches expected strings", "Edge cases: division by zero, complex numbers, very large/small numbers" ], "property_tests": [ "Simplification preserves numerical value (10,000+ random expressions)", "Differentiation + integration round-trip: ∫(d/dx f(x))dx ≈ f(x) + C", "Idempotence: simplify(simplify(e)) == simplify(e)", "Commutativity: simplify(a + b) == simplify(b + a)" ], "integration_tests": [ "OpenClaw message → engine → response pipeline", "Telegram bot receives message, returns correct math", "Canvas A2UI push renders correctly in browser test", "Multi-turn session: define function, then differentiate it" ], "stress_tests": [ "1000 concurrent evaluations on Pi cluster", "E-graph explosion: expressions designed to stress equality saturation", "WASM memory limits: expressions that approach 4GB boundary", "Long-running integration: 24-hour continuous operation stability" ], "benchmark_suite": [ "Compare simplification speed with SymPy on standard benchmark set", "Measure e-graph size vs. simplification quality tradeoff", "WASM vs. native performance comparison", "Latency: message received → response sent (target: < 2 seconds for typical queries)" ] } }, { "id": "P5.2", "task": "Documentation", "details": [ "mdBook user guide: Getting Started, Tutorials, API Reference", "Architecture document with diagrams (Mermaid)", "OpenClaw skill README with screenshots and GIFs", "Video: 5-minute demo of end-to-end usage", "Comparison table: SymClaw vs. Mathematica vs. SymPy vs. Maxima" ] }, { "id": "P5.3", "task": "Community preparation", "details": [ "GitHub repo setup: issue templates, PR template, labels, milestones", "Discord server or Matrix room for community", "CONTRIBUTING.md with 'good first issues' labeled", "Blog post: 'Why We Built an Open-Source Mathematica in Rust'", "Hacker News / Reddit launch post draft" ] }, { "id": "P5.4", "task": "V0.1 Alpha release", "details": [ "GitHub Release with changelog", "crates.io publish: symclaw-core", "npm publish: @symclaw/openclaw-skill", "Docker Hub: symclaw/engine, symclaw/gateway", "ClawHub: symclaw skill listing" ] } ], "exit_criteria": "V0.1 Alpha: installable, documented, tested, with known-issues list" } ], "future_phases": [ { "phase": "Phase 6 (V0.5 Beta)", "features": [ "Linear algebra module (eigenvalues, SVD, Jordan form)", "ODE/PDE solvers", "Number theory (prime factorization, modular arithmetic)", "Graph theory / combinatorics module", "Jupyter kernel (symclaw as Jupyter backend)", "VS Code extension with inline LaTeX preview" ] }, { "phase": "Phase 7 (V1.0 Launch)", "features": [ "GPU-accelerated numeric fallback (CUDA via RustyTorch integration)", "Distributed computation across Clawbernetes cluster", "Collaborative notebooks (multi-user Canvas sessions)", "Wolfram Language import/export (migration path for Mathematica users)", "Publication-ready PDF generation (LaTeX → PDF pipeline)", "Integration with Omar's SLAI GPU scheduler for heavy workloads" ] }, { "phase": "Phase 8 (V2.0 — Science Platform)", "features": [ "Domain-specific modules: Physics (units, kinematics), Chemistry (stoichiometry), Biology (population models)", "ML integration: symbolic regression via RustyTorch", "Natural language theorem proving", "Real-time collaboration with CRDTs", "Marketplace for community-contributed rule sets and problem libraries" ] } ] }, "milestones": [ { "version": "V0.1 Alpha", "target_date": "Week 18 (T+18 weeks from start)", "deliverables": "Core Rust library + CLI + OpenClaw skill + Docker deployment", "audience": "Developers, Rust community, Home Lab hobbyists" }, { "version": "V0.5 Beta", "target_date": "T+30 weeks", "deliverables": "OpenClaw Skill + Canvas Dashboard + Manipulate + Pi cluster deployment", "audience": "Early adopters, power users, math enthusiasts" }, { "version": "V1.0 Launch", "target_date": "T+44 weeks", "deliverables": "One-click install, comprehensive docs, GPU support, Jupyter integration", "audience": "Universities, Open Science projects, research groups" } ], "risks_and_mitigations": [ { "risk": "Symbolic integration is an unsolved problem — many integrals have no closed form", "impact": "High", "probability": "Certain", "mitigation": "Implement Risch algorithm incrementally; provide numeric fallback with clear messaging; leverage LLM for heuristic suggestions; benchmark against SymPy's coverage as baseline" }, { "risk": "E-graph explosion on complex expressions leads to OOM or timeout", "impact": "High", "probability": "Medium", "mitigation": "Strict iteration limits (100), node count limits (10K), time budgets (5s); fallback to greedy simplification; profile with dhat/heaptrack" }, { "risk": "WASM performance insufficient for real-time Manipulate sliders", "impact": "Medium", "probability": "Low", "mitigation": "Pre-compile expression to fast numeric evaluator (JIT-like partial evaluation); cache WASM compilation; fall back to server-side evaluation with WebSocket streaming" }, { "risk": "OpenClaw API/skill format changes break integration", "impact": "Medium", "probability": "Medium", "mitigation": "Pin to specific OpenClaw version; abstract skill interface behind adapter layer; maintain CI that tests against OpenClaw's latest" }, { "risk": "Security: malicious expressions cause DoS (infinite loops, memory exhaustion)", "impact": "High", "probability": "Medium", "mitigation": "Sandboxed execution (Docker/WASM); expression complexity limits; timeout enforcement; OpenClaw's built-in sandboxing" }, { "risk": "Scope creep — trying to match Mathematica's 6,600 built-in functions", "impact": "High", "probability": "High", "mitigation": "Ruthlessly prioritize: calculus + algebra + linear algebra cover 80% of use cases; accept 'not yet implemented' gracefully; extensible architecture allows community contributions" }, { "risk": "Low adoption due to SymPy's established ecosystem", "impact": "Medium", "probability": "Medium", "mitigation": "Differentiate on: (1) performance (Rust >> Python), (2) agentic AI integration (unique), (3) edge deployment (WASM + Pi), (4) conversational interface (WhatsApp/Telegram)" } ], "success_metrics": { "alpha": { "correctness": "> 95% accuracy on MIT OCW calculus problem sets", "performance": "< 100ms for typical simplification on Pi 5, < 50ms on x86", "adoption": "100+ GitHub stars, 20+ alpha testers", "reliability": "< 1% crash rate over 1000 random expressions" }, "beta": { "correctness": "> 98% accuracy on undergraduate math curriculum", "performance": "< 2s end-to-end (message → rendered response) for 95th percentile", "adoption": "1000+ GitHub stars, 5+ university pilot deployments", "features": "Covers differential equations, linear algebra, series" }, "launch": { "correctness": "Parity with SymPy on core algebra/calculus; surpass on simplification quality (egg advantage)", "performance": "10x faster than SymPy on benchmark suite", "adoption": "5000+ GitHub stars, 50+ active contributors, 3+ university courses using SymClaw", "ecosystem": "20+ community-contributed rule sets on ClawHub" } }, "competitive_landscape": { "comparison": [ { "product": "Wolfram Mathematica", "strengths": "6,600 functions, 35+ years of development, Wolfram Alpha integration, professional support", "weaknesses": "Closed source, expensive ($395-$2,495), cloud-dependent, no agentic AI integration", "symclaw_advantage": "Open source, free, self-hosted, AI-native, runs on Pi" }, { "product": "SymPy (Python)", "strengths": "Mature, large community, Jupyter integration, extensive documentation", "weaknesses": "Python performance limitations, no agentic integration, no edge deployment", "symclaw_advantage": "10x+ faster (Rust), WASM browser deployment, OpenClaw integration, equality saturation" }, { "product": "SageMath", "strengths": "Comprehensive (wraps many backends), notebook interface", "weaknesses": "Heavy installation (GB+), slow startup, no mobile/messaging support", "symclaw_advantage": "Lightweight (< 50MB), instant startup, multi-channel (WhatsApp, Telegram, etc.)" }, { "product": "Maxima / GNU Octave", "strengths": "Free, established, good for specific domains", "weaknesses": "Dated interfaces, no modern AI integration, limited community growth", "symclaw_advantage": "Modern Rust codebase, AI-agentic, active community model, Canvas visualization" }, { "product": "ChatGPT / Claude (direct LLM math)", "strengths": "Natural language, accessible, broad knowledge", "weaknesses": "Non-deterministic, hallucinations on complex math, no persistent state, no symbolic guarantees", "symclaw_advantage": "Deterministic symbolic engine guarantees correctness; LLM handles NL intent, engine handles computation" } ] }, "technical_decisions": [ { "decision": "ADR-001: Use Arc over Box", "rationale": "Thread-safe sharing needed for rayon parallelism and potential cluster distribution. Arc's reference counting overhead is acceptable given the compute-heavy workload.", "alternatives_considered": ["Box (faster, single-threaded only)", "Rc (no Send/Sync)"], "status": "Accepted" }, { "decision": "ADR-002: Equality saturation via egg crate as primary simplifier", "rationale": "E-graphs find globally optimal simplifications that greedy rewriting misses. The egg crate is production-proven (POPL 2021) and actively maintained.", "alternatives_considered": ["Pure pattern-matching rewriter (simpler, but misses optimizations)", "Custom e-graph implementation (unnecessary when egg exists)"], "status": "Accepted" }, { "decision": "ADR-003: WASM as primary OpenClaw integration, subprocess RPC as fallback", "rationale": "WASM allows in-process execution without IPC overhead and enables browser Canvas computation. Subprocess fallback for when full Rust performance (threads, GPU) is needed.", "alternatives_considered": ["HTTP microservice only (simpler, but adds network hop)", "FFI/NAPI (tighter coupling, platform-specific builds)"], "status": "Accepted" }, { "decision": "ADR-004: Dual license MIT + Apache 2.0", "rationale": "Maximum adoption: MIT for simplicity, Apache 2.0 for patent protection. Standard in Rust ecosystem.", "alternatives_considered": ["GPL (copyleft would limit commercial adoption)", "MIT only (no patent protection)"], "status": "Accepted" }, { "decision": "ADR-005: nom over pest for parser", "rationale": "nom is more flexible for dynamic grammar extension (user-defined functions, custom notation), compiles to WASM cleanly, and integrates well with Rust's type system.", "alternatives_considered": ["pest (PEG grammar, cleaner for static grammars)", "lalrpop (LR parser, overkill for math expressions)", "tree-sitter (focused on IDE use)"], "status": "Proposed — evaluate during Sprint 1" } ], "integration_with_existing_stack": { "description": "How SymClaw fits into Omar's existing HPC-AI platform ecosystem", "connections": [ { "project": "RustyTorch", "integration": "Numeric fallback for expressions that can't be solved symbolically — evaluate numerically using RustyTorch tensors; symbolic regression (find symbolic formula from numeric data)", "phase": "V1.0+" }, { "project": "SLAI (GPU Scheduler)", "integration": "Route heavy symbolic computations (large e-graphs, numeric ODE solving) to GPU-equipped nodes via SLAI scheduling", "phase": "V1.0+" }, { "project": "Clawbernetes", "integration": "Deploy SymClaw engine as Clawbernetes workload; auto-scale compute pods based on query complexity; distribute e-graph computation across cluster", "phase": "V1.0+" }, { "project": "StratoSwarm", "integration": "SymClaw as a distributed service within StratoSwarm's agent mesh; cross-node computation routing", "phase": "V2.0+" }, { "project": "OpenClaw Mission Control Dashboard", "integration": "SymClaw metrics (eval latency, cache hit rate, e-graph stats) surfaced in Mission Control; computation history in dashboard", "phase": "V0.5+" } ] }, "appendix": { "reference_implementations": [ {"name": "egg math.rs test", "url": "https://github.com/egraphs-good/egg/blob/main/tests/math.rs", "relevance": "Starting point for defining math Language in egg"}, {"name": "SymPy", "url": "https://github.com/sympy/sympy", "relevance": "Feature parity target, test case source"}, {"name": "Symbolica", "url": "https://github.com/benruijl/symbolica", "relevance": "High-performance Rust CAS, architectural inspiration"}, {"name": "cas-rs", "url": "https://github.com/eliphatfs/cas-rs", "relevance": "Minimal Rust CAS, good reference for AST design"}, {"name": "OpenClaw SKILL.md spec", "url": "https://docs.openclaw.ai/tools/skills", "relevance": "Skill authoring format and requirements"} ], "relevant_papers": [ "Willsey et al., 'egg: Fast and Extensible Equality Saturation', POPL 2021", "Tate et al., 'Equality Saturation: A New Approach to Optimization', POPL 2009", "Risch, 'The Solution of the Problem of Integration in Finite Terms', 1969", "Moses, 'Symbolic Integration: The Stormy Decade', CACM 1971" ] } }