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
Escape LaTeX special characters in user-provided text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
object
|
Text to escape (any object; converted with |
required |
Returns:
| Type | Description |
|---|---|
str
|
The text with LaTeX special characters replaced by their escapes. |
load_schema
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 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). |
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 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 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 the timeline as a LaTeX table (manuscript-ready).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeline
|
dict
|
Parsed timeline document. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The |
export_markdown
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 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 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 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. |
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).