dreamforge 0.2.0__tar.gz

dreamforge-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JToSound
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dreamforge-0.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: dreamforge
+Version: 0.2.0
+Summary: Deterministic, offline sandbox for non-clinical sleep/dream simulation proxies (research and visualization simulator; no medical claims).
+Author: JToSound
+License: MIT License
+        
+        Copyright (c) 2026 JToSound
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=2
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: networkx<4,>=3.3
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.37; extra == "dashboard"
+Requires-Dist: plotly>=5.22; extra == "dashboard"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
+Requires-Dist: hypothesis<7,>=6; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# DreamForge AI
+
+> DreamForge is a research and visualization simulator. It does not measure brains, diagnose conditions, predict dreams, infer psychological meaning, or provide medical advice.
+
+An open-source, deterministic, offline sandbox for simulating explicit,
+configurable, **non-clinical proxies** related to sleep regulation, sleep-stage
+dynamics, normalized neuromodulatory patterns, synthetic-memory graph
+selection, and structured dream-context features — under active construction
+toward the milestone plan in [`MASTER_PROMPT.md`](MASTER_PROMPT.md).
+
+## Status
+
+First execution slice + M1 (complete) and M2 groundwork: deterministic core with
+an 8-hour (960 × 30 s epoch) offline trace, event sourcing, DQCJ-1 canonical
+serialization, hash-verified exports, structured dream context/features/score,
+and the mandatory offline narrative provider with labeled report blocks. See
+[`ARCHITECTURE.md`](ARCHITECTURE.md), [`RESEARCH.md`](RESEARCH.md),
+[`LIMITATIONS.md`](LIMITATIONS.md), and `docs/`.
+
+**Not yet built** (by explicit scope control): API, plugins, notebooks,
+streaming/tool-use adapter features.
+
+## Optional: local / OpenAI-compatible narrative provider (opt-in)
+
+The offline mock is always the default. To use a local model via Ollama's
+OpenAI-compatible endpoint (or any `/chat/completions` service), construct the
+adapter explicitly in your own script — nothing is enabled by configuration
+alone:
+
+```python
+from dreamforge.core.providers.narrative import NarrativeRequest
+from dreamforge.integrations.openai_compat import OpenAICompatConfig, OpenAICompatProvider
+from dreamforge.integrations.transport import UrllibTransport
+
+config = OpenAICompatConfig(
+    base_url="http://127.0.0.1:11434/v1",  # Ollama loopback example
+    model="llama3.2:3b",
+    timeout_seconds=20,
+    max_retries=2,
+)
+provider = OpenAICompatProvider(config, UrllibTransport())
+response = provider.generate(request)  # request = validated NarrativeRequest
+```
+
+Guarantees (ADR 0005): allowlisted projection only; strict response schema;
+per-attempt timeout; bounded retries then fail-closed; errors redacted to
+status code + response hash; every response labeled `generative_interpretation`.
+
+An Anthropic-native adapter with the same guarantees ships alongside it
+(`AnthropicCompatProvider` — messages API, `x-api-key` +
+`anthropic-version` headers, content-block extraction); both share one
+vetted bounded-retry/redaction implementation (`integrations/retry.py`).
+
+## Dashboard (optional extras)
+
+```bash
+".venv/Scripts/python.exe" -m pip install -c constraints.txt streamlit plotly
+".venv/Scripts/python.exe" -m streamlit run src/dreamforge/visualization/dashboard.py -- exports/demo_8h
+```
+
+Renders verified exports only; accessibility/theme documentation in
+[`DASHBOARD.md`](DASHBOARD.md).
+
+## What it simulates (and what that means)
+
+- Conceptual two-process-inspired sleep-regulation equations (homeostatic "S"
+  pressure + sinusoidal circadian proxy) — mathematical constructs, not physiology.
+- A semi-Markov Wake/N1/N2/N3/REM stage process at 30-second resolution —
+  explicitly *not* PSG scoring.
+- Four normalized `[0,1]` neuromodulatory proxy indices — qualitative synthetic
+  values, never concentrations or measurements.
+- Selection over a synthetic directed weighted memory graph — graph selection,
+  not neural replay.
+- Deterministic structured features and scores derived only from the above.
+
+All parameters carry evidence grades (`assumption`, `synthetic_demo`, …) in
+[`docs/scientific_model/claim_registry.yaml`](docs/scientific_model/claim_registry.yaml).
+No empirical or clinical claim is made anywhere in this repository.
+
+## Quick start (offline demo)
+
+Requires Python 3.11+ (developed on 3.12, Windows). No network egress at runtime;
+install needs PyPI once.
+
+```bash
+python -m venv .venv
+".venv/Scripts/python.exe" -m pip install -c constraints.txt -e .   # Windows path; use .venv/bin elsewhere
+".venv/Scripts/python.exe" -m dreamforge.demo                       # runs examples/configs/demo_8h.json
+```
+
+The demo validates its configuration, runs 960 epochs, verifies stage-transition
+legality, writes an export under `exports/demo_8h/`
+(`events.ndjson` + `manifest.json`), re-imports it, and re-verifies all hashes.
+
+## Development checks
+
+```bash
+".venv/Scripts/python.exe" -m pytest -q                                            # tests
+".venv/Scripts/python.exe" -m pytest -q --cov=src/dreamforge --cov-report=term-missing
+".venv/Scripts/python.exe" -m ruff check src tests examples                        # lint
+".venv/Scripts/python.exe" -m black --check src tests examples                     # format-check
+".venv/Scripts/python.exe" -m mypy src/dreamforge/core                             # typecheck
+```
+
+## Repository layout
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the diagram and component table.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Copyright (c) 2026 JToSound.

