pydantic-agent

CLI-first toolkit of composable AI recipes for local models (Ollama, LM Studio, vLLM). Each recipe is a standalone CLI tool with stdin/stdout JSON piping, provider-neutral profiles, and playbook auto-capture.

dstroe2000 0 Updated 2mo ago

SKILL.md

Pydantic Agent Skill

Composable recipe toolkit for building with local AI models using Pydantic AI.

Architecture

CLI-first: every recipe is python -m recipes.<name> with JSON stdin/stdout
Provider-neutral: config.yaml profiles for Ollama, LM Studio, vLLM, Unsloth Studio
Pydantic-native: output_type for validated LLM output, BaseModel for contracts
Composable: pipe recipes via Unix pipes (recipe A | recipe B)
Observable: auto-logged to playbooks/default.jsonl

Recipe Index

Recipe	File	Use Case
`infra_health_check`	`recipes/infra_health_check.py`	Validate endpoint connectivity and model availability
`structured_extraction`	`recipes/structured_extraction.py`	Extract structured data from text with user-defined schema
`topic_extractor`	`recipes/topic_extractor.py`	Extract N topics with confidence scores
`text_classifier`	`recipes/text_classifier.py`	Classify text into user-defined categories
`conversational_agent`	`recipes/conversational_agent.py`	Multi-turn conversation with session persistence
`embedding_generator`	`recipes/embedding_generator.py`	Generate embeddings via local embedding models
`rag_agent`	`recipes/rag_agent.py`	RAG: index, query, list, clear collections with lifecycle tracking

Shared Infrastructure

Module	File	Purpose
Config	`recipes/common/config.py`	Profile loader, CLI arg merging, resolution hierarchy
Models	`recipes/common/models.py`	`get_chat_model()` — provider-neutral chat model factory
Embeddings	`recipes/common/embeddings.py`	`get_embedder()` — provider-neutral embedding factory
Envelope	`recipes/common/envelope.py`	`RecipeEnvelope` — standard output wrapper
Contracts	`recipes/common/contracts.py`	Base `RecipeInput`/`RecipeOutput` classes
Logging	`recipes/common/logging.py`	Playbook auto-capture (envelope to JSONL)

Resources (progressive disclosure)

Usage — how to run recipes:

resources/usage_guide.md — Per-recipe examples, flags, piping patterns, shared flags
resources/key_patterns.md — Code patterns: agents, profiles, history, RAG, envelopes, testing

Deep context — why it was built this way (read when extending, debugging design choices, or explaining trade-offs):

README.md — Setup guide, project structure, dependency overview
docs/specs/2026-03-28-pydantic-ai-recipes-design.md — Full design spec with 25 documented decisions (D1–D25)
docs/specs/2026-03-28_impl_insights.md — Implementation insights collected during build: what worked, why, and lessons learned
docs/specs/2026-03-28-implementation-plan.md — Original step-by-step implementation plan

Configuration

Edit config.yaml for profiles. Resolution: CLI flags > RECIPE_* env vars > profile > defaults.

Permissions

Pre-configured in .claude/settings.local.json — no prompts needed for common operations:

Pattern	Covers
`python -m recipes.:*`	Running any recipe
`python -m pytest:*`	Running tests
`pip install:*`	Installing dependencies
`curl -s http://localhost:*`	Ollama health checks
`rm -rf /tmp/test_:*`	Test cleanup in /tmp
`echo:`, `timeout:`, `mkdir:*`	Piping, timeouts, directories

Testing

pytest tests/unit/ -v      # Fast, no Ollama needed
pytest tests/integration/  # Needs Ollama running