Skip to content

API Reference

Programmatic API of the research_timeline package. Most users interact with the CLI (see Usage); these references are for tooling that imports the package directly.

CLI module

research-timeline CLI.

Track, validate, and export research timelines — from first AI interaction to scientific discovery. Commands: init, log, list, export, stats, validate; formats: LaTeX, Markdown, standalone HTML, schema.org JSON-LD, W3C PROV-O (JSON-LD), CSV, and TikZ Gantt.

latex_escape

latex_escape(value: object) -> str

Escape LaTeX special characters in user-provided text.

Parameters:

Name Type Description Default
value object

Text to escape (any object; converted with str).

required

Returns:

Type Description
str

The text with LaTeX special characters replaced by their escapes.

load_schema

load_schema() -> dict

Load the packaged JSON Schema (draft-07).

Searches the packaged copy first, then the repository schema/ copy.

Returns:

Type Description
dict

The parsed schema as a dictionary.

Raises:

Type Description
FileNotFoundError

If no schema copy can be found.

validate_timeline

validate_timeline(timeline: dict) -> List[str]

Validate a timeline against the JSON Schema.

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
List[str]

A list of human-readable problems (empty when the timeline is valid).

load_timeline

load_timeline(path: Path) -> Optional[dict]

Load timeline from JSON file.

save_timeline

save_timeline(path: Path, data: dict) -> None

Save timeline to JSON file.

print_ok

print_ok(msg: str) -> None

Print success message.

init

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'), force: bool = typer.Option(False, '--force', help='Overwrite an existing file without asking'))

Create a new timeline file with project and author metadata.

log

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)'), end_date: Optional[str] = typer.Option(None, '--end-date', help='Optional end date for a range (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 typed event to the timeline.

The event ID must be unique and match the typed phases (T0…Tn, pivot, control, submission, publication, milestone). The resulting document is validated against the JSON Schema before it is written; invalid events are rejected without touching the file.

edit

edit(event_id: str = typer.Argument(..., help='Event ID to edit'), description: Optional[str] = typer.Option(None, '--desc', help='New description'), event_date: Optional[str] = typer.Option(None, '--date', help='New date (YYYY-MM-DD)'), end_date: Optional[str] = typer.Option(None, '--end-date', help='New end date (YYYY-MM-DD)'), tags: Optional[str] = typer.Option(None, '--tags', help='New tags (comma-separated)'), timeline_file: Path = typer.Option(Path('.research-timeline.json'), '--file', '-f', help='Timeline file'))

Edit fields of an existing event (description, date, end date, tags).

Only the fields you pass are changed. The document is validated against the JSON Schema before it is written.

remove

remove(event_id: str = typer.Argument(..., help='Event ID to remove'), yes: bool = typer.Option(False, '--yes', '-y', help='Skip the confirmation prompt'), timeline_file: Path = typer.Option(Path('.research-timeline.json'), '--file', '-f', help='Timeline file'))

Remove an event from the timeline (asks for confirmation).

list

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'), event_type: Optional[str] = typer.Option(None, '--type', help='Filter by event type'), tag: Optional[str] = typer.Option(None, '--tag', help='Filter by tag (exact match)'), since: Optional[str] = typer.Option(None, '--since', help='Only events with date >= YYYY-MM-DD'), until: Optional[str] = typer.Option(None, '--until', help='Only events with date <= YYYY-MM-DD'), json_out: bool = typer.Option(False, '--json', help='Output the filtered events as JSON'))

List events, with optional filters by type, tag, or date window.

export

export(format: str = typer.Option('latex', '--format', help='Export format: latex, markdown, jsonld, html, csv, gantt, prov'), 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 the timeline to LaTeX, Markdown, HTML, JSON-LD, PROV-O, CSV, or Gantt (TikZ).

export_csv

export_csv(timeline: dict) -> str

Export the timeline as CSV (machine-readable, spreadsheet-friendly).

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

CSV content as a single string (header + one row per event).

export_gantt

export_gantt(timeline: dict) -> str

Export the timeline as a publication-ready Gantt chart (LaTeX TikZ).

Requires \usepackage{tikz}. Point events render as markers; events with an end_date render as bars.

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

TikZ content as a single string.

stats

stats(timeline_file: Path = typer.Option(Path('.research-timeline.json'), '--file', '-f', help='Timeline file'), json_out: bool = typer.Option(False, '--json', help='Output statistics as JSON'))

Print summary statistics: event count, date window, per-type and per-tag counts.

export_latex

export_latex(timeline: dict) -> str

Export the timeline as a LaTeX table (manuscript-ready).

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

The table environment as a single string.

export_markdown

export_markdown(timeline: dict) -> str

Export the timeline as a Markdown table (portable, README-friendly).

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

The table as Markdown text.

export_jsonld

export_jsonld(timeline: dict) -> str

Export the timeline as schema.org JSON-LD (ResearchProject + Event).

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

The JSON-LD document as a string.

export_prov

export_prov(timeline: dict) -> str

Export the timeline as a W3C PROV-O provenance graph (JSON-LD).

Mapping: project → prov:Bundle; author → prov:Person; declared AI role → prov:SoftwareAgent; events → prov:Activity (ISO start/end times) associated with both agents; evidence items → prov:Entity generated by their event. Custom rt: terms carry metrics, tags, type.

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

The PROV-O JSON-LD document as a string.

export_html

export_html(timeline: dict) -> str

Export the timeline as a standalone HTML widget (no build step).

Parameters:

Name Type Description Default
timeline dict

Parsed timeline document.

required

Returns:

Type Description
str

The HTML document as a single string.

validate

validate(timeline_file: Path = typer.Option(Path('.research-timeline.json'), '--file', '-f', help='Timeline file'))

Validate the timeline against the shipped JSON Schema (draft-07).

Models (pydantic)

Pydantic models for research-timeline documents.

These models mirror the JSON Schema shipped with the package and can be used by downstream tools to validate or construct timelines programmatically.

ProjectInfo

Bases: BaseModel

Project metadata: name, description, and research domain.

Author

Bases: BaseModel

Author metadata, including the declared role of AI (ai_role).

Evidence

Bases: BaseModel

Supporting evidence for an event (commits, job IDs, data/code links).

Metrics

Bases: BaseModel

Quantitative metrics for an event (z-scores, shots, backend).

Event

Bases: BaseModel

A typed timeline event with optional metrics and evidence.

ResearchTimeline

Bases: BaseModel

A complete timeline document (project, author, events).