dreamforge-0.2.0/README.md

@@ -0,0 +1,111 @@
+# DreamForge AI
+
+> DreamForge is a research and visualization simulator. It does not measure brains, diagnose conditions, predict dreams, infer psychological meaning, or provide medical advice.
+
+An open-source, deterministic, offline sandbox for simulating explicit,
+configurable, **non-clinical proxies** related to sleep regulation, sleep-stage
+dynamics, normalized neuromodulatory patterns, synthetic-memory graph
+selection, and structured dream-context features — under active construction
+toward the milestone plan in [`MASTER_PROMPT.md`](MASTER_PROMPT.md).
+
+## Status
+
+First execution slice + M1 (complete) and M2 groundwork: deterministic core with
+an 8-hour (960 × 30 s epoch) offline trace, event sourcing, DQCJ-1 canonical
+serialization, hash-verified exports, structured dream context/features/score,
+and the mandatory offline narrative provider with labeled report blocks. See
+[`ARCHITECTURE.md`](ARCHITECTURE.md), [`RESEARCH.md`](RESEARCH.md),
+[`LIMITATIONS.md`](LIMITATIONS.md), and `docs/`.
+
+**Not yet built** (by explicit scope control): API, plugins, notebooks,
+streaming/tool-use adapter features.
+
+## Optional: local / OpenAI-compatible narrative provider (opt-in)
+
+The offline mock is always the default. To use a local model via Ollama's
+OpenAI-compatible endpoint (or any `/chat/completions` service), construct the
+adapter explicitly in your own script — nothing is enabled by configuration
+alone:
+
+```python
+from dreamforge.core.providers.narrative import NarrativeRequest
+from dreamforge.integrations.openai_compat import OpenAICompatConfig, OpenAICompatProvider
+from dreamforge.integrations.transport import UrllibTransport
+
+config = OpenAICompatConfig(
+    base_url="http://127.0.0.1:11434/v1",  # Ollama loopback example
+    model="llama3.2:3b",
+    timeout_seconds=20,
+    max_retries=2,
+)
+provider = OpenAICompatProvider(config, UrllibTransport())
+response = provider.generate(request)  # request = validated NarrativeRequest
+```
+
+Guarantees (ADR 0005): allowlisted projection only; strict response schema;
+per-attempt timeout; bounded retries then fail-closed; errors redacted to
+status code + response hash; every response labeled `generative_interpretation`.
+
+An Anthropic-native adapter with the same guarantees ships alongside it
+(`AnthropicCompatProvider` — messages API, `x-api-key` +
+`anthropic-version` headers, content-block extraction); both share one
+vetted bounded-retry/redaction implementation (`integrations/retry.py`).
+
+## Dashboard (optional extras)
+
+```bash
+".venv/Scripts/python.exe" -m pip install -c constraints.txt streamlit plotly
+".venv/Scripts/python.exe" -m streamlit run src/dreamforge/visualization/dashboard.py -- exports/demo_8h
+```
+
+Renders verified exports only; accessibility/theme documentation in
+[`DASHBOARD.md`](DASHBOARD.md).
+
+## What it simulates (and what that means)
+
+- Conceptual two-process-inspired sleep-regulation equations (homeostatic "S"
+  pressure + sinusoidal circadian proxy) — mathematical constructs, not physiology.
+- A semi-Markov Wake/N1/N2/N3/REM stage process at 30-second resolution —
+  explicitly *not* PSG scoring.
+- Four normalized `[0,1]` neuromodulatory proxy indices — qualitative synthetic
+  values, never concentrations or measurements.
+- Selection over a synthetic directed weighted memory graph — graph selection,
+  not neural replay.
+- Deterministic structured features and scores derived only from the above.
+
+All parameters carry evidence grades (`assumption`, `synthetic_demo`, …) in
+[`docs/scientific_model/claim_registry.yaml`](docs/scientific_model/claim_registry.yaml).
+No empirical or clinical claim is made anywhere in this repository.
+
+## Quick start (offline demo)
+
+Requires Python 3.11+ (developed on 3.12, Windows). No network egress at runtime;
+install needs PyPI once.
+
+```bash
+python -m venv .venv
+".venv/Scripts/python.exe" -m pip install -c constraints.txt -e .   # Windows path; use .venv/bin elsewhere
+".venv/Scripts/python.exe" -m dreamforge.demo                       # runs examples/configs/demo_8h.json
+```
+
+The demo validates its configuration, runs 960 epochs, verifies stage-transition
+legality, writes an export under `exports/demo_8h/`
+(`events.ndjson` + `manifest.json`), re-imports it, and re-verifies all hashes.
+
+## Development checks
+
+```bash
+".venv/Scripts/python.exe" -m pytest -q                                            # tests
+".venv/Scripts/python.exe" -m pytest -q --cov=src/dreamforge --cov-report=term-missing
+".venv/Scripts/python.exe" -m ruff check src tests examples                        # lint
+".venv/Scripts/python.exe" -m black --check src tests examples                     # format-check
+".venv/Scripts/python.exe" -m mypy src/dreamforge/core                             # typecheck
+```
+
+## Repository layout
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the diagram and component table.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Copyright (c) 2026 JToSound.

