research-timeline 0.2.1__tar.gz

research_timeline-0.2.1/LICENSE

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

research_timeline-0.2.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: research-timeline
+Version: 0.2.1
+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 line-by-line by the human author, whose design decisions (schema, event types, export contracts, `ai_role` semantics) drove the project; algorithmic behavior is covered by the test suite in `tests/` and by CI. 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).

research_timeline-0.2.1/README.md

@@ -0,0 +1,113 @@
+# 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 line-by-line by the human author, whose design decisions (schema, event types, export contracts, `ai_role` semantics) drove the project; algorithmic behavior is covered by the test suite in `tests/` and by CI. 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).

research_timeline-0.2.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "research-timeline"
+version = "0.2.1"
+description = "Track, visualize, and export research timelines from first AI interaction to scientific discovery"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Alessandro Tulli", email = "2injob.at2@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "typer>=0.9.0",
+    "pydantic>=2.5.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Strugiss/research-timeline"
+Repository = "https://github.com/Strugiss/research-timeline"
+Issues = "https://github.com/Strugiss/research-timeline/issues"
+
+[project.scripts]
+research-timeline = "research_timeline.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

research_timeline-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

research_timeline-0.2.1/src/research_timeline/__init__.py

@@ -0,0 +1,2 @@
+"""Research Timeline package."""
+__version__ = "0.2.0"

