4ee3da3bf7
Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
122 lines
3.9 KiB
Markdown
122 lines
3.9 KiB
Markdown
# Research Overview
|
|
|
|
Welcome to the **BlackRoad OS Research Lab** 🧪🧠
|
|
|
|
This repository serves as the R&D hub for BlackRoad OS, containing theory, experiments, and conceptual foundations that inform production implementations.
|
|
|
|
## 📁 Repository Structure
|
|
|
|
### Core Directories
|
|
|
|
- **`/papers`** - Research papers and theoretical foundations
|
|
- Text-based research (Markdown, LaTeX)
|
|
- Organized by domain (SIG, QLM, agents, PS-SHA∞, etc.)
|
|
- Each paper should include: abstract, motivation, definitions, and links to experiments
|
|
|
|
- **`/notebooks`** - Jupyter notebooks and exploratory scripts
|
|
- `sig/` - Spiral Information Geometry explorations
|
|
- `qlm/` - Quantum Language Model experiments
|
|
- `orchestration/` - Orchestration strategy prototypes
|
|
- Each notebook should start with a header cell explaining purpose and dependencies
|
|
|
|
- **`/experiments`** - Structured experiment folders
|
|
- Use format: `domain/experiment-YYYY-MM-DD-name/`
|
|
- Each experiment must include:
|
|
- `README.md` (what, why, how, results, next steps)
|
|
- `config.json` or `config.yaml` (parameters)
|
|
- `results/` (summaries, small plots, findings)
|
|
|
|
- **`/src`** - Reusable research utilities (NOT production code)
|
|
- Geometry helpers
|
|
- Metrics and evaluation tools
|
|
- Model wrappers
|
|
- Must be typed and documented
|
|
|
|
- **`/data`** - Metadata and references only
|
|
- NO large datasets in the repo
|
|
- Document external data sources in `data/README.md`
|
|
- Only small samples or synthetic data
|
|
|
|
- **`/schemas`** - JSON Schemas for core concepts
|
|
- **`/glossary`** - Canonical definitions and symbol tables
|
|
- **`/meta`** - Repository-level documentation and conventions
|
|
|
|
## 🎯 What Belongs Here
|
|
|
|
✅ **YES:**
|
|
- Theoretical papers and conceptual models
|
|
- Experimental prototypes and simulations
|
|
- Research notebooks with analysis
|
|
- Schemas and formal specifications
|
|
- Glossaries and reference materials
|
|
- Small synthetic datasets
|
|
|
|
❌ **NO:**
|
|
- Production API implementations
|
|
- Live services or web UIs
|
|
- Large datasets or binaries
|
|
- Secrets or API keys
|
|
- Messy, unstructured dumps
|
|
|
|
## 📝 Adding New Research
|
|
|
|
### Adding a Paper
|
|
|
|
1. Create a new file in `/papers/{domain}/`
|
|
2. Use frontmatter with: title, date, status, tags, version
|
|
3. Include: abstract, motivation, definitions, related work
|
|
4. Link to supporting experiments and notebooks
|
|
5. Add entry to `/index.md`
|
|
|
|
### Adding an Experiment
|
|
|
|
1. Create folder: `/experiments/{domain}/experiment-{date}-{name}/`
|
|
2. Add `README.md` answering:
|
|
- What question are we exploring?
|
|
- What setup/data/models were used?
|
|
- What metrics did we track?
|
|
- What did we learn?
|
|
- What should we try next?
|
|
3. Include `config.json` with parameters
|
|
4. Store results in `results/` subdirectory
|
|
5. Reference from related papers
|
|
|
|
### Adding a Notebook
|
|
|
|
1. Create in `/notebooks/{domain}/`
|
|
2. Start with header cell explaining:
|
|
- Purpose
|
|
- Dependencies
|
|
- Data sources
|
|
3. Use small datasets or samples
|
|
4. Avoid committing large outputs
|
|
5. Reference from experiments or papers
|
|
|
|
## 🔗 Cross-Repository Relationships
|
|
|
|
This repository **informs** but does not directly implement:
|
|
|
|
- **blackroad-os-core** - Types and core contracts inspired by research
|
|
- **blackroad-os-operator** - Orchestration strategies tested here
|
|
- **blackroad-os-docs** - User-facing documentation of concepts
|
|
|
|
Use text references, not code dependencies.
|
|
|
|
## ✅ Pre-Commit Checklist
|
|
|
|
Before committing:
|
|
|
|
- [ ] Files are text-based (no huge binaries)
|
|
- [ ] New experiments have clear README and config
|
|
- [ ] Notebooks have explanatory headers
|
|
- [ ] No secrets, API keys, or private data
|
|
- [ ] Research code is typed and documented
|
|
- [ ] Papers and experiments are cross-linked
|
|
|
|
## 🧭 Need Help?
|
|
|
|
- See `/docs/experiment-template.md` for experiment structure
|
|
- See `/docs/notebook-style-guide.md` for notebook conventions
|
|
- Check `/index.md` for a curated research map
|
|
- Review `/glossary/concepts.md` for standard definitions
|