temporal-pydanticai-codeact: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python library named temporal.pydanticai.codeact, a reusable package for building agents with code execution capabilities using:

• PydanticAI (v1.27.0) - Agent framework for building production-grade GenAI applications
• Temporal (v1.19.0) - Workflow orchestration for reliable, long-running processes
• Docker Python Client (v7.1.0) - Programmatic Docker container management

The library is structured as a proper Python package under the namespace temporal.pydanticai.codeact.

Environment Setup

• Python Version: 3.13+
• Virtual Environment: .venv/ (already configured)
• Package Manager: uv (inferred from pyproject.toml structure)

Core Dependencies

• pydantic-ai (>=1.27.0): Agent framework for building type-safe AI applications
• temporalio (>=1.19.0): Workflow orchestration and durable execution
• docker (>=7.1.0): Docker Engine API client for container management

Documentation Requirements

CRITICAL: Before writing any code that uses external libraries or frameworks, you MUST check Context7 MCP for the most up-to-date documentation. Use the mcp__context7__resolve-library-id and mcp__context7__get-library-docs tools to retrieve current API references and code examples.

This is especially important for:

• PydanticAI API usage and patterns
• Python standard library updates (since this uses Python 3.13+)
• Any third-party dependencies added to the project

Common Commands

Environment Management

# Activate virtual environment
source .venv/bin/activate

# Install dependencies (when added to pyproject.toml)
uv sync

# Add new dependencies
uv add <package-name>

Development Workflow

# Run all tests
pytest

# Run tests from specific module
pytest tests/temporal/pydanticai/codeact/test_datamodels_codeact.py

# Run with verbose output
pytest -v

# Run only unit tests (no Docker/Temporal required)
pytest -m unit

# Type checking
mypy src/

# Linting
ruff check .

# Auto-fix linting issues
ruff check --fix .