Metadata-Version: 2.4
Name: gesso
Version: 0.1.0
Summary: Automate creation of Obsidian markdown files for art collection
Project-URL: Repository, https://github.com/sanchitram1/gesso.git
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: perplexityai>=0.22.2
Requires-Dist: python-dotenv>=1.2.1

# gesso

[![CI](https://github.com/sanchitram1/gesso/actions/workflows/ci.yml/badge.svg)
](https://github.com/sanchitram1/gesso/actions/workflows/ci.yml)
[![Coverage](https://coveralls.io/repos/github/sanchitram1/gesso/badge.svg?branch=main)
](https://coveralls.io/github/sanchitram1/gesso?branch=main)

Generate Obsidian-ready painting notes from a simple input list. The CLI reads
`PERPLEXITY_API_KEY` from your environment (or `.env`), enriches each row via
Perplexity, and writes markdown files from the bundled template.

## Pre-requisites

- [`uv`](https://astral.sh/uv) for dependency management

## Quickstart
- Install deps: `uv sync`
- Export `PERPLEXITY_API_KEY` (or add to `.env`)
- Run: ` uv run imbue --input data/input.txt --output outputs/`
  - Defaults: `--input data/input.txt --output outputs/ --cache .cache`

## Input & Template
- Input lines: `number: Title, Artist`
- Default template: `data/painting-template.md`; output files land in
`outputs/{title}.md`.
- Cache: `.cache/{title_artist}.json` to avoid duplicate API calls.
- Open TODO: make template path configurable (flag or env) so non-default
templates work.

## Flow (per painting)
1. Parse input line into `{number, title, artist}`.
2. Check cache; otherwise query Perplexity for metadata.
3. Post-process strings into Obsidian-friendly lists/links.
4. Render template placeholders and frontmatter.
5. Write markdown to the output directory.

## Module reference
- `parse_input(filepath)`: read lines into structured dicts; warns on invalid
rows.
- `get_cache_key(title, artist)`: normalize to cache filename.
- `load_from_cache / save_to_cache`: JSON cache helpers under `.cache/`.
- `query_painting_metadata(title, artist)`: Perplexity SDK wrapper using
`PERPLEXITY_API_KEY`.
- `post_process_fields(data)`: convert comma-separated strings to lists and wrap
wikilinks; drop `"Unknown"` values.
- `render_markdown(template_path, painting_data, today)`: fill template
placeholders and YAML lists.
- `write_output(output_dir, filename, content)`: ensure dirs exist and persist
markdown.
- `main(...)`: CLI orchestrator; invoked via `uv run imbue`.

## Error handling
- Missing env key: fails fast with a clear message.
- Input parse errors: warn and skip lines.
- Perplexity failures: log error and skip that painting.
- Cache/IO issues: log warnings and continue to the next item.

## Development
- Python 3.13+, managed with `uv`.
- Style: `uv run ruff format --check .` and `uv run ruff check .`
- Tests: `uv run pytest -v --cov --cov-report=xml`
- CI mirrors these steps (`.github/workflows/ci.yml`).

## Contributing
- Keep README aligned with behavior; update TODOs when adding features.
- Add tests for new parsing, templating, or API edge cases.
- Run lint/format/tests before sending changes.
