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.

RETTIFICA (01/09/2026): una precedente asserzione di unicità di questo strumento è stata formulata senza una verifica di mercato documentata. La verifica del 01/09/2026 ha evidenziato strumenti simili esistenti (timeline-fishbone-generator, timeline-maker, SubThesis Timeline Generator, Research-Timeline-Planner, The Timeline Project, altri). Questo strumento non è unico: si distingue per tracciamento AI→scoperta, evidence QPU e disclosure ai_role, ma la sua esistenza non è isolata.

Terminal preview

Real output (v0.2.4, Typer + rich):

$ research-timeline init -n "PASM DTC Discovery" -d "Classical prethermal DTC via PASM on IBM Quantum" -a "Alessandro Tulli" -o timeline.json
[OK] Initialized timeline at timeline.json
  Project: PASM DTC Discovery (quantum)
  Author: Alessandro Tulli (without academic degrees)

$ research-timeline log T1 --type T1 --desc "First QPU campaign: 14 experiments, Z>50 sigma" --z-combined 50.0 --backend ibm_kingston --job-ids abc123,def456 --tags commit,qpu -f timeline.json
[OK] Logged event T1: First QPU campaign: 14 experiments, Z>50 sigma

$ research-timeline validate -f timeline.json
[OK] Timeline is valid!

$ research-timeline stats -f timeline.json
Events:      1
Date window: 2026-09-14 .. 2026-09-14 (0 days)
By type:
  T1             1
By tag:
  commit         1
  qpu            1

Features

Install

pip install research-timeline

Quick start (3 steps)

# 1) initialize a timeline
research-timeline init -n "My project" -d "What the research is about" -a "Your Name" -o timeline.json

# 2) log a typed event with metrics and evidence
research-timeline log T1 --type T1 --desc "First result" --z-score 5.0 --git-commit abc1234 --tags result -f timeline.json

# 3) export (latex | markdown | html | jsonld | csv | gantt)
research-timeline export --format latex -o timeline.tex --file timeline.json

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

Documentation

Full documentation: https://strugiss.github.io/research-timeline/ — install, commands, file format, exports, FAQ.

AI Usage Disclosure

This package was developed with the assistance of generative AI tools (interactive AI coding assistants with agentic workflows): 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 (schema, event types, export contracts, ai_role semantics) and the final acceptance of every change were made by the human author.

This is an AI-augmented development model: the AI extends the author's capabilities (the cognitive_prosthesis role recorded by the tool itself), while every decision, review, and responsibility remain human. See docs/ai-disclosure.md and AI_POLICY.md for the full policy.

Citation

If you use research-timeline in your research, please cite it:

@software{tulli_research_timeline_2026,
  author  = {Tulli, Alessandro},
  title   = {research-timeline: track, validate, and export the research process as a typed JSON timeline},
  year    = {2026},
  doi     = {10.5281/zenodo.21862618},
  url     = {https://github.com/Strugiss/research-timeline},
  license = {MIT}
}

A machine-readable citation is provided in CITATION.cff.

Community & archive

• pyOpenSci software submission: issue #338
• Archived on Zenodo: 10.5281/zenodo.21862618
• Software Heritage: swh:1:snp:62a2f748e52113016cf291c4b8c944e86c6848bf

Links

• N47Lab main site: https://n47lab.altervista.org/
• Source code: https://github.com/Strugiss/research-timeline

License

MIT — see LICENSE.

Contributing

Contributions are welcome: see CONTRIBUTING.md for tests, coding conventions, and governance.

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