{"id":29253514,"url":"https://github.com/heraclitus0/rupture-detector","last_synced_at":"2025-07-04T02:06:47.770Z","repository":{"id":301713646,"uuid":"1010096708","full_name":"heraclitus0/rupture-detector","owner":"heraclitus0","description":"Rupture detector for forecast misalignment and preventable loss detection","archived":false,"fork":false,"pushed_at":"2025-06-28T11:00:27.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T11:36:25.436Z","etag":null,"topics":["forecasting-model","loss-prevention","streamlit","supply-chain"],"latest_commit_sha":null,"homepage":"https://rupture-detector-mubnlicpxjqxpz8ovuo7je.streamlit.app","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/heraclitus0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2025-06-28T10:36:19.000Z","updated_at":"2025-06-28T11:00:59.000Z","dependencies_parsed_at":"2025-06-28T11:47:54.455Z","dependency_job_id":null,"html_url":"https://github.com/heraclitus0/rupture-detector","commit_stats":null,"previous_names":["heraclitus0/rupture-detector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/heraclitus0/rupture-detector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heraclitus0%2Frupture-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heraclitus0%2Frupture-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heraclitus0%2Frupture-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heraclitus0%2Frupture-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heraclitus0","download_url":"https://codeload.github.com/heraclitus0/rupture-detector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heraclitus0%2Frupture-detector/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263432382,"owners_count":23465577,"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","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":["forecasting-model","loss-prevention","streamlit","supply-chain"],"created_at":"2025-07-04T02:03:11.023Z","updated_at":"2025-07-04T02:06:47.754Z","avatar_url":"https://github.com/heraclitus0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"RUPTURE DETECTOR\r\n================\r\n\r\nForecast Drift Monitoring \u0026 Preventable Loss Detection for Supply Chains\r\n\r\n[Live Demo](https://rupture-detector-mubnlicpxjqxpz8ovuo7je.streamlit.app)\r\n\r\nThis tool detects misalignments between forecasted and actual demand. It identifies rupture points where deviation becomes costly and suggests corrective resets. The system quantifies preventable monetary loss using real-time thresholds and memory-aware state tracking.\r\n\r\n---------------------------------------------------------\r\nSECTION 1 — FEATURES\r\n---------------------------------------------------------\r\n\r\n- Upload real-world data via Excel or CSV\r\n- Auto-calculate drift: Delta(t), E(t), Theta(t)\r\n- Detect rupture events where ∆(t) \u003e Θ(t)\r\n- Quantify preventable loss in monetary terms\r\n- Visual diagnostics and downloadable output\r\n\r\n---------------------------------------------------------\r\nSECTION 2 — INSTALLATION\r\n---------------------------------------------------------\r\n\r\nCreate and activate a virtual environment:\r\n\r\n    python -m venv venv\r\n    source venv/bin/activate     # On Windows: .\\venv\\Scripts\\activate\r\n\r\nInstall the required packages:\r\n\r\n    pip install -r requirements.txt\r\n\r\n---------------------------------------------------------\r\nSECTION 3 — FILE STRUCTURE\r\n---------------------------------------------------------\r\n\r\n    rupture_detector/\r\n    ├── app.py            # Streamlit interface\r\n    ├── rupture.py        # Core logic (RCC silently embedded)\r\n    ├── requirements.txt  # Dependency list\r\n\r\n---------------------------------------------------------\r\nSECTION 4 — DATA FORMAT\r\n---------------------------------------------------------\r\n\r\nYour input file must be an Excel or CSV with the following columns:\r\n\r\n    Date        (YYYY-MM-DD format)\r\n    Forecast    (numeric)\r\n    Actual      (numeric)\r\n    Unit_Cost   (monetary per unit)\r\n\r\n---------------------------------------------------------\r\nSECTION 5 — RUNNING LOCALLY\r\n---------------------------------------------------------\r\n\r\nTo start the app locally:\r\n\r\n    streamlit run app.py\r\n\r\nStreamlit UI will load in your browser.\r\n\r\n---------------------------------------------------------\r\nSECTION 6 — PARAMETERS\r\n---------------------------------------------------------\r\n\r\nThe following parameters are adjustable in-app:\r\n\r\n    c        - Drift amplification factor\r\n    a        - Sensitivity of threshold to drift\r\n    Theta0   - Base rupture threshold\r\n    sigma    - Noise level for volatility\r\n    alpha    - EWMA smoothing factor\r\n    k        - EWMA standard deviation multiplier\r\n\r\nThese can be exposed to UI sliders or presets.\r\n\r\n---------------------------------------------------------\r\nSECTION 7 — OUTPUTS\r\n---------------------------------------------------------\r\n\r\n- Delta(t): instantaneous drift\r\n- E(t): cumulative epistemic misalignment\r\n- Theta(t): rupture threshold over time\r\n- Rupture Table: dates and loss amounts\r\n- Plot: Drift vs Threshold (with rupture flags)\r\n- Total preventable monetary loss\r\n\r\n---------------------------------------------------------\r\nSECTION 8 — DEPLOYMENT OPTIONS\r\n---------------------------------------------------------\r\n\r\nYou can deploy on:\r\n\r\n- Streamlit Cloud\r\n- Self-hosted server (Docker or VM)\r\n- Embedded inside ERP dashboards\r\n- Local desktop usage (single-user Excel monitor)\r\n\r\n---------------------------------------------------------\r\nSECTION 9 — EXTENSION IDEAS\r\n---------------------------------------------------------\r\n\r\n- REST API integration (e.g., with NetSuite)\r\n- Email/Slack alerts for new ruptures\r\n- Authentication for multi-team use\r\n- Multi-sheet ingestion\r\n- Real-time data ingestion hook\r\n\r\n---------------------------------------------------------\r\nSECTION 10 — LICENSE\r\n---------------------------------------------------------\r\n\r\nMIT License. Free for personal and commercial use with attribution.\r\n\r\n---------------------------------------------------------\r\nSECTION 11 — AUTHOR\r\n---------------------------------------------------------\r\n\r\nBuilt by Pulikanti Sashi Bharadwaj\r\n\r\nContact: bharadwajpulikanti11@gmail.com\r\n---------------------------------------------------------\r\nSECTION 12 — THEORETICAL FOUNDATION\r\n---------------------------------------------------------\r\n\r\nThis tool is grounded in the principles of the **Recursion Control Calculus (RCC)** — a formal framework for regulating epistemic misalignment in volatile environments.\r\n\r\nRCC introduces symbolic memory (`V(t)`), distortion (`∆(t)`), and adaptive rupture thresholds (`Θ(t)`) to track misalignment between internal projections and emergent reality — enabling early detection of systemic drift.\r\n\r\nFor the complete mathematical formulation, see:\r\n\r\nPulikanti, S.B. (2025). *Recursion Control Calculus: A Formal Epistemic Control System for Drift Regulation under Stochastic Volatility*. Zenodo.  \r\n[https://doi.org/10.5281/zenodo.15730197](https://doi.org/10.5281/zenodo.15730197)\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheraclitus0%2Frupture-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheraclitus0%2Frupture-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheraclitus0%2Frupture-detector/lists"}