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.