research_timeline-0.2.1/src/research_timeline/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for research-timeline CLI."""
+from .cli import app
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(app())

research_timeline-0.2.1/src/research_timeline/cli.py

@@ -0,0 +1,415 @@
+import typer
+from typing import Optional, List
+from datetime import date
+from pathlib import Path
+import json
+import re
+from rich.console import Console
+from rich.table import Table
+from rich import print as rprint
+
+from .models import ResearchTimeline, ProjectInfo, Author, Event
+
+VALID_EVENT_ID = re.compile(r"^T([0-9]+|n)$|^(pivot|control|submission|publication|milestone)$")
+
+app = typer.Typer(
+    name="research-timeline",
+    help="Track, visualize, and export research timelines from first AI interaction to scientific discovery",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+console = Console()
+
+# Default timeline file
+DEFAULT_TIMELINE_FILE = Path(".research-timeline.json")
+
+
+def load_timeline(path: Path) -> Optional[dict]:
+    """Load timeline from JSON file."""
+    if not path.exists():
+        return None
+    with open(path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def save_timeline(path: Path, data: dict) -> None:
+    """Save timeline to JSON file."""
+    with open(path, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+def print_ok(msg: str) -> None:
+    """Print success message."""
+    print(f"[OK] {msg}")
+
+
+def print_error(msg: str) -> None:
+    print(f"[ERROR] {msg}")
+
+
+@app.command()
+def init(
+    name: str = typer.Option(..., "--name", "-n", help="Project name"),
+    description: str = typer.Option(..., "--desc", "-d", help="Project description"),
+    domain: str = typer.Option("quantum", "--domain", help="Research domain"),
+    author_name: str = typer.Option(..., "--author", "-a", help="Author name"),
+    affiliation: str = typer.Option("independent", "--affiliation", help="Affiliation"),
+    orcid: Optional[str] = typer.Option(None, "--orcid", help="ORCID URL"),
+    background: str = typer.Option("without academic degrees", "--background", help="Academic background"),
+    ai_role: str = typer.Option("cognitive_prosthesis", "--ai-role", help="AI role"),
+    output: Path = typer.Option(Path(".research-timeline.json"), "--output", "-o", help="Output file"),
+):
+    """Initialize a new research timeline."""
+    from datetime import date
+    
+    timeline = {
+        "project": {
+            "name": name,
+            "description": description,
+            "domain": domain
+        },
+        "author": {
+            "name": author_name,
+            "affiliation": affiliation,
+            "orcid": orcid,
+            "background": background,
+            "ai_role": ai_role
+        },
+        "events": [],
+        "created_at": str(date.today()),
+        "updated_at": str(date.today()),
+        "version": "1.0"
+    }
+    
+    output_path = Path(output)
+    with open(output_path, 'w', encoding='utf-8') as f:
+        json.dump(timeline, f, indent=2, ensure_ascii=False)
+    
+    print(f"[OK] Initialized timeline at {output}")
+    print(f"  Project: {name} ({domain})")
+    print(f"  Author: {author_name} ({background})")
+
+
+@app.command()
+def log(
+    event_id: str = typer.Argument(..., help="Event ID (T0, T1, T2, Tn, pivot, control, etc.)"),
+    event_type: str = typer.Option(..., "--type", help="Event type (T0, T1, T2, Tn, pivot, control, submission, publication, milestone)"),
+    event_date: str = typer.Option(str(date.today()), "--date", help="Event date (YYYY-MM-DD)"),
+    description: str = typer.Option(..., "--desc", help="Event description"),
+    tags: Optional[str] = typer.Option(None, "--tags", help="Tags (comma-separated)"),
+    z_score: Optional[float] = typer.Option(None, "--z-score", help="Z-score"),
+    shots: Optional[int] = typer.Option(None, "--shots", help="Number of shots"),
+    backend: Optional[str] = typer.Option(None, "--backend", help="Quantum backend"),
+    job_ids: Optional[List[str]] = typer.Option(None, "--job-ids", help="Job IDs (comma-separated)"),
+    z_score_combined: Optional[float] = typer.Option(None, "--z-combined", help="Combined Z-score"),
+    git_commit: Optional[str] = typer.Option(None, "--git-commit", help="Git commit hash"),
+    data_links: Optional[List[str]] = typer.Option(None, "--data-links", help="Data links (comma-separated)"),
+    code_links: Optional[List[str]] = typer.Option(None, "--code-links", help="Code links (comma-separated)"),
+    timeline_file: Path = typer.Option(Path(".research-timeline.json"), "--file", "-f", help="Timeline file"),
+):
+    """Log a new event to the timeline."""
+    if not Path(timeline_file).exists():
+        print(f"[ERROR] Timeline file not found: {timeline_file}. Run 'init' first.")
+        raise typer.Exit(1)
+    
+    with open(timeline_file, 'r', encoding='utf-8') as f:
+        timeline = json.load(f)
+    
+    # Validate event ID
+    event_id = event_id.strip()
+    if not VALID_EVENT_ID.match(event_id):
+        print("[ERROR] Event ID must match T0, T1, T2, Tn, pivot, control, submission, publication, milestone")
+        raise typer.Exit(1)
+    
+    # Check for duplicate ID
+    for event in timeline.get("events", []):
+        if event.get("id") == event_id:
+            print(f"[ERROR] Event ID {event_id} already exists")
+            raise typer.Exit(1)
+    
+    # Build event
+    event = {
+        "id": event_id,
+        "type": event_type,
+        "date": event_date,
+        "description": description,
+        "tags": [t.strip() for t in tags.split(",")] if tags else [],
+    }
+    
+    # Add metrics if provided
+    metrics = {}
+    if z_score is not None:
+        metrics["z_score"] = z_score
+    if shots is not None:
+        metrics["shots"] = shots
+    if backend:
+        metrics["backend"] = backend
+    if z_score_combined is not None:
+        metrics["z_score_combined"] = z_score_combined
+    if metrics:
+        event["metrics"] = {k: v for k, v in metrics.items() if v is not None}
+    
+    # Evidence
+    evidence = {}
+    if git_commit:
+        evidence["git_commit"] = git_commit
+    if job_ids:
+        evidence["job_ids"] = [j.strip() for tok in job_ids for j in tok.split(",") if j.strip()]
+    if data_links:
+        evidence["data_links"] = [d.strip() for tok in data_links for d in tok.split(",") if d.strip()]
+    if code_links:
+        evidence["code_links"] = [c.strip() for tok in code_links for c in tok.split(",") if c.strip()]
+    if evidence:
+        event["evidence"] = {k: v for k, v in evidence.items() if v}
+    
+    timeline.setdefault("events", []).append(event)
+    timeline["updated_at"] = str(date.today())
+    
+    with open(timeline_file, 'w', encoding='utf-8') as f:
+        json.dump(timeline, f, indent=2, ensure_ascii=False)
+    
+    print(f"[OK] Logged event {event_id}: {description}")
+
+
+@app.command()
+def list(
+    timeline_file: Path = typer.Option(Path(".research-timeline.json"), "--file", "-f", help="Timeline file"),
+    show_metrics: bool = typer.Option(False, "--metrics", "-m", help="Show metrics"),
+):
+    """List all events in the timeline."""
+    if not Path(timeline_file).exists():
+        print(f"[ERROR] Timeline file not found: {timeline_file}")
+        raise typer.Exit(1)
+    
+    with open(timeline_file, 'r', encoding='utf-8') as f:
+        timeline = json.load(f)
+    
+    # Print as simple text table to avoid Unicode issues on Windows
+    print("Research Timeline")
+    print("=" * 80)
+    header = f"{'ID':<4} | {'Type':<6} | {'Date':<12} | {'Description':<40} | {'Tags':<20} | {'Metrics':<30}"
+    print(header)
+    print("-" * 120)
+    
+    for event in timeline.get("events", []):
+        metrics_str = ""
+        if event.get("metrics"):
+            # Replace sigma character for Windows compatibility
+            metrics_str = ", ".join(f"{k}={v}".replace('\u03c3', 'sigma') for k, v in event.get("metrics", {}).items() if v is not None)
+        
+        desc = event["description"][:50]
+        tags_str = ", ".join(event.get("tags", []))
+        print(f"{event['id']:<4} | {event['type']:<6} | {event['date']:<12} | {desc:<50} | {tags_str:<20} | {metrics_str}")
+
+
+@app.command()
+def export(
+    format: str = typer.Option("latex", "--format", help="Export format: latex, markdown, jsonld, html"),
+    timeline_file: Path = typer.Option(Path(".research-timeline.json"), "--file", help="Timeline file"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file"),
+):
+    """Export timeline to various formats."""
+    if not Path(timeline_file).exists():
+        print(f"[ERROR] Timeline file not found: {timeline_file}")
+        raise typer.Exit(1)
+    
+    with open(timeline_file, 'r', encoding='utf-8') as f:
+        timeline = json.load(f)
+    
+    if format == "latex":
+        output_content = export_latex(timeline)
+    elif format == "markdown":
+        output_content = export_markdown(timeline)
+    elif format == "jsonld":
+        output_content = export_jsonld(timeline)
+    elif format == "html":
+        output_content = export_html(timeline)
+    else:
+        print(f"[ERROR] Unknown format: {format}")
+        raise typer.Exit(1)
+    
+    if output:
+        with open(output, 'w', encoding='utf-8') as f:
+            f.write(output_content)
+        print(f"[OK] Exported to {output}")
+    else:
+        print(output_content)
+
+
+def export_latex(timeline: dict) -> str:
+    """Export timeline as LaTeX table."""
+    lines = [
+        "\\begin{table}[ht]",
+        "\\centering",
+        "\\caption{Research Timeline: First AI Interaction to Discovery}",
+        "\\label{tab:timeline}",
+        "\\begin{tabular}{lllll}",
+        "\\toprule",
+        "\\textbf{Phase} & \\textbf{Date} & \\textbf{Event} & \\textbf{Metrics} & \\textbf{Evidence} \\\\",
+        "\\midrule",
+    ]
+    
+    for event in timeline.get("events", []):
+        metrics = event.get("metrics", {})
+        metrics_str = ", ".join(f"{k}={v}" for k, v in metrics.items() if v is not None) if metrics else ""
+        evidence = event.get("evidence", {})
+        evidence_str = ""
+        if evidence.get("git_commit"):
+            evidence_str += f"git {evidence['git_commit'][:8]} "
+        if evidence.get("job_ids"):
+            evidence_str += f"jobs: {', '.join(evidence['job_ids'][:3])} "
+        
+        lines.append(
+            f"{event['id']} & {event['date']} & {event['description'][:50]} & {metrics_str} & {evidence_str} \\\\"
+        )
+    
+    lines.extend([
+        "\\bottomrule",
+        "\\end{tabular}",
+        "\\end{table}",
+    ])
+    return "\n".join(lines)
+
+
+def export_markdown(timeline: dict) -> str:
+    """Export timeline as Markdown table."""
+    lines = ["## Research Timeline", "", "| Phase | Date | Event | Metrics | Evidence |", "|-------|------|-------|---------|----------|"]
+    
+    for event in timeline.get("events", []):
+        metrics = event.get("metrics", {})
+        metrics_str = ", ".join(f"{k}={v}" for k, v in metrics.items() if v is not None) if metrics else ""
+        evidence = event.get("evidence", {})
+        evidence_str = ""
+        if evidence.get("git_commit"):
+            evidence_str += f"git {evidence['git_commit'][:8]} "
+        if evidence.get("job_ids"):
+            evidence_str += f"jobs: {', '.join(evidence['job_ids'][:3])} "
+        
+        lines.append(f"| {event['id']} | {event['date']} | {event['description'][:60]} | {metrics_str} | {evidence_str} |")
+    
+    return "\n".join(lines)
+
+
+def export_jsonld(timeline: dict) -> str:
+    """Export as JSON-LD for Schema.org."""
+    context = {
+        "@context": "https://schema.org",
+        "@type": "ResearchProject",
+        "name": timeline.get("project", {}).get("name", ""),
+        "description": timeline.get("project", {}).get("description", ""),
+        "author": {
+            "@type": "Person",
+            "name": timeline.get("author", {}).get("name", ""),
+            "affiliation": timeline.get("author", {}).get("affiliation", ""),
+            "orcid": timeline.get("author", {}).get("orcid", "")
+        },
+        "dateCreated": timeline.get("created_at"),
+        "dateModified": timeline.get("updated_at"),
+        "hasPart": []
+    }
+    
+    for event in timeline.get("events", []):
+        event_obj = {
+            "@type": "ResearchEvent",
+            "identifier": event["id"],
+            "name": event["description"],
+            "startDate": event["date"],
+            "eventType": event["type"],
+            "description": event["description"]
+        }
+        if event.get("metrics"):
+            event_obj["measurementTechnique"] = ", ".join(f"{k}: {v}" for k, v in event.get("metrics", {}).items() if v is not None)
+        context["hasPart"].append(event_obj)
+    
+    return json.dumps(context, indent=2, ensure_ascii=False)
+
+
+def export_html(timeline: dict) -> str:
+    """Export as interactive HTML widget."""
+    html = """<!DOCTYPE html>
+<html>
+<head>
+    <title>Research Timeline</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
+        .timeline { position: relative; padding: 20px 0; }
+        .event { position: relative; padding: 15px; margin: 10px 0; background: #1a1f2a; border-radius: 8px; border-left: 4px solid #6fc3df; }
+        .event-id { font-family: monospace; color: #6fc3df; font-weight: bold; }
+        .event-date { color: #8892a8; font-size: 0.9em; }
+        .event-desc { color: #e0e4ee; margin: 8px 0; }
+        .event-metrics { color: #facc15; font-family: monospace; font-size: 0.85em; }
+        .event-tags { margin-top: 8px; }
+        .tag { display: inline-block; background: rgba(111,195,223,0.12); color: #6fc3df; padding: 2px 8px; border-radius: 12px; font-size: 0.75em; margin-right: 4px; }
+    </style>
+</head>
+<body>
+    <h1>Research Timeline</h1>
+    <div class="timeline">"""
+    
+    for event in timeline.get("events", []):
+        metrics = event.get("metrics", {})
+        metrics_html = ""
+        if event.get("metrics"):
+            metrics_html = f'<div class="event-metrics">{" | ".join(f"{k}={v}" for k, v in event["metrics"].items() if v is not None)}</div>'
+        
+        tags_html = ""
+        if event.get("tags"):
+            tags_html = '<div class="event-tags">' + "".join(f'<span class="tag">{t}</span>' for t in event["tags"]) + '</div>'
+        
+        html += f"""
+        <div class="event">
+            <div class="event-id">{event['id']}</div>
+            <div class="event-date">{event['date']}</div>
+            <div class="event-desc">{event['description']}</div>
+            {metrics_html}
+            {tags_html}
+        </div>"""
+    
+    html += """    </div>
+</body>
+</html>"""
+    return html
+
+
+@app.command()
+def validate(
+    timeline_file: Path = typer.Option(Path(".research-timeline.json"), "--file", "-f", help="Timeline file"),
+):
+    """Validate timeline against schema."""
+    if not Path(timeline_file).exists():
+        print(f"[ERROR] Timeline file not found: {timeline_file}")
+        raise typer.Exit(1)
+    
+    with open(timeline_file, 'r', encoding='utf-8') as f:
+        timeline = json.load(f)
+    
+    # Basic validation
+    errors = []
+    if "project" not in timeline:
+        errors.append("Missing 'project' section")
+    if "author" not in timeline:
+        errors.append("Missing 'author' section")
+    if "events" not in timeline or not timeline["events"]:
+        errors.append("Missing or empty 'events' section")
+    
+    for i, event in enumerate(timeline.get("events", [])):
+        if "id" not in event:
+            errors.append(f"Event {i}: missing 'id'")
+        if "type" not in event:
+            errors.append(f"Event {event.get('id', i)}: missing 'type'")
+        if "date" not in event:
+            errors.append(f"Event {event.get('id', i)}: missing 'date'")
+    
+    if errors:
+        print("[ERROR] Validation failed:")
+        for err in errors:
+            print(f"  [ERROR] {err}")
+        raise typer.Exit(1)
+    else:
+        print("[OK] Timeline is valid!")
+
+
+if __name__ == "__main__":
+    app()

research_timeline-0.2.1/src/research_timeline/models.py

@@ -0,0 +1,134 @@
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+from datetime import date
+from enum import Enum
+
+
+class ProjectInfo(BaseModel):
+    name: str = Field(..., description="Project name")
+    description: str = Field(..., description="Brief project description")
+    domain: str = Field(..., description="Research domain (e.g., quantum, biology, ml, physics, chemistry, materials, computer_science, other)")
+
+
+class Author(BaseModel):
+    name: str = Field(..., description="Author name")
+    affiliation: str = Field(..., description="Institutional affiliation (or 'independent')")
+    orcid: Optional[str] = Field(None, description="ORCID identifier")
+    background: str = Field(..., description="Academic background / credentials")
+    ai_role: str = Field(..., description="Role of AI in the research process (e.g., cognitive_prosthesis, co_pilot, autonomous_agent)")
+
+
+class Evidence(BaseModel):
+    git_commit: Optional[str] = Field(None, description="Git commit hash")
+    job_ids: List[str] = Field(default_factory=list, description="Related job IDs")
+    data_links: List[str] = Field(default_factory=list, description="Links to data repositories")
+    code_links: List[str] = Field(default_factory=list, description="Links to code repositories")
+
+
+class Metrics(BaseModel):
+    z_score: Optional[float] = Field(None, description="Z-score for the event")
+    shots: Optional[int] = Field(None, ge=0, description="Number of measurement shots")
+    backend: Optional[str] = Field(None, description="Quantum backend used")
+    job_ids: List[str] = Field(default_factory=list, description="Job IDs from quantum processor")
+    z_score_combined: Optional[float] = Field(None, description="Combined Z-score (Fisher method)")
+
+
+class Event(BaseModel):
+    id: str = Field(..., pattern=r"^T([0-9]+|n)$|^(pivot|control|submission|publication|milestone)$", description="Event identifier (T0, T1, T2, Tn, pivot, control, submission, publication, milestone)")
+    event_type: str = Field(..., description="Event type", alias="type")
+    event_date: date = Field(..., description="Event date (ISO 8601)", alias="date")
+    description: str = Field(..., description="Human-readable description of the event")
+    tags: List[str] = Field(default_factory=list, description="Tags for categorization")
+    metrics: Optional[Dict[str, Any]] = Field(None, description="Quantitative metrics for the event (arbitrary key-value pairs)")
+    evidence: Optional[Dict[str, Any]] = Field(None, description="Supporting evidence for the event")
+
+
+class ResearchTimeline(BaseModel):
+    project: dict = Field(..., description="Project information")
+    author: dict = Field(..., description="Author information")
+    events: List[dict] = Field(..., min_length=1, description="Timeline events")
+    created_at: date = Field(default_factory=date.today, description="Timeline creation date")
+    updated_at: date = Field(default_factory=date.today, description="Last update date")
+    version: str = Field(default="1.0", description="Timeline schema version")
+
+
+if __name__ == "__main__":
+    import json
+    timeline = {
+        "project": {
+            "name": "PASM DTC Discovery",
+            "description": "Observation of Classical Prethermal DTC on IBM Heron",
+            "domain": "quantum"
+        },
+        "author": {
+            "name": "N47Lab",
+            "affiliation": "independent",
+            "orcid": "https://orcid.org/0009-0008-9201-6080",
+            "background": "without academic degrees",
+            "ai_role": "cognitive_prosthesis"
+        },
+        "events": [
+            {
+                "id": "T0",
+                "type": "T0",
+                "date": "2026-06-06",
+                "description": "First AI interaction: setup, theory, protocol design",
+                "tags": ["setup", "theory", "protocol_design"],
+                "evidence": {
+                    "data_links": [".opencode log"]
+                }
+            },
+            {
+                "id": "T1",
+                "type": "T1",
+                "date": "2026-07-31",
+                "description": "First commit: 14 QPU experiments, Z>50σ",
+                "tags": ["commit", "qpu", "baseline"],
+                "metrics": {"z_score_combined": 50.0},
+                "evidence": {
+                    "git_commit": "c3ddc4a",
+                    "job_ids": []
+                }
+            }
+        ]
+    }
+    print("Schema validation passed!")
+    import json
+    print(json.dumps({
+        "project": {
+            "name": "PASM DTC Discovery",
+            "description": "Observation of Classical Prethermal DTC on IBM Heron",
+            "domain": "quantum"
+        },
+        "author": {
+            "name": "N47Lab",
+            "affiliation": "independent",
+            "orcid": "https://orcid.org/0009-0008-9201-6080",
+            "background": "without academic degrees",
+            "ai_role": "cognitive_prosthesis"
+        },
+        "events": [
+            {
+                "id": "T0",
+                "type": "T0",
+                "date": "2026-06-06",
+                "description": "First AI interaction: setup, theory, protocol design",
+                "tags": ["setup", "theory", "protocol_design"],
+                "evidence": {
+                    "data_links": [".opencode log"]
+                }
+            },
+            {
+                "id": "T1",
+                "type": "T1",
+                "date": "2026-07-31",
+                "description": "First commit: 14 QPU experiments, Z>50σ",
+                "tags": ["commit", "qpu", "baseline"],
+                "metrics": {"z_score_combined": 50.0},
+                "evidence": {
+                    "git_commit": "c3ddc4a",
+                    "job_ids": []
+                }
+            }
+        ]
+    }, indent=2))

research_timeline-0.2.1/src/research_timeline.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: research-timeline
+Version: 0.2.1
+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 line-by-line by the human author, whose design decisions (schema, event types, export contracts, `ai_role` semantics) drove the project; algorithmic behavior is covered by the test suite in `tests/` and by CI. 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).

research_timeline-0.2.1/src/research_timeline.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/research_timeline/__init__.py
+src/research_timeline/__main__.py
+src/research_timeline/cli.py
+src/research_timeline/models.py
+src/research_timeline.egg-info/PKG-INFO
+src/research_timeline.egg-info/SOURCES.txt
+src/research_timeline.egg-info/dependency_links.txt
+src/research_timeline.egg-info/entry_points.txt
+src/research_timeline.egg-info/requires.txt
+src/research_timeline.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_models.py

research_timeline-0.2.1/src/research_timeline.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

research_timeline-0.2.1/src/research_timeline.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+research-timeline = research_timeline.cli:app

research_timeline-0.2.1/src/research_timeline.egg-info/requires.txt

@@ -0,0 +1,8 @@
+typer>=0.9.0
+pydantic>=2.5.0
+rich>=13.0.0
+
+[dev]
+pytest>=7.4.0
+pytest-cov>=4.1.0
+ruff>=0.1.0

research_timeline-0.2.1/src/research_timeline.egg-info/top_level.txt

@@ -0,0 +1 @@
+research_timeline

research_timeline-0.2.1/tests/test_cli.py

@@ -0,0 +1,146 @@
+"""Tests for research-timeline CLI (typer-based)."""
+
+import json
+import os
+import tempfile
+
+from typer.testing import CliRunner
+
+from research_timeline.cli import app
+
+runner = CliRunner()
+
+
+def _tmp_path():
+    tmp = tempfile.mkdtemp()
+    return os.path.join(tmp, "tl.json")
+
+
+def _init(path):
+    return runner.invoke(app, [
+        "init",
+        "--name", "Test Project",
+        "--desc", "Test description",
+        "--domain", "quantum",
+        "--author", "Test Author",
+        "--affiliation", "independent",
+        "--output", path,
+    ])
+
+
+def test_init_creates_timeline():
+    path = _tmp_path()
+    result = _init(path)
+    assert result.exit_code == 0
+    assert os.path.exists(path)
+    data = json.load(open(path, encoding="utf-8"))
+    assert data["project"]["name"] == "Test Project"
+    assert data["events"] == []
+
+
+def test_log_then_list():
+    path = _tmp_path()
+    _init(path)
+    r = runner.invoke(app, [
+        "log", "T0", "--type", "T0",
+        "--desc", "First AI interaction", "--tags", "setup,theory",
+        "--file", path,
+    ])
+    assert r.exit_code == 0
+    r2 = runner.invoke(app, ["list", "--file", path])
+    assert r2.exit_code == 0
+    assert "T0" in r2.stdout
+
+
+def test_log_metrics_and_evidence():
+    path = _tmp_path()
+    _init(path)
+    r = runner.invoke(app, [
+        "log", "T1", "--type", "T1",
+        "--desc", "First QPU run", "--z-combined", "50.0",
+        "--z-score", "12.5", "--shots", "8192", "--backend", "ibm_kingston",
+        "--job-ids", "abc,def", "--git-commit", "c3ddc4a",
+        "--tags", "qpu", "--file", path,
+    ])
+    assert r.exit_code == 0
+    data = json.load(open(path, encoding="utf-8"))
+    event = data["events"][0]
+    assert event["metrics"]["z_score_combined"] == 50.0
+    assert event["metrics"]["shots"] == 8192
+    assert event["metrics"]["backend"] == "ibm_kingston"
+    assert event["evidence"]["job_ids"] == ["abc", "def"]
+    assert event["evidence"]["git_commit"] == "c3ddc4a"
+
+
+def test_log_valid_ids():
+    path = _tmp_path()
+    _init(path)
+    for eid in ["T0", "T1", "Tn", "pivot", "control", "submission", "publication", "milestone"]:
+        r = runner.invoke(app, [
+            "log", eid, "--type", eid, "--desc", f"Test {eid}", "--file", path,
+        ])
+        assert r.exit_code == 0, f"{eid} should be accepted"
+
+
+def test_log_invalid_id_rejected():
+    path = _tmp_path()
+    _init(path)
+    r = runner.invoke(app, [
+        "log", "X0", "--type", "T0", "--desc", "Bad", "--file", path,
+    ])
+    assert r.exit_code != 0
+
+
+def test_log_duplicate_id_rejected():
+    path = _tmp_path()
+    _init(path)
+    runner.invoke(app, ["log", "T0", "--type", "T0", "--desc", "First", "--file", path])
+    r = runner.invoke(app, ["log", "T0", "--type", "T0", "--desc", "Dup", "--file", path])
+    assert r.exit_code != 0
+    assert "already exists" in r.stdout.lower()
+
+
+def test_export_latex():
+    path = _tmp_path()
+    _init(path)
+    runner.invoke(app, ["log", "T0", "--type", "T0", "--desc", "Start", "--file", path])
+    r = runner.invoke(app, ["export", "--format", "latex", "--file", path])
+    assert r.exit_code == 0
+    assert "tabular" in r.stdout
+    assert "T0" in r.stdout
+
+
+def test_export_jsonld():
+    path = _tmp_path()
+    _init(path)
+    r = runner.invoke(app, ["export", "--format", "jsonld", "--file", path])
+    assert r.exit_code == 0
+    assert '"@context": "https://schema.org"' in r.stdout
+    assert '"@type": "ResearchProject"' in r.stdout
+
+
+def test_export_html_to_file():
+    path = _tmp_path()
+    _init(path)
+    runner.invoke(app, ["log", "Tn", "--type", "Tn", "--desc", "Discovery", "--file", path])
+    out = os.path.join(os.path.dirname(path), "out.html")
+    r = runner.invoke(app, ["export", "--format", "html", "--file", path, "-o", out])
+    assert r.exit_code == 0
+    assert os.path.exists(out)
+    assert "<html>" in open(out, encoding="utf-8").read()
+
+
+def test_validate_ok_and_fail():
+    path = _tmp_path()
+    _init(path)
+    runner.invoke(app, ["log", "T0", "--type", "T0", "--desc", "Ok", "--file", path])
+    r = runner.invoke(app, ["validate", "--file", path])
+    assert r.exit_code == 0
+    r2 = runner.invoke(app, ["validate", "--file", os.path.join(os.path.dirname(path), "none.json")])
+    assert r2.exit_code != 0
+
+
+def test_help():
+    r = runner.invoke(app, ["--help"])
+    assert r.exit_code == 0
+    assert "research-timeline" in r.stdout

research_timeline-0.2.1/tests/test_models.py

@@ -0,0 +1,89 @@
+import pytest
+from datetime import date
+from research_timeline.models import ResearchTimeline, ProjectInfo, Author, Event, Metrics, Evidence
+
+
+def test_basic_timeline():
+    """Test basic timeline creation."""
+    timeline = {
+        "project": {
+            "name": "Test Project",
+            "description": "Test",
+            "domain": "quantum"
+        },
+        "author": {
+            "name": "Test Author",
+            "affiliation": "independent",
+            "orcid": "https://orcid.org/0000-0000-0000-0000",
+            "background": "without academic degrees",
+            "ai_role": "cognitive_prosthesis"
+        },
+        "events": [
+            {
+                "id": "T0",
+                "type": "T0",
+                "date": "2026-06-06",
+                "description": "First AI interaction",
+                "tags": ["setup"],
+                "metrics": {},
+                "evidence": {}
+            }
+        ],
+        "created_at": "2026-08-06",
+        "updated_at": "2026-08-06",
+        "version": "1.0"
+    }
+    
+    # This would be validated by pydantic in real usage
+    assert True
+
+
+def test_event_validation():
+    """Test event ID validation."""
+    from research_timeline.models import Event
+    
+    # Valid IDs
+    Event(id="T0", type="T0", date="2026-06-06", description="Test")
+    Event(id="T1", type="T1", date="2026-06-06", description="Test")
+    Event(id="Tn", type="Tn", date="2026-06-06", description="Test")
+    Event(id="pivot", type="pivot", date="2026-08-01", description="Pivot")
+    Event(id="control", type="control", date="2026-08-01", description="Control")
+    Event(id="submission", type="submission", date="2026-08-01", description="Submission")
+    Event(id="publication", type="publication", date="2026-08-01", description="Publication")
+    Event(id="milestone", type="milestone", date="2026-08-01", description="Milestone")
+    
+    # Invalid ID should raise
+    try:
+        Event(id="X0", type="T0", date="2026-06-06", description="Test")
+        assert False, "Should have raised"
+    except ValueError:
+        pass  # Expected
+
+
+def test_metrics_optional():
+    """Test that metrics are optional."""
+    from research_timeline.models import Event
+    
+    event = Event(
+        id="T0",
+        type="T0",
+        date="2026-06-06",
+        description="Test"
+    )
+    assert event.metrics is None
+    
+    # With metrics (as dict)
+    event2 = Event(
+        id="T1",
+        type="T1",
+        date="2026-07-01",
+        description="Test",
+        metrics={"z_score": 50.0, "shots": 8192}
+    )
+    assert event2.metrics is not None
+    assert event2.metrics["z_score"] == 50.0
+    assert event2.metrics["shots"] == 8192
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])