sdg_hub: Instructions file for Claude Code

CLAUDE.md

Project Overview

Requirements: Python 3.10+

SDG Hub is a Python framework for synthetic data generation using composable blocks and flows. Blocks are processing units that transform datasets; flows chain blocks into pipelines defined in YAML.

Core concept: dataset -> Block1 -> Block2 -> Block3 -> enriched_dataset

For architecture details, see ARCHITECTURE.md.

Agent Knowledge Base

Task	Read this first
Adding a block	docs/agent-knowledge/block-invariants.md
Adding a flow	docs/agent-knowledge/flow-invariants.md
Adding a connector	docs/agent-knowledge/connector-invariants.md
Writing tests	docs/agent-knowledge/testing-standards.md
Reviewing code	docs/agent-knowledge/grading-criteria.md
Deciding to fix vs escalate	docs/agent-knowledge/decision-rubric.md
Checking quality status	docs/agent-knowledge/QUALITY.md
All principles	docs/agent-knowledge/core-principles.md

Full index: docs/agent-knowledge/index.md

Development Commands

Use uv for all Python commands and package management.

# Install with dev dependencies
uv pip install .[dev]

# IMPORTANT: Always install pre-commit hooks after cloning
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg

# Other install targets
uv pip install .           # Core only
uv pip install .[vllm]     # With vLLM support
uv pip install .[examples] # With examples dependencies

Testing

# Unit tests (excludes slow/integration)
uv run pytest tests/blocks tests/connectors tests/flow tests/utils -m "not (examples or slow)"

# Structural tests (architecture enforcement)
uv run pytest tests/structural/

# With coverage
uv run pytest --cov=sdg_hub --cov-report=term tests/blocks tests/connectors tests/flow tests/utils

# Integration tests (requires API keys)
uv run pytest tests/integration -v -s

Linting and Formatting

uv run ruff check --fix src/ tests/    # Lint with auto-fix
uv run ruff format src/ tests/         # Format
uv run mypy src/                       # Type check