Research Timeline

Track, visualize, and export research timelines — from first AI interaction to scientific discovery.

research-timeline documents the process of research, not just its artifacts: every milestone of a project (the first AI interaction that shaped the protocol, the first QPU commit with its evidence, pivots, controls, submissions, publications) is recorded in a single versioned JSON file with typed events, quantitative metrics, and supporting evidence.

Features

• Typed events — T0, T1…Tn, pivot, control, submission, publication, milestone
• Metrics — attach any quantitative result (z-scores, shots, backend, MI, …) to an event
• Evidence — git commits, IBM Quantum job IDs, data links, code links
• AI-role disclosure — each timeline declares how AI was used (cognitive_prosthesis, co_pilot, autonomous_agent)
• Exports — LaTeX table (papers/reports), Markdown, standalone HTML, schema.org JSON-LD
• Validate — structural checks with CI-friendly exit codes
• Simple JSON storage — human readable, diff-friendly, git-native, zero lock-in

Installation

pip install research-timeline
# or from source:
pip install git+https://github.com/Strugiss/research-timeline.git
# or editable for development:
pip install -e .

Usage

# Initialize a timeline
research-timeline init --output timeline.json

# Log a typed event (with metrics and evidence)
research-timeline log T1 --desc "First commit: 14 QPU experiments, Z>50sigma" \
  --z-combined 50.0 --git-commit c3ddc4a --job-ids abc,def --tags commit,qpu

# List events (optionally with metrics)
research-timeline list --metrics

# Export to LaTeX (papers), Markdown, HTML, or JSON-LD
research-timeline export --format latex -o timeline.tex
research-timeline export --format markdown -o timeline.md
research-timeline export --format html -o timeline.html
research-timeline export --format jsonld -o timeline.jsonld

# Validate
research-timeline validate

See example/timeline.json for a real-world timeline (the PASM DTC Discovery project, N47Lab MatterMemory research program) and the generated exports in example/.

Event IDs

T0, T1, T2, …, Tn (ordered research phases) plus special events: pivot, control, submission, publication, milestone.

File Format

A timeline is a single JSON document:

{
  "project": {"name": "PASM DTC Discovery", "description": "...", "domain": "quantum"},
  "author": {"name": "N47Lab", "affiliation": "independent", "ai_role": "cognitive_prosthesis"},
  "events": [{
    "id": "T1", "type": "T1", "date": "2026-07-31",
    "description": "First commit: 14 QPU experiments, Z>50sigma",
    "metrics": {"z_score_combined": 50.0},
    "evidence": {"git_commit": "c3ddc4a", "job_ids": ["abc"]}
  }]
}

The schema is documented in schema/timeline.schema.json (JSON Schema draft-07).

Related work

• Notes/task tools (Notion, Obsidian, Logseq, Trello) — general-purpose notes or task boards; no typed research phases, no JSON schema, no CI validation, cloud-dependent storage.
• Experiment trackers (Weights & Biases, MLflow, DVC) — track model runs, artifacts, and metrics; they do not record researcher-level process events (first insight, pivot, control, submission) nor provide paper-oriented exports (LaTeX).
• Notebooks (Jupyter, Quarto) — rich narrative but unstructured; no enforcement of a timeline schema, no machine-readable JSON-LD export.
• Lab notebooks (ELN, Code Ocean) — heavyweight, instrument-locked, or cloud-bound; too heavy for long-term, single-author project process tracking.

research-timeline fills the empty slot: a zero-dependency, git-native, JSON-backed tracker for the research narrative with an explicit schema, structured evidence fields, and LaTeX/JSON-LD exports for the writing stage.

AI Usage Disclosure

This project was developed with the assistance of generative AI tools (interactive AI coding assistants with agentic workflows). AI assistance covered initial code scaffolding, the test suite, and documentation drafting (June–August 2026). All AI-assisted output was reviewed by the human author, with AI-assisted review for verification; design decisions and final acceptance of every change (schema, event types, export contracts, ai_role semantics) were made by the human author. Algorithmic behavior is covered by the test suite in tests/ and by CI. See AI_POLICY.md for the full policy.

Development & Contributing

See CONTRIBUTING.md — tests, coding conventions, and governance.

pip install -e ".[dev]"
pytest tests/ -v

Software Heritage

This repository is archived in permanent storage: swh:1:snp:62a2f748e52113016cf291c4b8c944e86c6848bf

License

MIT — see LICENSE.