Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (65 loc) · 3.92 KB

AGENTS.md

File metadata and controls

75 lines (65 loc) · 3.92 KB
Raw

AGENTS.md — plot-cli

Project Overview

plot-cli is a simple command-line plotting tool for terminal-based data visualization. It uses DuckDB for data loading/transformation and tplot for rendering. Supports CSV, JSON, NDJSON, and Parquet input with SQL-style filtering and time-series bucketing.

Package Environment

This project uses uv for all Python tooling. Do not use pip, poetry, or conda.

  • Install dependencies: uv sync
  • Run the CLI: uv run plot or uv run plot-cli
  • Run tests: uv run pytest
  • Run a specific test marker: uv run pytest -m unit or uv run pytest -m integration
  • Add a dependency: uv add <package>
  • Add a dev dependency: uv add --group dev <package>
  • Build: uv build

The lockfile is uv.lock. Always commit it alongside pyproject.toml changes.

Project Layout

pyproject.toml          # PEP 621 metadata, dependencies, pytest config (hatchling backend)
uv.lock                 # Locked dependency versions
src/plot_cli/           # Package source (src-layout)
  __init__.py           # Entry-point, PlotApp (CmdKit Application), CLI interface
  config.py             # Configuration via CmdKit (TOML), logging, error handling
  query.py              # QueryBuilder — DuckDB queries, format detection, filtering, bucketing
  plot.py               # Figure/TimeSeriesFigure wrappers around tplot, tick generation
tests/
  test_app.py           # Unit tests — version output
  test_query.py         # Unit tests — QueryBuilder, format detection, filtering, aggregation
  test_cli.py           # Integration tests — CLI output modes, filtering, aggregation options

Architecture

  • CmdKit pattern: The CLI follows the CmdKit Application pattern. PlotApp in __init__.py defines the full CLI interface via Interface with argument groups. See cmdkit docs.
  • Data pipeline: PlotApp.run() → _load_data() (QueryBuilder) → output or render.
  • QueryBuilder (query.py): Builds and executes DuckDB SQL queries. Handles format detection, column selection, WHERE/datetime filtering, time bucketing, PIVOT for --by, and datetime scale conversion.
  • Figure (plot.py): Thin wrapper over tplot.Figure. TimeSeriesFigure extends it with smart datetime axis tick generation via _CustomTplotFigure.

Coding Conventions

  • License headers: Every .py file starts with SPDX copyright/license comments.
  • Type annotations: Use from __future__ import annotations. Prefer Optional, List, Tuple from typing (existing convention in this codebase).
  • Imports: Group as: type annotations, standard libs, external libs, internal libs. Include a # Public interface section with __all__.
  • Logging: Use cmdkit.logging.Logger in application code, logging.getLogger(__name__) in library modules.
  • Self annotations: Methods use explicit self: ClassName type annotations.

Testing

  • Framework: pytest with custom markers defined in pyproject.toml.
  • Markers: @mark.unit for fast interface tests, @mark.integration for CLI/system tests.
  • Run all tests: uv run pytest
  • Run by marker: uv run pytest -m unit
  • Test data: Use tmp_path fixture for temporary files; create CSV/JSON/Parquet inline.
  • CLI tests: Invoke via PlotApp.main([...]) and capture output with capsys.

Git Workflow

  • Work on the wip branch with WIP: prefixed commit messages.
  • Push to wip freely; collapse into logical commits before PR against main.
  • Include Co-Authored-By: Oz <oz-agent@warp.dev> on AI-assisted commits.

Key Dependencies

  • cmdkit[toml] — CLI framework (Application, Interface, Configuration, Logger)
  • duckdb — In-process SQL for data loading and transformation
  • pandas — DataFrame interchange between DuckDB and plotting
  • tplot — Terminal-based plotting (line, scatter, bar, histogram)
  • pyarrow — Parquet read/write support