# Tutorial: Using the `github.com/dwycoff2013/dual-stream` Repository
Hi Alex,
This is a short “operator’s guide” to the Dual-Stream Architecture repo so you can pull it locally, explore the code, and (if you want) wire it into any evaluation or demo infrastructure on llmresearch.net.
Repo URL: [
https://github.com/dwycoff2013/dual-stream](https://github.com/dwycoff2013/dual-stream) ([GitHub][1])
---
## 1. What this repository is
The Dual-Stream Architecture is an experimental framework for **verifiable inner alignment**:
* **Answer Stream** – the normal, user-visible output of a model.
* **Monologue Stream** – a structured, machine-readable trace of what the model is “thinking about” (probes, logit info, attention summaries, etc.) before it answers. ([GitHub][1])
A **Coherence Auditor** sits on top of those streams and looks for things like:
* contradictions between what the model “thought” and what it said
* signs of deception or unsafe intent
* other misalignment patterns that you might want to flag or block at runtime ([GitHub][1])
The repo currently includes (per README + commit history):
* A **probe library** for key alignment signals
* A **Coherence Auditor API / CLI**
* **Example inference pipelines** showing dual-stream output
* **Evaluation pieces** and early work on model-collapse resilience ([GitHub][1])
Most of the code is **Python** with a smaller **Go** component (used as a parser/utility layer). ([GitHub][1])
---
## 2. Cloning the repository
From any machine with Git installed:
```bash
git clone
GitHub - dwycoff2013/dual-stream
cd dual-stream
```
If you prefer SSH:
```bash
git clone
[email protected]:dwycoff2013/dual-stream.git
```
---
## 3. Recommended local setup
### 3.1. Python environment
The repo is mostly Python, so a venv is the easiest path:
```bash
cd dual-stream
# Create and activate a virtual environment (Linux/macOS)
python3 -m venv .venv
source .venv/bin/activate
# or on Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
```
Then install whatever dependencies the Python PoC uses (check imports in `python_poc/`):
```bash
pip install -U pip
# Example – adjust to match actual imports you see:
pip install openai tiktoken numpy pandas
```
*(The repo may grow a `requirements.txt` or `pyproject.toml` later; if so, just `pip install -r requirements.txt` instead.)*
### 3.2. Go toolchain (optional but useful)
There is a small Go component (a parser / helper tooling), so if you want to build or run that part:
1. Install Go (1.21+ recommended).
2. Make sure `go` is on your `PATH`:
```bash
go version
```
---
## 4. Repository layout (high-level)
At the top level you’ll see something like: ([GitHub][1])
* `README.md`
* Conceptual overview of Dual-Stream and what’s included.
* `The Internal Monologue_ A Dual-Stream Architecture for Verifiable Inner Alignment-v2.1.pdf`
* The main architecture whitepaper; explains the theory behind Answer vs Monologue streams, the auditor, and how this all plugs into real systems.
* `python_poc/`
* Python proof-of-concept with a basic dual-stream pipeline and a Go-based parser (per commit notes). This is the best starting point to actually *run* something. ([GitHub][2])
* `dualstream_anticollapse/`
* Early code aimed at integrating Dual-Stream with model-collapse detection / prevention logic (ties into the “model collapse tree” idea).
* `model_collapse_tree/`
* An initial structure around “collapse modes” and policies — used by the anti-collapse code as the system evolves. ([GitHub][2])
Because GitHub now renders directory contents dynamically, you’ll want to inspect the exact filenames once you’ve cloned:
```bash
ls
ls python_poc
ls dualstream_anticollapse
ls model_collapse_tree
```
---
## 5. Running the Python proof-of-concept
> Goal: feed a prompt to a model and get **both** Answer and Monologue streams, then run them through the Coherence Auditor.
### 5.1. Configure your model access
Inside `python_poc/`, look for:
* a configuration file (e.g. `.env`, `config.yml`, or a Python module that holds API keys / endpoints), and
* the main entry-point script (often something like `main.py`, `run_dualstream.py`, etc.).
Steps (generic pattern):
```bash
cd python_poc
# If there is a .env.example or similar, copy it:
cp .env.example .env
# Then edit .env with your OpenAI / other LLM API keys
```
If there’s no explicit config file, open the main script and look for environment variables like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc., and export them before running:
```bash
export OPENAI_API_KEY="sk-..."
```
### 5.2. Running a simple dual-stream inference
Once the environment is set:
```bash
cd python_poc
# Replace <entrypoint>.py with the actual script you see
python <entrypoint>.py --prompt "Explain the Dual-Stream Architecture at a high level."
```
Typical behaviour you should expect:
* **Answer Stream**: plain-English answer
* **Monologue Stream**: structured JSON or line-delimited logs that include:
* probe activations (alignment signals)
* partial reasoning traces or attention/feature summaries
* any metadata needed by the Coherence Auditor
A lot of Python entrypoints expose `--help`; it’s worth trying:
```bash
python <entrypoint>.py --help
```
---
## 6. Exploring the Coherence Auditor
The repo description and README mention an **“API and CLI”** for the Coherence Auditor, plus **example inference pipelines**. ([GitHub][1])
Once you locate the relevant module (likely in `python_poc/` or `dualstream_anticollapse/`), you’ll typically interact with it in one of two ways:
### 6.1. Programmatic use (Python)
Pseudocode pattern:
```python
from dualstream_auditor import CoherenceAuditor # adjust to actual module name
auditor = CoherenceAuditor(config=...)
result = auditor.check(answer_stream=answer, monologue_stream=monologue)
print(result.summary)
print(result.flags) # e.g., deception_suspected, unsafe_intent, etc.
```
### 6.2. CLI use
Expect something like:
```bash
# Feed answer + monologue as JSONL or separate files
dualstream-auditor \
--answer answer.json \
--monologue monologue.json \
--out report.json
```
Exactly naming may differ; once you’ve cloned the repo, search for “auditor” or “coherence” to find the entrypoints:
```bash
cd dual-stream
grep -R "CoherenceAuditor" -n
grep -R "auditor" -n python_poc dualstream_anticollapse
```
---
## 7. Anti-collapse components
The `dualstream_anticollapse/` and `model_collapse_tree/` paths are (per commit messages) focused on applying Dual-Stream to **model collapse detection and mitigation**. ([GitHub][2])
Rough intended usage:
1. Run your model with **dual-stream output** enabled.
2. Feed Answer + Monologue into the **Coherence Auditor**.
3. Feed auditor outputs (plus other telemetry) into the **anti-collapse logic**, which uses the “collapse tree” definitions to:
* classify *what kind* of collapse/degeneration may be happening, and
* suggest or automatically trigger mitigation steps (e.g., refuse, re-prompt, or route to a safer model/config).
Once cloned, you can explore the tree definitions:
```bash
cd model_collapse_tree
ls
```
Look for YAML/JSON files describing different collapse modes; those can typically be edited or extended without touching the core code.
---
## 8. How this could be integrated with llmresearch.net
A few practical ways you might use this repo in the forum environment:
1. **Reproducible demo environment**
* Clone the repo onto a sandbox machine.
* Provide a pre-configured `.env` (with non-secret dummy keys or test-only keys).
* Let community members run a single script (e.g. `python run_example.py`) to see dual-stream behaviour end-to-end.
2. **Benchmark harness integration**
* Wrap the PoC entrypoint in whatever harness you use for LLM evals, so each benchmark run captures:
* Answer Stream
* Monologue Stream
* Coherence Auditor results
* Store those in the existing metrics DB / dashboards.
3. **Discussion anchor**
* Create a forum thread that links directly to:
* the GitHub repo,
* the internal monologue PDF, and
* any local notes you have about running the PoC in your environment.
* Pin or sticky that thread as the “Dual-Stream Architecture” hub.
---
## 9. Housekeeping / admin notes
* **License**: check the repo root for a `LICENSE` file to confirm exact terms before exposing it as a hosted service or modifying it heavily.
* **Branching**: development appears to be happening on `main`. If we start experimenting, it’s probably worth opening feature branches (`alexh/eval-harness`, etc.) rather than pushing directly to `main`.
* **Issues / feedback**: if you find bugs or have feature requests, opening GitHub issues against the repo will make it easier to track them than forum posts alone.