dark-research-lab 0.1.0__tar.gz

dark_research_lab-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+*.env
+# Dolt database files (added by bd init)
+.dolt/
+*.db
+
+# Python bytecode
+**/__pycache__/
+*.pyc
+
+# Build artifacts
+go/dist/
+go/drl
+dist/
+*.egg-info/
+
+# Bundled Go binary (copied by hatch build hook)
+python/drl/drl
+python/drl/drl.exe
+
+# Agent cache files
+**/.claude/.cache/
+
+# Agent runtime logs
+agent_logs/
+
+# Credential keys
+.beads/.beads-credential-key
+
+# Ephemeral hook state
+.claude/.drl-last-phase
+.drl-phase-state.json
+
+# Stale worktree debris
+drltmp/
+
+# LaTeX build artifacts
+paper/*.aux
+paper/*.log
+paper/*.bbl
+paper/*.blg
+paper/*.out
+paper/*.toc
+paper/*.synctex.gz
+paper/*.pdf
+paper/sections/*.aux
+
+# Reproducibility manifest (generated)
+paper/repro_manifest.json

dark_research_lab-0.1.0/AGENTS.md

@@ -0,0 +1,246 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+
+## DRL Research Workflow
+
+This project is an autonomous research paper factory. Agents operate within a structured research pipeline.
+
+### Research Agent Roles
+
+#### Skills (orchestration roles -- not agent files)
+
+| Role | Skill File (from project root) | Responsibility |
+|------|-------------------------------|---------------|
+| Research Architect | `.claude/skills/drl/research-architect/SKILL.md` | Decomposes research questions into epics with methodology specs |
+
+#### Agents (spawnable subagent definitions)
+
+| Role | Agent File (from project root) | Responsibility |
+|------|-------------------------------|---------------|
+| Research Analyst | `.claude/agents/drl/analyst.md` | Executes statistical analysis with Polars, produces tables/figures |
+| Literature Analyst | `.claude/agents/drl/literature-analyst.md` | Surveys existing research via PDF + RAG pipeline |
+| Methodology Reviewer | `.claude/agents/drl/methodology-reviewer.md` | Audits statistical methods and causal inference validity |
+| Robustness Checker | `.claude/agents/drl/robustness-checker.md` | Verifies findings hold under alternative specifications |
+| Coherence Reviewer | `.claude/agents/drl/coherence-reviewer.md` | Ensures logical consistency across paper sections |
+| Reproducibility Verifier | `.claude/agents/drl/reproducibility-verifier.md` | Validates all outputs can be independently reproduced |
+| Citation Checker | `.claude/agents/drl/citation-checker.md` | Verifies citation accuracy and bibliography completeness |
+| Writing Quality Reviewer | `.claude/agents/drl/writing-quality-reviewer.md` | Evaluates academic writing clarity and publication standards |
+| Advisory Fleet | (external CLIs) | Multi-model review (Claude + Gemini + Codex) for critical decisions |
+
+### Decision Logging
+
+All agents MUST log methodological decisions to `docs/decisions/` (from project root) using the ADR template (`docs/decisions/0000-template.md`). Use `/drl:decision` for guided logging. Before making a choice between statistical methods, data sources, or analytical approaches, create an ADR with alternatives considered and rationale.
+
+### Research Phases
+
+Research follows the compound-agent cook-it workflow adapted for academic work:
+
+| Phase | Skill File (from project root) | Gate |
+|-------|-----------|------|
+| Spec | `.claude/skills/drl/research-spec/SKILL.md` | RQ + hypotheses approved |
+| Plan | `.claude/skills/drl/research-plan/SKILL.md` | Methodology approved |
+| Work | `.claude/skills/drl/research-work/SKILL.md` | All analyses complete |
+| Review | `.claude/skills/drl/methodology-review/SKILL.md` | All checks pass |
+| Synthesis | `.claude/skills/drl/synthesis/SKILL.md` | Paper compiles + all refs resolve |
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work atomically
+bd close <id>         # Complete work
+bd dolt push          # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+<!-- BEGIN BEADS INTEGRATION profile:full hash:d4f96305 -->
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Dolt-powered version control with native sync
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+
+```bash
+bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
+bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
+```
+
+**Claim and update:**
+
+```bash
+bd update <id> --claim --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task atomically**: `bd update <id> --claim`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+
+### Auto-Sync
+
+bd automatically syncs via Dolt:
+
+- Each write auto-commits to Dolt history
+- Use `bd dolt push`/`bd dolt pull` for remote sync
+- No manual export/import needed!
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, see README.md and docs/QUICKSTART.md.
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+
+<!-- END BEADS INTEGRATION -->
+<!-- compound-agent:start -->
+## Compound Agent Integration
+
+This project uses compound-agent for session memory via **CLI commands**.
+
+### CLI Commands (ALWAYS USE THESE)
+
+**You MUST use CLI commands for lesson management:**
+
+| Command | Purpose |
+|---------|---------|
+| `ca search "query"` | Search lessons - MUST call before architectural decisions; use anytime you need context |
+| `ca knowledge "query"` | Semantic search over project docs - MUST call before architectural decisions; use keyword phrases, not questions |
+| `ca learn "insight"` | Capture lessons - use AFTER corrections or discoveries |
+| `ca list` | List all stored lessons |
+| `ca show <id>` | Show details of a specific lesson |
+| `ca wrong <id>` | Mark a lesson as incorrect |
+
+### Mandatory Recall
+
+You MUST call `ca search` and `ca knowledge` BEFORE:
+- Architectural decisions or complex planning
+- Patterns you've implemented before in this repo
+- After user corrections ("actually...", "wrong", "use X instead")
+
+**NEVER skip search for complex decisions.** Past mistakes will repeat.
+
+Beyond mandatory triggers, use these commands freely — they are lightweight queries, not heavyweight operations. Uncertain about a pattern? `ca search`. Need a detail from the docs? `ca knowledge`. The cost of an unnecessary search is near-zero; the cost of a missed one can be hours.
+
+### Capture Protocol
+
+Run `ca learn` AFTER:
+- User corrects you
+- Test fail -> fix -> pass cycles
+- You discover project-specific knowledge
+
+**Workflow**: Search BEFORE deciding, capture AFTER learning.
+
+### Quality Gate
+
+Before capturing, verify the lesson is:
+- **Novel** - Not already stored
+- **Specific** - Clear guidance
+- **Actionable** (preferred) - Obvious what to do
+
+### Never Edit JSONL Directly
+
+**WARNING: NEVER edit .claude/lessons/index.jsonl directly.**
+
+The JSONL file requires proper ID generation, schema validation, and SQLite sync.
+Use CLI (`ca learn`) — never manual edits.
+
+See [documentation](https://github.com/Nathandela/compound-agent) for more details.
+<!-- compound-agent:end -->

dark_research_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathandela
+
+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.

dark_research_lab-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: dark-research-lab
+Version: 0.1.0
+Summary: Dark Research Lab - autonomous research paper factory
+Project-URL: Homepage, https://github.com/Nathandela/dark-research-lab
+Project-URL: Repository, https://github.com/Nathandela/dark-research-lab
+Project-URL: Issues, https://github.com/Nathandela/dark-research-lab/issues
+Author: Nathan Delacretaz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,latex,reproducibility,research,social-science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: pymupdf>=1.24.0
+Description-Content-Type: text/markdown
+
+# DRL -- Dark Research Lab
+
+Autonomous research paper factory for social science. Turn a git repo into a
+reproducible academic paper with AI-driven analysis, literature indexing, and
+LaTeX compilation.
+
+## Install
+
+```bash
+uv pip install drl
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# Initialize a new research project
+drl setup
+
+# Walk through configuration
+/drl:onboard
+
+# Customize for your field (labor economics, political science, etc.)
+/drl:flavor
+
+# Index literature -- drop PDFs into literature/pdfs/, then:
+drl index
+
+# Decompose your research question into epics
+/drl:architect
+
+# Run the full pipeline (spec -> plan -> work -> review -> synthesis)
+drl loop
+```
+
+## How It Works
+
+DRL wraps [compound-agent](https://github.com/Nathandela/compound-agent) with
+research-specific skills, agents, and guardrails:
+
+```
+Researcher
+    |
+    v
+ drl CLI (Go binary in a Python wheel)
+    |
+    +-- Claude Code (executes skills/agents)
+    +-- Beads (epic tracking with dependency graphs)
+    +-- Literature RAG (PDF extraction + embedding via ca-embed)
+    +-- LaTeX toolchain (3-pass pdflatex + bibtex)
+    +-- Advisory Fleet (optional: Gemini, Codex reviewers)
+```
+
+Each research question passes through a **cook-it cycle**:
+1. **Spec** -- research question, hypotheses, literature gap
+2. **Plan** -- methodology, variables, statistical models
+3. **Work** -- analysis, tables, figures, section drafting
+4. **Review** -- methodology audit + external model review
+5. **Synthesis** -- lessons captured, paper section finalized
+
+Every methodological decision is logged to `docs/decisions/` for full
+traceability. A reproducibility package (lockfile + data manifest + run script)
+is generated at compilation time.
+
+## Project Structure
+
+```
+paper/          LaTeX source and compiled outputs
+src/            Analysis scripts
+literature/     PDFs and indexed knowledge base
+docs/           Decisions, specs, agent notes
+tests/          Test suite
+.claude/        Skills, agents, hooks, commands
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `drl setup` | Initialize or update project templates |
+| `drl index` | Index literature PDFs for RAG search |
+| `drl loop` | Run infinity loop over all epics |
+| `/drl:compile` | Compile LaTeX paper + reproducibility package |
+| `/drl:flavor` | Customize skills for your research field |
+| `/drl:onboard` | Guided first-time setup |
+| `/drl:architect` | Decompose research question into epics |
+
+## Documentation
+
+- [System Specification](docs/specs/drl-package.md)
+- [Architecture Decisions](docs/decisions/)
+- [Agent Configuration](AGENTS.md)
+
+## License
+
+[MIT](LICENSE)

dark_research_lab-0.1.0/README.md

@@ -0,0 +1,97 @@
+# DRL -- Dark Research Lab
+
+Autonomous research paper factory for social science. Turn a git repo into a
+reproducible academic paper with AI-driven analysis, literature indexing, and
+LaTeX compilation.
+
+## Install
+
+```bash
+uv pip install drl
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# Initialize a new research project
+drl setup
+
+# Walk through configuration
+/drl:onboard
+
+# Customize for your field (labor economics, political science, etc.)
+/drl:flavor
+
+# Index literature -- drop PDFs into literature/pdfs/, then:
+drl index
+
+# Decompose your research question into epics
+/drl:architect
+
+# Run the full pipeline (spec -> plan -> work -> review -> synthesis)
+drl loop
+```
+
+## How It Works
+
+DRL wraps [compound-agent](https://github.com/Nathandela/compound-agent) with
+research-specific skills, agents, and guardrails:
+
+```
+Researcher
+    |
+    v
+ drl CLI (Go binary in a Python wheel)
+    |
+    +-- Claude Code (executes skills/agents)
+    +-- Beads (epic tracking with dependency graphs)
+    +-- Literature RAG (PDF extraction + embedding via ca-embed)
+    +-- LaTeX toolchain (3-pass pdflatex + bibtex)
+    +-- Advisory Fleet (optional: Gemini, Codex reviewers)
+```
+
+Each research question passes through a **cook-it cycle**:
+1. **Spec** -- research question, hypotheses, literature gap
+2. **Plan** -- methodology, variables, statistical models
+3. **Work** -- analysis, tables, figures, section drafting
+4. **Review** -- methodology audit + external model review
+5. **Synthesis** -- lessons captured, paper section finalized
+
+Every methodological decision is logged to `docs/decisions/` for full
+traceability. A reproducibility package (lockfile + data manifest + run script)
+is generated at compilation time.
+
+## Project Structure
+
+```
+paper/          LaTeX source and compiled outputs
+src/            Analysis scripts
+literature/     PDFs and indexed knowledge base
+docs/           Decisions, specs, agent notes
+tests/          Test suite
+.claude/        Skills, agents, hooks, commands
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `drl setup` | Initialize or update project templates |
+| `drl index` | Index literature PDFs for RAG search |
+| `drl loop` | Run infinity loop over all epics |
+| `/drl:compile` | Compile LaTeX paper + reproducibility package |
+| `/drl:flavor` | Customize skills for your research field |
+| `/drl:onboard` | Guided first-time setup |
+| `/drl:architect` | Decompose research question into epics |
+
+## Documentation
+
+- [System Specification](docs/specs/drl-package.md)
+- [Architecture Decisions](docs/decisions/)
+- [Agent Configuration](AGENTS.md)
+
+## License
+
+[MIT](LICENSE)

dark_research_lab-0.1.0/go/.golangci.yml

@@ -0,0 +1,81 @@
+version: "2"
+run: {}
+linters:
+  enable:
+    - cyclop
+    - funlen
+    - gosec
+    - revive
+  settings:
+    cyclop:
+      max-complexity: 10
+    funlen:
+      lines: 50
+      statements: 40
+    gosec:
+      includes:
+        - G201
+        - G202
+    revive:
+      rules:
+        - name: blank-imports
+        - name: context-as-argument
+        - name: context-keys-type
+        - name: dot-imports
+        - name: error-return
+        - name: error-strings
+        - name: error-naming
+        - name: exported
+        - name: if-return
+        - name: increment-decrement
+        - name: var-naming
+        - name: package-comments
+          disabled: true
+        - name: range
+        - name: receiver-naming
+        - name: time-naming
+        - name: unexported-return
+        - name: indent-error-flow
+        - name: errorf
+        - name: empty-block
+        - name: superfluous-else
+        - name: unreachable-code
+        - name: redefines-builtin-id
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    rules:
+      - linters:
+          - funlen
+        path: _test\.go
+      - linters:
+          - cyclop
+        path: _test\.go
+      - linters:
+          - errcheck
+        path: _test\.go
+      - linters:
+          - revive
+        path: _test\.go
+        text: dot-imports
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$

dark_research_lab-0.1.0/go/Makefile

@@ -0,0 +1,70 @@
+DIST      := dist
+VERSION   := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+COMMIT    := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+LDFLAGS   := -s -w -X github.com/nathandelacretaz/dark-research-lab/internal/build.Version=$(VERSION) \
+             -X github.com/nathandelacretaz/dark-research-lab/internal/build.Commit=$(COMMIT)
+RUST_DIR  := ../rust/embed-daemon
+
+PLATFORMS := darwin-arm64 darwin-amd64 linux-arm64 linux-amd64 windows-amd64 windows-arm64
+
+.PHONY: build build-release build-all build-daemon build-daemon-all test test-integration lint clean
+
+# Build for local platform (development).
+build:
+	go build -o drl ./cmd/drl
+
+# Build for local platform with version injection and stripped symbols.
+build-release:
+	go build -ldflags '$(LDFLAGS)' -o $(DIST)/drl ./cmd/drl
+
+# Cross-compile Go binary for all platforms.
+# Pure Go (CGO_ENABLED=0) — no C cross-compiler needed.
+build-all: $(DIST)
+	@for platform in $(PLATFORMS); do \
+		os=$${platform%%-*}; \
+		arch=$${platform##*-}; \
+		ext=""; \
+		if [ "$$os" = "windows" ]; then ext=".exe"; fi; \
+		echo "Building drl-$${platform}$${ext}..."; \
+		CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch \
+			go build -ldflags '$(LDFLAGS)' \
+			-o $(DIST)/drl-$$platform$$ext ./cmd/drl || exit 1; \
+	done
+
+# Build Rust embed-daemon for local platform.
+build-daemon:
+	cd $(RUST_DIR) && cargo build --release
+	@mkdir -p $(DIST)
+	cp $(RUST_DIR)/target/release/drl-embed $(DIST)/drl-embed
+
+# Cross-compile Rust embed-daemon for all platforms.
+# Requires rustup target add for each target triple.
+build-daemon-all: $(DIST)
+	@for platform in $(PLATFORMS); do \
+		case $$platform in \
+			windows-*) continue ;; \
+			darwin-arm64) triple="aarch64-apple-darwin" ;; \
+			darwin-amd64) triple="x86_64-apple-darwin" ;; \
+			linux-arm64)  triple="aarch64-unknown-linux-gnu" ;; \
+			linux-amd64)  triple="x86_64-unknown-linux-gnu" ;; \
+		esac; \
+		echo "Building embed-daemon-$$platform ($$triple)..."; \
+		cd $(RUST_DIR) && cargo build --release --target $$triple || exit 1; \
+		cp $(RUST_DIR)/target/$$triple/release/drl-embed $(DIST)/drl-embed-$$platform; \
+	done
+
+test:
+	go test ./...
+
+test-integration:
+	go test -tags integration ./...
+
+lint:
+	go vet ./...
+
+clean:
+	rm -rf $(DIST) drl
+	rm -rf $(RUST_DIR)/target
+
+$(DIST):
+	@mkdir -p $(DIST)