{"data":{"kind":"file","path":"README.md","version_id":"lwrbtpnypenfiil3976j0gsw","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":5361,"modified_at":"2026-01-29T02:15:36.693000","content_hash":"699cd7ac2ce6bf78aecf043860c4d02a7890bd3ebb46db7b517e6f7180652689"},"entries":[],"content":"# FluxEM Ultimate\n\nThe ultimate tool-calling environment for training LLMs with **242 deterministic tools** across **43 domains**.\n\n## Features\n\n- **242 Tools**: 9.3x more than the original FluxEM environment\n- **43 Domains**: Math, science, engineering, finance, everyday tasks, and more\n- **RAG-based Retrieval**: Only 20-25 relevant tools in context (92% token savings)\n- **Domain Routing**: Neural classifier selects relevant domains\n- **Multi-Tool Calls**: Execute multiple tools per turn\n- **5-Phase Curriculum**: Progressive learning from 28 to 242 tools\n- **Adaptive Turns**: Dynamic max_turns based on problem complexity\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  Domain Router → Selects 2-3 relevant domain groups          │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n                     ▼\n┌─────────────────────────────────────────────────────────────┐\n│  Tool Retriever (FAISS) → Top 20 most relevant tools        │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n                     ▼\n┌─────────────────────────────────────────────────────────────┐\n│  Dynamic Environment → Multi-tool calls, adaptive turns     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Tool Categories\n\n| Category | Tools | Domains |\n|----------|-------|---------|\n| Core Math | 28 | arithmetic, number_theory, combinatorics, sets |\n| Physical Sciences | 31 | physics, chemistry, thermodynamics, optics |\n| Life Sciences | 11 | biology, pharmacology |\n| Data & Statistics | 26 | statistics, probability, data, signal_processing |\n| Engineering | 23 | electrical, control_systems, optimization |\n| Finance | 13 | finance, currency |\n| Everyday | 37 | cooking, fitness, travel, diy, photography, gardening |\n| Text & Logic | 69 | text, logic, graphs, music, color, security |\n\n## Installation\n\n```bash\n# Install the environment\nprime env install fluxem-ultimate --path ./environments/fluxem_ultimate\n\n# Or install from hub (after publishing)\nprime env install hunterbown/fluxem-ultimate\n```\n\n## Usage\n\n### Local Evaluation\n\n```bash\n# Quick test\nprime eval run fluxem-ultimate -m openai/gpt-4o-mini -n 10\n\n# Full evaluation\nprime eval run fluxem-ultimate -m Qwen/Qwen3-4B-Instruct-2507 -n 100\n```\n\n### Training\n\n```bash\n# Phase 1: Foundation (28 tools)\nprime rl run configs/lab/fluxem_ultimate/foundation.toml\n\n# Phase 2: Core Sciences (52 tools)\nprime rl run configs/lab/fluxem_ultimate/core_sciences.toml\n\n# Phase 3: Applied (88 tools)\nprime rl run configs/lab/fluxem_ultimate/applied.toml\n\n# Phase 4: Advanced (125 tools)\nprime rl run configs/lab/fluxem_ultimate/advanced.toml\n\n# Phase 5: Mastery (242 tools)\nprime rl run configs/lab/fluxem_ultimate/mastery.toml\n```\n\n### Monitor Training\n\n```bash\nprime rl logs <run_id> -f | grep \"SUCCESS Step\"\n```\n\n## Curriculum\n\n| Phase | Steps | Tools | Focus |\n|-------|-------|-------|-------|\n| Foundation | 300 | 28 | Math core, basic judgment |\n| Core Sciences | 300 | 52 | Physics, chemistry, statistics |\n| Applied | 400 | 88 | Finance, engineering, biology |\n| Advanced | 500 | 125 | Optimization, text, signals |\n| Mastery | 500 | 242 | All domains + adversarial |\n\n## Reward Function\n\n```\nReward = 0.30 × correctness\n       + 0.25 × tool_appropriateness\n       + 0.20 × tool_efficiency\n       + 0.25 × reasoning_quality\n```\n\n## Configuration Options\n\n```python\nload_environment(\n    n_problems=1000,\n    phase=\"mastery\",  # foundation, core_sciences, applied, advanced, mastery\n    use_retrieval=True,  # Enable RAG\n    use_domain_routing=True,  # Enable domain router\n    retrieved_tools_count=25,  # Tools in context\n    max_turns=10,\n    adaptive_turns=True,  # Dynamic max_turns\n    adversarial_ratio=0.15,\n    embedding_backend=\"sbert\",  # \"sbert\" (default) or \"hash\" (fork-safe)\n    embedding_dim=384,  # Hash embedding size\n)\n```\n\n## File Structure\n\n```\nfluxem_ultimate/\n├── src/fluxem_ultimate/\n│   ├── __init__.py\n│   ├── env_ultimate.py      # Main environment\n│   ├── tool_embeddings.py   # RAG retrieval\n│   ├── domain_router.py     # Domain classification\n│   ├── multi_parser.py      # Multi-tool parser\n│   ├── tools_full.py        # Tool registry\n│   ├── dataset_ultimate.py  # 430+ problem generators\n│   └── rewards_v2.py        # Enhanced rewards\n├── embeddings/              # Pre-built index\n├── fluxem_ultimate.py       # Entry point\n└── pyproject.toml\n```\n\n## License\n\nMIT\n","encoding":"utf-8","truncated":false,"total_bytes":5361},"status":null}