{"id":46340615,"url":"https://github.com/awa-si/nhsmm","last_synced_at":"2026-03-04T20:01:17.257Z","repository":{"id":318871171,"uuid":"1073607177","full_name":"awa-si/NHSMM","owner":"awa-si","description":"Developing neural, hierarchical, and context-aware Hidden Semi-Markov Models (HSMMs) for structured temporal pattern learning","archived":false,"fork":false,"pushed_at":"2025-12-30T16:10:28.000Z","size":922,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-12-30T22:17:47.835Z","etag":null,"topics":["finance","healthcare","hsmm","iot","ml","neural-networks","robotics","trading"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awa-si.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-10T11:01:46.000Z","updated_at":"2025-12-30T16:10:32.000Z","dependencies_parsed_at":"2025-10-16T23:40:39.535Z","dependency_job_id":"f21d8b6c-e41e-4256-9cb7-d32e18750248","html_url":"https://github.com/awa-si/NHSMM","commit_stats":null,"previous_names":["awwea/neuralhsmm","awa-si/nhsmm"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/awa-si/NHSMM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awa-si%2FNHSMM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awa-si%2FNHSMM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awa-si%2FNHSMM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awa-si%2FNHSMM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awa-si","download_url":"https://codeload.github.com/awa-si/NHSMM/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awa-si%2FNHSMM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30091566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T19:41:02.502Z","status":"ssl_error","status_checked_at":"2026-03-04T19:40:05.550Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["finance","healthcare","hsmm","iot","ml","neural-networks","robotics","trading"],"created_at":"2026-03-04T20:01:15.596Z","updated_at":"2026-03-04T20:01:17.244Z","avatar_url":"https://github.com/awa-si.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NHSMM — Neural Hidden Semi-Markov Models\n\n* **Repository:** [NHSMM on GitHub](https://github.com/awa-si/NHSMM)\n* **Interfaces:** [NHSMM-INTERFACES on GitHub](https://github.com/awa-si/nhsmm-interfaces)\n* **Documentation:** [NHSMM Wiki](https://github.com/awa-si/NHSMM/wiki)\n* **Article:** [Unlocking Hidden Patterns in Time – Meet NHSMM](https://medium.com/@awa-si/unlocking-hidden-patterns-in-time-meet-nhsmm-the-neural-hidden-semi-markov-model-cd3f1e2428c2)\n\n---\n\n\u003e ⚠️ **Alpha stage** — NHSMM is a **proof-of-concept** and actively evolving. Public APIs may change before stable `1.0.0`.\n\n**NHSMM** is a **modular PyTorch library** for **context-aware sequential modeling**, forming the foundation of the **State Aware Engine ([SAE](https://github.com/awa-si/SAE))**.\n**[NHSMM-INTERFACES](https://github.com/awa-si/nhsmm-interfaces)** defines domain-level contracts for integrating NHSMM in diverse systems.\n\nDesigned for **developers, data scientists, and system integrators**, NHSMM enables rapid understanding, deployment, and extension of **latent state models** for domains such as **finance, IoT, robotics, health, and cybersecurity**.\n\n[![PyPI](https://img.shields.io/pypi/v/nhsmm.svg)](https://pypi.org/project/nhsmm/) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)\n\n---\n\n## 🌟 Highlights\n\n* **Neural HSMM** — integrates Hidden Semi-Markov Models with neural parameterization for expressive latent dynamics.\n* **Context-Aware Modulation** — initial, transition, duration, and emission distributions adapt to external covariates.\n* **Flexible Architectures** — supports hierarchical and hybrid models.\n* **PyTorch \u0026 GPU Ready** — scalable multi-domain deployment.\n* **Modular Foundation** — for research, experimentation, and production-ready sequence models.\n\n---\n\n## 🧩 Overview\n\nNHSMM explicitly models:\n\n* **Context-Dependent State Durations** — variable dwell-times per hidden state influenced by covariates.\n* **Context-Dependent Transitions** — dynamic transition probabilities adapting to time-varying features.\n\nSuitable for **non-stationary, heterogeneous, and time-aware sequences** across real-world applications.\n\n---\n\n## NHSMM Project Covenant\n\n1. **Forever Open Core** — `nhsmm` remains fully open-source and actively maintained.\n2. **No Hidden Dependencies** — core library uses only open components; experimental modules (`nhsmm-interfaces`) are optional.\n3. **Transparent Evolution** — research previews and pre-release interfaces are clearly marked.\n4. **Community Respect** — contributions are acknowledged; experimental previews may close but knowledge remains accessible.\n5. **Clear Upgrade Path** — experimental work informs SAE; core NHSMM is stable and independent.\n\n---\n\n## 🚀 Key Features\n\n* **Contextual HSMM** — dynamic modulation of initial, transition, duration, and emission probabilities.\n* **Duration Models** — explicit, context-aware state dwell-times.\n* **Emission Models** — Gaussian, Student-t, or discrete outputs; differentiable and context-aware.\n* **Transition Models** — learnable, covariate-aware with gating and temperature scaling; supports low-rank factorization.\n* **Hybrid HSMM-HMM Inference** — forward-backward and Viterbi adapted for neural latent states.\n* **Subclassable Distributions** — extend Initial, Duration, Transition, Emission modules.\n* **Differentiable Training** — gradient-based optimization, temperature annealing, neural modulation.\n* **Neural Context Encoders** — CNN, LSTM, or hybrid encoders for time-varying covariates.\n* **GPU-Ready** — fully batched operations.\n* **Multi-Domain Applicability** — finance, IoT, robotics, health, cybersecurity.\n* **Extensible Architecture** — foundation for SAE interfaces, API integration, and research projects.\n* **Hybrid Update Modes** — neural gradient-based updates, optional alternative schemes.\n\n---\n\n## ⚡ Performance \u0026 Scalability\n\n* Vectorized forward-backward for **batched likelihood computation**.\n* Optional low-rank transitions for **large state spaces**.\n* Supports **long sequences** efficiently.\n* Memory-efficient Viterbi optimized for GPU.\n* Handles **variable-length sequences** with padding and masking.\n\n---\n\n## 📌 Milestones\n\n| Stage               | Status  | Notes                                   |\n| ------------------- | ------- | --------------------------------------- |\n| Proof of Concept    | ✅ Done  | Alpha release (0.0.1-alpha)            |\n| Testing/Enhancement | ⚠️ Todo | Improve performance, extend API         |\n| Production Release  | ⚠️ Todo | Stable 1.0.0 release with documentation |\n\n---\n\n## 📦 Installation\n\n### 🔹 From PyPI (alpha stage)\n\n```bash\npip install nhsmm\n```\n\n### 🔹 From Source (recommended)\n\n```bash\ngit clone https://github.com/awa-si/NHSMM.git\ncd NHSMM\npip install -e .\n```\n\nEditable mode allows modification and testing without reinstalling.\n\n---\n\n## 🧠 Usage Example — Market Regime Detection\n\nSee: [State Occupancy \u0026 Duration/Transition Diagnostics](docs/test_ohlcv.md)\n\nWorks similarly for **IoT signals, health telemetry, robotics, or cybersecurity logs**.\n\n```python\nfrom nhsmm.models import HSMM\nmodel = HSMM(n_states=3, n_features=5)\nseq_features, canonical = model.encoder.encode(sequences)\n```\n\n---\n\n## 🔍 Conceptual Flow\n\n```text\nExternal Input → Neural Initial Module (π)\n                → Neural Transition Module (A)\n                → Neural Duration Module (D)\n                → Emission Module (Gaussian/Student-t/Discrete)\n                → Forward-Backward / Viterbi → Backprop\n```\n\n* **External Input:** features, covariates, embeddings.\n* **Neural Modules:** context-conditioned initial, transition, duration, and emission distributions.\n* **Inference:** latent states inferred via forward-backward and Viterbi.\n* **Backpropagation:** updates all neural modules jointly.\n\n---\n\n## 🌐 Multi-Domain Applicability\n\n* **Security \u0026 Cyber-Physical Systems:** anomaly and hidden state detection.\n* **Finance \u0026 Trading:** regime detection, forecasting, adaptive strategies.\n* **IoT \u0026 Industrial:** predictive maintenance, fault detection.\n* **Health \u0026 Wearables:** activity and state tracking, multimodal fusion.\n* **Robotics:** behavior monitoring, safe human-robot interaction.\n* **Telecommunications \u0026 Energy:** latent state monitoring, resource optimization.\n* **Research \u0026 AI:** temporal modeling, neural-probabilistic experiments.\n\n---\n\n## ⚙️ Development\n\n\u003e Contributions welcome! Bug reports, feature suggestions, or documentation improvements strengthen NHSMM.\n\n```bash\ngit clone https://github.com/awa-si/NHSMM.git\ncd NHSMM\npip install -e \".[dev]\"\npytest -v\nblack nhsmm\nruff check nhsmm\n```\n\n---\n\n## Support\n\nDevelopment is supported via **GitHub Sponsors, Patreon, Medium**.\nSee [FUNDING.md](./FUNDING.md) for details.\n\n---\n\n## 🧾 License\n\nApache License 2.0 © 2024 **AWA.SI**\nFull terms: [LICENSE](https://github.com/awa-si/NHSMM/blob/develop/LICENSE)\n\nIf used in academic work, please cite the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawa-si%2Fnhsmm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawa-si%2Fnhsmm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawa-si%2Fnhsmm/lists"}