fastworkflow: Instructions file for Codex

Agent Instructions

This file provides guidance to AI coding agents when working with code in this repository.

Activate the local .venv Python environment before running tests or scripts.

On a CUDA machine, poetry install alone gives you CPU torch. The default is pinned to CPU-only wheels, because Poetry cannot lock torch from the CPU and CUDA indexes at once. GPU users need both steps:

poetry install --with gpu && make install-gpu-torch

There is no warning if you skip it — training silently runs on CPU, which is much slower and easy to mistake for the suite or the model being slow. make install-gpu-torch verifies CUDA is usable before reporting success, so run python -c "import torch; print(torch.cuda.is_available())" if you are unsure which you have.

Project Overview

fastWorkflow is a Python framework for building NLP-driven workflows and AI agents with deterministic or LLM-powered business logic. It enables "AI-enabling" existing Python applications by wrapping their classes and methods with an intent-detection and parameter-extraction pipeline built on DSPy, PyTorch/Transformers, scikit-learn utilities, and Pydantic.

Testing Philosophy

(from .cursor/rules/testing_rules.mdc):

• Don't use Mock fixtures — all tests are integration tests against real components
• Use the real test workflows in tests/example_workflow/, tests/hello_world_workflow/, and tests/todo_list_workflow/
• Do NOT remove pytest tests without explicit user approval

Never run two full suites at once

The full suite loads BERT-family models, and two concurrent runs exceed this box's 31 GB. The second run dies to the OOM killer partway through — observed twice at ~69%, reported as PYTEST_EXIT=137, which reads like a crash in whatever test was running rather than a resource problem. If you are working alongside another agent, serialise the suite runs; a run measured against a tree another agent is still editing is worthless anyway, so waiting costs nothing.