dreamforge-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dreamforge"
+version = "0.2.0"
+description = "Deterministic, offline sandbox for non-clinical sleep/dream simulation proxies (research and visualization simulator; no medical claims)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "JToSound" }]
+dependencies = [
+    "numpy>=2,<3",
+    "pydantic>=2.7,<3",
+    "networkx>=3.3,<4",
+]
+
+[project.optional-dependencies]
+dashboard = [
+    "streamlit>=1.37",
+    "plotly>=5.22",
+]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=5,<7",
+    "hypothesis>=6,<7",
+    "ruff>=0.6",
+    "black>=24",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+dreamforge-demo = "dreamforge.demo:main"
+dreamforge-dashboard = "dreamforge.visualization.dashboard:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP"]
+ignore = []
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.mypy]
+strict = true
+files = ["src/dreamforge/core", "src/dreamforge/integrations"]
+# Checked under 3.12 semantics because numpy>=2.5 stubs use 3.12-only syntax;
+# the package runtime floor stays >=3.11 and no source uses 3.12-only features.
+python_version = "3.12"
+warn_unreachable = true
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = "networkx.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "integration: long-running deterministic integration tests",
+    "property: hypothesis property-based tests",
+]

dreamforge-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dreamforge-0.2.0/src/dreamforge/__init__.py

@@ -0,0 +1,8 @@
+"""DreamForge — deterministic research and visualization simulator.
+
+DreamForge is a research and visualization simulator. It does not measure
+brains, diagnose conditions, predict dreams, infer psychological meaning, or
+provide medical advice.
+"""
+
+__version__ = "0.2.0"

dreamforge-0.2.0/src/dreamforge/core/__init__.py

@@ -0,0 +1,6 @@
+"""DreamForge deterministic core.
+
+Nothing in this package may import FastAPI, Streamlit, LangGraph, provider
+SDKs, environment variables, clocks, filesystem/network clients, or runtime
+configuration loaders (MASTER_PROMPT.md section 3).
+"""

dreamforge-0.2.0/src/dreamforge/core/config.py

