blackroad-os-research/notebooks/README.md

Notebooks

This directory contains Jupyter notebooks and exploratory analysis scripts for BlackRoad OS research.

Organization

Notebooks are organized by research domain:

• sig/ - Spiral Information Geometry explorations

  • Coordinate transforms
  • Distance metrics
  • Factor tree visualizations
  • Embedding analysis

• qlm/ - Quantum Language Model experiments

  • Entanglement proxies
  • Superposition models
  • Interference patterns

• orchestration/ - Orchestration strategy prototypes

  • Contradiction resolution
  • Agent coordination
  • Workflow experiments

Style Guide

Please follow the Notebook Style Guide when creating notebooks.

Quick Checklist

Every notebook should have:

• Header cell with purpose, dependencies, and data sources
• Organized imports
• Centralized configuration
• Markdown cells explaining each section
• Labeled visualizations
• Small datasets (or references to external data)
• Cross-references to related papers/experiments

Creating a New Notebook

1. Choose the appropriate domain subdirectory
2. Name your notebook descriptively: descriptive-name.ipynb
3. Copy the header template from the style guide
4. Document your dependencies
5. Link to related papers and experiments

Data

Notebooks should use:

• Small synthetic datasets
• Sampled data (< 1000 rows typically)
• References to external data sources (documented in code)

Never commit large datasets directly in notebooks.

Outputs

Clear large outputs before committing:

• Use "Cell > All Output > Clear" for notebooks with heavy outputs
• Save important results to files instead of displaying in cells
• Keep only essential visualizations embedded

Related Documentation

• Research Overview
• Notebook Style Guide
• Experiment Template