Metadata-Version: 2.4
Name: research-timeline
Version: 0.2.3
Summary: Track, visualize, and export research timelines from first AI interaction to scientific discovery
Author-email: Alessandro Tulli <2injob.at2@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Strugiss/research-timeline
Project-URL: Repository, https://github.com/Strugiss/research-timeline
Project-URL: Issues, https://github.com/Strugiss/research-timeline/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

﻿# Research Timeline

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21855315.svg)](https://doi.org/10.5281/zenodo.21855315)
[![CI](https://github.com/Strugiss/research-timeline/actions/workflows/ci.yml/badge.svg)](https://github.com/Strugiss/research-timeline/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![SWH](https://archive.softwareheritage.org/badge/swh:1:snp:62a2f748e52113016cf291c4b8c944e86c6848bf/)](https://archive.softwareheritage.org/swh:1:snp:62a2f748e52113016cf291c4b8c944e86c6848bf)

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

```bash
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

```bash
# 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](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:

```json
{
  "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. The work was conducted by a single human author with substantial AI assistance, mirroring the distribution of roles in a research group (design, implementation, verification, drafting), with the human author bearing full responsibility for the final result. See [AI_POLICY.md](AI_POLICY.md) for the full policy.

## Development & Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) — tests, coding conventions, and governance.

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

## Software Heritage

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

## License

MIT — see [LICENSE](LICENSE).
