How melroyanthony/provet works
Project Type and Purpose
• Type: A Python-based “full-stack” tool that runs as a CLI or as a REST API microservice.
• Purpose: Ingest veterinary consultation JSON, call OpenAI LLM, render Jinja2 templates, and emit formatted discharge notes.
Main Architectural Components
A. Client Tier
– CLI interface: provet_cli.py and provet/__main__.py
– API interface: FastAPI app defined in api/main.py, served by Uvicorn (via Docker Compose)
B. Core Application Tier (provet/core/)
– App Facade (app.py): orchestrates the workflow
– Data Models (data_models.py): domain entities (consultation, note)
– IO Manager (io_manager.py): file I/O (load JSON, write output)
– LLM Service (llm_service.py): OpenAI API calls
C. Utility Tier (provet/utils/)
– Config loader (config.py): reads .env or env vars
– Template engine (template_engine.py): wraps Jinja2, applies templates in provet/templates/
D. External Services & Data
– OpenAI API (external “LLM” cloud service)
– Local JSON files (input in data/, output in solution/)
E. Deployment & Orchestration
– Dockerfile (multi-stage build + test stage)
– docker-compose.yml (brings up the API service)
– Shell scripts (scripts/) for setup/dev/cleanup
Relationships & Data Flows
1. User invokes CLI or sends HTTP request to API.
2. CLI/HTTP handler calls Core.App facade.
3. Core.App asks IO Manager to read consultation JSON → yields Data Models.
4. Core.App passes data models to LLM Service → makes HTTP call to OpenAI → receives generated text.
5. Core.App hands text + models to Template Engine → renders Jinja2 templates (discharge_prompt.j2, system_message.j2).
6. Core.App uses IO Manager to write formatted note JSON to disk (solution/).
7. API returns JSON response; CLI writes file and/or dumps to stdout.
Architectural Patterns & Design Principles
• Facade Pattern: provet/core/app.py central orchestration
• Separation of Concerns: I/O, data modeling, LLM interaction, templating, and config are each in their own module.
• Template-Based Rendering: Jinja2 templates exist under provet/templates/.
• Multi-Stage Docker Builds: enforce tests before production image.
• Modular Deployment: same core used by both CLI and API.
Technologies & Frameworks to Annotate
• Python 3.13+, uv (dependency manager)
• FastAPI + Uvicorn (API)
• Jinja2 (templating)
• OpenAI API (LLM backend)
• Docker + Docker Compose (containerization)