{"id":31618056,"url":"https://github.com/pkeffect/numbers","last_synced_at":"2025-10-06T13:45:21.562Z","repository":{"id":317442193,"uuid":"1066035888","full_name":"pkeffect/numbers","owner":"pkeffect","description":"Math things and stuff","archived":false,"fork":false,"pushed_at":"2025-09-30T21:31:18.000Z","size":100,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-30T23:25:21.315Z","etag":null,"topics":["constants","docker","docker-compose","eluer","fastpi","math","phi","pi","python","sqlite"],"latest_commit_sha":null,"homepage":"https://internode.info/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkeffect.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T23:15:20.000Z","updated_at":"2025-09-30T21:31:22.000Z","dependencies_parsed_at":"2025-09-30T23:25:35.629Z","dependency_job_id":"541c6fd0-1d18-4c49-93ae-d548e030d2a2","html_url":"https://github.com/pkeffect/numbers","commit_stats":null,"previous_names":["pkeffect/numbers"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pkeffect/numbers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkeffect%2Fnumbers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkeffect%2Fnumbers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkeffect%2Fnumbers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkeffect%2Fnumbers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkeffect","download_url":"https://codeload.github.com/pkeffect/numbers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkeffect%2Fnumbers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621844,"owners_count":26017253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["constants","docker","docker-compose","eluer","fastpi","math","phi","pi","python","sqlite"],"created_at":"2025-10-06T13:45:15.853Z","updated_at":"2025-10-06T13:45:21.543Z","avatar_url":"https://github.com/pkeffect.png","language":"Python","readme":"# 🔢 Math Constants Storage System\n\n\u003e **⚠️ IMPORTANT: DATA FILES NOT INCLUDED**\n\u003e \n\u003e This repository contains the API and storage infrastructure **only**. The mathematical constant data files (billions of digits) are **NOT included** due to their large size (multiple GB per constant).\n\u003e \n\u003e **You must obtain these data files separately:**\n\u003e - Download from mathematical constant databases (e.g., [Archive.org](https://archive.org), university repositories)\n\u003e - Generate them yourself using high-precision computation tools\n\u003e - Contact research institutions that maintain these datasets\n\u003e \n\u003e **Expected file format:**\n\u003e - Plain text files containing digits (the system handles both formatted and unformatted)\n\u003e - **Supported formats:** With or without decimal points, spaces, and newlines (automatically cleaned)\n\u003e - Named according to convention: `pi_digits.txt`, `e_digits.txt`, etc.\n\u003e - Place in the `data/` directory before starting the system\n\u003e \n\u003e **We are exploring options for hosting these datasets** and will update this notice when publicly accessible sources become available. See [Data Sources](#-data-sources) section below for more information.\n\nHigh-performance, triple-redundancy storage system for accessing billions of digits of mathematical constants (π, φ, e, √2, and more) with FastAPI backend, dedicated endpoints per constant, and accuracy-first design.\n\n## ✨ Features\n\n- **12 Mathematical Constants**: Pi, Euler's number, Golden ratio, Square roots, Logarithms, and more\n- **Dedicated Endpoints**: Each constant has its own clean API namespace (`/pi/*`, `/e/*`, etc.)\n- **Triple Redundancy**: Original file + SQLite chunks + Binary cache\n- **Smart Cache Management**: Automatically skips already-built caches\n- **Accuracy First**: Automatic verification and corruption detection\n- **High Performance**: Optimized for random access to billions of digits\n- **Modular Architecture**: Clean separation with 16 focused router files\n- **Hot Reloading**: Development-friendly Docker setup\n- **Backward Compatible**: Legacy parameterized endpoints still work\n- **LLM Integration**: Clean JSON responses for AI/ML applications\n\n## 🚀 Quick Start\n\n\u003e **⚠️ Prerequisites:** You must have the mathematical constant data files before proceeding. See the [Data Sources](#-data-sources) section below.\n\n```bash\n# Clone the repository\ngit clone https://github.com/pkeffect/numbers\ncd numbers\n\n# Copy environment configuration\ncp .env.example .env\n\n# Place your math constant files in data/ directory\n# Required filenames: pi_digits.txt, e_digits.txt, phi_digits.txt, etc.\n# Files should contain only digits (no decimal points or formatting)\n\n# Start the development environment\ndocker-compose up --build\n\n# Build caches (after first startup)\ncurl -X POST http://localhost:8000/admin/build-all-caches\n```\n\n## 📊 Supported Mathematical Constants\n\n| Constant | Symbol | Endpoint | Filename | Description |\n|----------|---------|----------|----------|-------------|\n| Pi | π | `/pi/*` | `pi_digits.txt` | Ratio of circumference to diameter |\n| Euler's number | e | `/e/*` | `e_digits.txt` | Base of natural logarithm |\n| Golden Ratio | φ | `/phi/*` | `phi_digits.txt` | (1 + √5) / 2 |\n| Square Root of 2 | √2 | `/sqrt2/*` | `sqrt2_digits.txt` | √2 |\n| Square Root of 3 | √3 | `/sqrt3/*` | `sqrt3_digits.txt` | √3 |\n| Catalan | G | `/catalan/*` | `catalan_digits.txt` | Catalan constant |\n| Euler-Mascheroni | γ | `/eulers/*` | `eulers_digits.txt` | Euler-Mascheroni constant |\n| Lemniscate | ϖ | `/lemniscate/*` | `lemniscate_digits.txt` | Lemniscate constant |\n| Natural log of 2 | ln(2) | `/log2/*` | `log2_digits.txt` | Natural logarithm of 2 |\n| Natural log of 3 | ln(3) | `/log3/*` | `log3_digits.txt` | Natural logarithm of 3 |\n| Natural log of 10 | ln(10) | `/log10/*` | `log10_digits.txt` | Natural logarithm of 10 |\n| Apéry's constant | ζ(3) | `/zeta3/*` | `zeta3_digits.txt` | Riemann zeta function ζ(3) |\n\n## 🔧 API Endpoints\n\n### **General Endpoints**\n\n```bash\nGET  /                    # API root with system info\nGET  /health              # System health check\nGET  /constants           # List all constants with status\n```\n\n### **Per-Constant Endpoints** (Pattern for all 12 constants)\n\nEach constant has 7 dedicated endpoints:\n\n```bash\nGET  /{constant}/status        # Status and cache information\nGET  /{constant}/digits        # Retrieve digits from position\nGET  /{constant}/search        # Search for digit sequences\nGET  /{constant}/stats         # Statistical analysis\nGET  /{constant}/random        # Get random digits\nPOST /{constant}/build-cache   # Build SQLite and binary cache\nPOST /{constant}/verify        # Verify data integrity\n```\n\n**Example for Pi (π):**\n```bash\nGET  /pi/status\nGET  /pi/digits?start=0\u0026length=50\nGET  /pi/search?sequence=123456\nGET  /pi/stats?sample_size=10000\nGET  /pi/random?length=20\u0026seed=42\nPOST /pi/build-cache\nPOST /pi/verify?sample_count=5\n```\n\n### **Admin Endpoints**\n\n```bash\nPOST /admin/build-all-caches   # Build caches for all constants\nGET  /admin/status             # Administrative status\n```\n\n### **Legacy Endpoints** (Deprecated but still functional)\n\nFor backward compatibility, the old parameterized style still works:\n\n```bash\nGET  /digits/{constant_id}              # Use /{constant}/digits instead\nGET  /search/{constant_id}              # Use /{constant}/search instead\nGET  /stats/{constant_id}               # Use /{constant}/stats instead\nGET  /random/{constant_id}              # Use /{constant}/random instead\nPOST /admin/build-cache/{constant_id}   # Use /{constant}/build-cache instead\nPOST /admin/verify/{constant_id}        # Use /{constant}/verify instead\n```\n\n### **Documentation**\n- `GET /docs` - Interactive API documentation (Swagger UI)\n- `GET /redoc` - Alternative API documentation (ReDoc)\n\n## 📁 Project Structure\n\n```\nmath-constants-storage/\n├── app/\n│   ├── main.py                      # Application entry (60 lines)\n│   ├── api/\n│   │   ├── routers/                 # Modular routers (NEW!)\n│   │   │   ├── __init__.py         # Router exports\n│   │   │   ├── general.py          # Root, health, list\n│   │   │   ├── admin.py            # Bulk operations\n│   │   │   ├── legacy.py           # Backward compatibility\n│   │   │   ├── pi.py               # Pi endpoints\n│   │   │   ├── e.py                # Euler's number endpoints\n│   │   │   ├── phi.py              # Golden ratio endpoints\n│   │   │   ├── sqrt2.py            # √2 endpoints\n│   │   │   ├── sqrt3.py            # √3 endpoints\n│   │   │   ├── catalan.py          # Catalan constant endpoints\n│   │   │   ├── eulers.py           # Euler-Mascheroni endpoints\n│   │   │   ├── lemniscate.py       # Lemniscate endpoints\n│   │   │   ├── log2.py             # ln(2) endpoints\n│   │   │   ├── log3.py             # ln(3) endpoints\n│   │   │   ├── log10.py            # ln(10) endpoints\n│   │   │   └── zeta3.py            # Apéry's constant endpoints\n│   │   └── models/\n│   │       ├── requests.py         # Request models\n│   │       └── responses.py        # Response models\n│   ├── storage/\n│   │   ├── manager.py              # Single constant manager\n│   │   ├── multi_manager.py        # Multi-constant manager\n│   │   ├── file_source.py          # Original file access\n│   │   ├── sqlite_source.py        # SQLite chunked storage\n│   │   └── binary_source.py        # Binary packed storage\n│   ├── core/\n│   │   ├── config.py               # Configuration\n│   │   ├── constants.py            # Mathematical constants definitions\n│   │   └── exceptions.py           # Custom exceptions\n│   └── utils/                       # Helper functions\n├── data/                            # Math constant data files (gitignored)\n├── logs/                            # Application logs (gitignored)\n├── tests/                           # Test suite\n└── docker/                          # Docker configuration\n```\n\n## 🐳 Docker Development\n\n```bash\n# Start basic development environment\ndocker-compose up\n\n# Start with SQLite browser for debugging\ndocker-compose --profile debug up\n\n# View logs\ndocker-compose logs -f math-constants-api\n\n# Rebuild containers\ndocker-compose up --build\n\n# Stop all services\ndocker-compose down\n```\n\n## 🔒 Data Integrity\n\n### Triple Verification System\n1. **Original File**: Source of truth, never modified\n2. **SQLite Chunks**: Fast access with MD5 checksums\n3. **Binary Cache**: Space-efficient with built-in verification\n\n### Automatic Safeguards\n- Checksums on all cached data\n- Cross-source validation every 100th request\n- Startup integrity verification\n- Corruption detection and fallback\n- Smart cache building (skips complete caches)\n\n## ⚙️ Configuration\n\nKey environment variables (see `.env.example`):\n\n```bash\n# Primary Math Constant (Pi)\nPI_FILE_PATH=/app/data/pi_digits.txt\nPI_SQLITE_DB=/app/data/pi_chunks.db\nPI_BINARY_FILE=/app/data/pi_binary.dat\n\n# Additional constants follow same pattern\nE_FILE_PATH=/app/data/e_digits.txt\nPHI_FILE_PATH=/app/data/phi_digits.txt\n# ... etc for all 12 constants\n\n# Storage Configuration\nCHUNK_SIZE=10000\nVERIFY_EVERY=100\n\n# API Configuration\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\n```\n\n## 🧪 Testing\n\n```bash\n# Run tests\ndocker-compose exec math-constants-api pytest\n\n# Run with coverage\ndocker-compose exec math-constants-api pytest --cov=app\n\n# Run specific test file\ndocker-compose exec math-constants-api pytest tests/test_storage.py\n```\n\n## 🚀 Performance\n\n- **Random Access**: O(1) lookup to any position\n- **Memory Efficient**: Handles multi-GB files without loading into memory\n- **Cached Queries**: SQLite index for frequently accessed ranges\n- **Parallel Safe**: Thread-safe storage operations\n- **Smart Caching**: Automatic detection of existing caches\n\n## 🤖 LLM Integration Examples\n\n```python\nimport requests\n\n# List available constants\nresponse = requests.get(\"http://localhost:8000/constants\")\nconstants = response.json()\n\n# Get Pi digits\nresponse = requests.get(\"http://localhost:8000/pi/digits?start=0\u0026length=100\")\npi_data = response.json()\n\n# Search for birthday in multiple constants\nfor constant in [\"pi\", \"e\", \"phi\"]:\n    result = requests.get(f\"http://localhost:8000/{constant}/search?sequence=19851201\")\n    print(f\"{constant}: {result.json()}\")\n\n# Get random digits for creative applications\nresponse = requests.get(\"http://localhost:8000/pi/random?length=100\u0026seed=42\")\n\n# Statistical analysis for research\nresponse = requests.get(\"http://localhost:8000/e/stats?sample_size=100000\")\n```\n\n## 📊 Usage Examples\n\n### Check System Status\n```bash\n# Overall health\ncurl http://localhost:8000/health\n\n# List all constants\ncurl http://localhost:8000/constants\n\n# Check specific constant\ncurl http://localhost:8000/pi/status\n```\n\n### Build Caches for All Constants\n```bash\n# Build all (skips already-cached)\ncurl -X POST http://localhost:8000/admin/build-all-caches\n\n# Force rebuild all\ncurl -X POST \"http://localhost:8000/admin/build-all-caches?force_rebuild=true\"\n\n# Monitor progress in logs\ndocker-compose logs -f math-constants-api\n```\n\n### Access Multiple Constants\n```bash\n# Pi digits\ncurl \"http://localhost:8000/pi/digits?start=0\u0026length=100\"\n\n# Euler's number\ncurl \"http://localhost:8000/e/digits?start=0\u0026length=100\"\n\n# Golden ratio\ncurl \"http://localhost:8000/phi/digits?start=0\u0026length=100\"\n\n# Search for pattern in Pi\ncurl \"http://localhost:8000/pi/search?sequence=123456\"\n\n# Get statistics for √2\ncurl \"http://localhost:8000/sqrt2/stats?sample_size=50000\"\n```\n\n## 🎯 What's New in v2.0\n\n### Major Changes\n- ✅ **Dedicated endpoints per constant** - Clean URLs like `/pi/digits` instead of `/digits/pi`\n- ✅ **Modular router architecture** - 16 focused files instead of 1 monolithic main.py\n- ✅ **Backward compatible** - Old parameterized endpoints still work (marked as deprecated)\n- ✅ **Enhanced documentation** - Better organized Swagger UI with grouping by constant\n- ✅ **Admin status endpoint** - Monitor cache status and system health\n- ✅ **Improved error handling** - Better error messages and edge case handling\n\n### Migration from v1.0\nOld endpoints still work but are deprecated:\n```bash\n# Old style (still works)\ncurl \"http://localhost:8000/digits/pi?start=0\u0026length=50\"\n\n# New style (recommended)\ncurl \"http://localhost:8000/pi/digits?start=0\u0026length=50\"\n```\n\n## 🔮 Future Roadmap\n\n- [ ] Advanced pattern recognition with ML\n- [ ] GraphQL API support\n- [ ] Real-time WebSocket subscriptions for streaming digits\n- [ ] Distributed storage across multiple nodes\n- [ ] Redis caching layer for frequently accessed ranges\n- [ ] Advanced mathematical sequence analysis\n- [ ] Web-based visualization interface\n- [ ] Comparison endpoints (compare patterns across constants)\n- [ ] Export endpoints (download ranges in various formats)\n- [ ] Rate limiting per constant\n- [ ] Authentication and authorization\n- [ ] Metadata endpoints (mathematical properties and fun facts)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n\n## 🙏 Acknowledgments\n\n- Mathematical constants computed using high-precision algorithms\n- Built with FastAPI, SQLite, and Docker\n- Inspired by the beauty of mathematical constants\n- Community contributions and feedback\n\n## 📞 Support\n\n- 📚 [Full Documentation](docs/)\n- 🐛 [Issue Tracker](https://github.com/your-repo/issues)\n- 💬 [Discussions](https://github.com/your-repo/discussions)\n- 📧 [Email Support](mailto:support@mathconstants.dev)\n\n## 📁 Data Sources\n\n### Where to Get Mathematical Constant Data Files\n\nSince the data files are not included in this repository, here are recommended sources:\n\n#### Option 1: Download Pre-Computed Files\n\n**Pi (π):**\n- [Archive.org - Pi to 1 Trillion Digits](https://archive.org/details/pi_digits)\n- [Numbers API](http://www.numberworld.org/digits/Pi/)\n- [University of Tokyo - Pi Database](http://www.super-computing.org/)\n\n**Euler's Number (e):**\n- [Archive.org - E Digits](https://archive.org/search.php?query=euler%20number%20digits)\n- [Mathematical Constants Database](http://www.plouffe.fr/simon/constants/)\n\n**Golden Ratio (φ):**\n- [Wolfram MathWorld Resources](https://mathworld.wolfram.com/GoldenRatio.html)\n- [OEIS - Online Encyclopedia of Integer Sequences](https://oeis.org/)\n\n**Square Roots and Other Constants:**\n- [Inverse Symbolic Calculator](http://wayback.cecm.sfu.ca/projects/ISC/ISCmain.html)\n- [Mathematical Constants Repository](http://www.plouffe.fr/)\n\n#### Option 2: Generate Files Yourself\n\nUse high-precision mathematical libraries:\n\n**Python (mpmath):**\n```python\nfrom mpmath import mp\nmp.dps = 1000000  # Set precision to 1 million digits\n\n# Generate Pi\npi_digits = str(mp.pi).replace('.', '')\nwith open('pi_digits.txt', 'w') as f:\n    f.write(pi_digits)\n\n# Generate e\ne_digits = str(mp.e).replace('.', '')\nwith open('e_digits.txt', 'w') as f:\n    f.write(e_digits)\n\n# Generate phi (Golden Ratio)\nphi_digits = str(mp.phi).replace('.', '')\nwith open('phi_digits.txt', 'w') as f:\n    f.write(phi_digits)\n```\n\n**Mathematica:**\n```mathematica\n(* Export 1 billion digits of Pi *)\nExport[\"pi_digits.txt\", StringReplace[ToString[N[Pi, 1000000000]], \".\" -\u003e \"\"], \"Text\"]\n```\n\n**y-cruncher (Fastest):**\n- [y-cruncher Download](http://www.numberworld.org/y-cruncher/)\n- Can compute billions/trillions of digits\n- Optimized for multi-core processors\n\n#### Option 3: Request from Research Institutions\n\nContact these institutions that maintain large mathematical constant databases:\n- Stanford University Mathematics Department\n- University of Tokyo Supercomputing Center\n- CERN Computing Division\n- Max Planck Institute for Mathematics\n\n#### File Format Requirements\n\n**Good news:** The system automatically handles multiple formats!\n\n```\n✅ All these formats work (automatically cleaned):\n3.1415926535897932384626433832795...  (with decimal point)\n31415926535897932384626433832795...   (without decimal point)\n3 1 4 1 5 9 2 6 5 3 5 8 9 7...        (with spaces)\n3141592653589793\n2384626433832795...                   (with newlines)\n3.141 592 653 589 793...              (mixed formatting)\n```\n\n**How it works:**\n- System automatically removes: decimal points (`.`), spaces, newlines (`\\n`), carriage returns (`\\r`)\n- Only digits (0-9) are retained for storage and computation\n- Original file is never modified - cleaning happens in memory\n\n**Validation script:**\n```python\ndef validate_constant_file(filepath):\n    \"\"\"Validate mathematical constant file format\"\"\"\n    with open(filepath, 'r') as f:\n        content = f.read()\n    \n    # Clean content (same as system does)\n    cleaned = content.replace('.', '').replace(' ', '').replace('\\n', '').replace('\\r', '')\n    \n    # Check for invalid characters after cleaning\n    if not cleaned.isdigit():\n        invalid = set(cleaned) - set('0123456789')\n        print(f\"❌ Invalid characters found: {invalid}\")\n        return False\n    \n    print(f\"✅ Valid format: {len(cleaned):,} digits\")\n    print(f\"   Original file size: {len(content):,} characters\")\n    print(f\"   After cleaning: {len(cleaned):,} digits\")\n    return True\n\n# Test your files\nvalidate_constant_file('data/pi_digits.txt')\n```\n\n### Hosting Plans (Coming Soon)\n\nWe are currently exploring options to host pre-processed datasets:\n\n- **Option A:** Cloud storage (AWS S3, Google Cloud Storage)\n- **Option B:** Academic partnerships for direct downloads\n- **Option C:** Torrent distribution for large files\n- **Option D:** CDN-backed public repository\n\n**Status:** In planning phase. Follow [GitHub Discussions](https://github.com/your-repo/discussions) for updates.\n\n**Want to help?** If you have access to hosting resources or mathematical constant datasets, please reach out via [GitHub Issues](https://github.com/your-repo/issues).\n\n---\n\n**Note**: This system is designed for educational, research, and creative applications. Ensure you have proper rights to use any mathematical constant datasets.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkeffect%2Fnumbers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkeffect%2Fnumbers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkeffect%2Fnumbers/lists"}