@@ -0,0 +1,142 @@
+"""Strict simulation configuration loading (fail closed).
+
+The configuration is the only external input to a run. It is validated into
+frozen Pydantic models before any engine object is constructed; any violation
+raises :class:`ConfigError` with a machine-readable ``code``. No environment
+variables, clocks, or network access participate.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from dreamforge.core.models.events import ALL_STAGES, StageName
+from dreamforge.core.models.memory_graph import GraphSpecConfig, ReplaySelectorConfig
+from dreamforge.core.models.neurochemistry import NeurochemistryConfig
+from dreamforge.core.models.sleep_cycle import (
+    CircadianConfig,
+    DwellDistribution,
+    ProcessSConfig,
+    TransitionMatrixConfig,
+)
+
+#: Hard limits guarding against oversized/hostile configs (section 6.3).
+MAX_EPOCH_SECONDS = 3600.0
+MIN_EPOCH_SECONDS = 1.0
+MAX_TOTAL_TICKS = 100_000
+
+
+class ConfigError(ValueError):
+    """Raised when configuration fails validation; ``code`` is stable."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class ReplayPolicyConfig(BaseModel):
+    """Where replay selection gets its graph and its policy."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    synthetic_graph: GraphSpecConfig = Field(default_factory=GraphSpecConfig)
+    selector: ReplaySelectorConfig = Field(default_factory=ReplaySelectorConfig)
+    replay_every_n_epochs: int = Field(default=8, ge=1)
+
+
+class SimulationConfig(BaseModel):
+    """Fully validated run configuration (immutable after load)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: str = Field(pattern=r"^\d+\.\d+$")
+    run_id: str = Field(min_length=8, max_length=64, pattern=r"^[A-Za-z0-9._-]+$")
+    run_seed: int = Field(ge=0, le=2**64 - 1)
+    epoch_seconds: float = Field(default=30.0)
+    total_ticks: int = Field(ge=1)
+    initial_stage: StageName = "Wake"
+    process_s: ProcessSConfig = Field(default_factory=ProcessSConfig)
+    circadian: CircadianConfig = Field(default_factory=CircadianConfig)
+    transitions: TransitionMatrixConfig
+    dwells: dict[StageName, DwellDistribution]
+    chemistry: NeurochemistryConfig
+    replay_policy: ReplayPolicyConfig = Field(default_factory=ReplayPolicyConfig)
+
+    @field_validator("epoch_seconds")
+    @classmethod
+    def _epoch_bounds(cls, value: float) -> float:
+        if not MIN_EPOCH_SECONDS <= value <= MAX_EPOCH_SECONDS:
+            msg = f"epoch_seconds must be within " f"[{MIN_EPOCH_SECONDS}, {MAX_EPOCH_SECONDS}]"
+            raise ValueError(msg)
+        return value
+
+    @field_validator("total_ticks")
+    @classmethod
+    def _ticks_cap(cls, value: int) -> int:
+        if value > MAX_TOTAL_TICKS:
+            msg = f"total_ticks exceeds MAX_TOTAL_TICKS={MAX_TOTAL_TICKS}"
+            raise ValueError(msg)
+        return value
+
+    @model_validator(mode="after")
+    def _dwell_support(self) -> SimulationConfig:
+        missing = [s for s in ALL_STAGES if s not in self.dwells]
+        if missing:
+            msg = f"dwells missing stages: {missing}"
+            raise ValueError(msg)
+        for stage, dwell in self.dwells.items():
+            longest = dwell.min_epochs + len(dwell.weights) - 1
+            if longest > self.total_ticks:
+                msg = f"dwell support for {stage} exceeds total_ticks"
+                raise ValueError(msg)
+        return self
+
+    def simulated_time_minutes(self, tick: int) -> float:
+        """Documented conversion: tick × epoch_seconds / 60."""
+        return tick * self.epoch_seconds / 60.0
+
+
+def dumps_config_canonical(config: SimulationConfig) -> bytes:
+    """Canonical configuration snapshot bytes (embedded into exports).
+
+    Lives here rather than in the simulation package so that export/import
+    verification never needs to load the engine module at all.
+    """
+    from dreamforge.core.serialization.dqcj import dumps_canonical
+
+    return dumps_canonical(config.model_dump(mode="json"))
+
+
+def load_config(source: str | Path | dict[str, Any]) -> SimulationConfig:
+    """Load and strictly validate a run configuration.
+
+    ``source`` may be an already-parsed dict or a path to UTF-8 JSON. Raises
+    :class:`ConfigError` on any violation (schema, ranges, structure).
+    """
+    if isinstance(source, dict):
+        raw = source
+    else:
+        path = Path(source)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            msg = f"config file unreadable: {exc.__class__.__name__}"
+            raise ConfigError("config_unreadable", msg) from exc
+        from dreamforge.core.serialization.dqcj import loads_strict
+
+        try:
+            raw = loads_strict(text)
+        except ValueError as exc:
+            raise ConfigError("config_invalid_json", str(exc)) from exc
+        if not isinstance(raw, dict):
+            raise ConfigError(
+                "config_invalid_json",
+                "top-level configuration must be a JSON object",
+            )
+    try:
+        return SimulationConfig.model_validate(raw)
+    except Exception as exc:  # noqa: BLE001 - re-raised typed below
+        raise ConfigError("config_validation_failed", str(exc)) from exc

dreamforge-0.2.0/src/dreamforge/core/models/__init__.py

@@ -0,0 +1 @@
+"""Domain models: sleep cycle, neurochemistry, memory graph, events."""