Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
#################################################################################
################################# HELPERS #################################
#################################################################################
LOCAL_IMAGE := pipelex-api:local
HUB_IMAGE_NAME := pipelex/pipelex-api
HUB_TAG ?= latest
HUB_IMAGE := $(HUB_IMAGE_NAME):$(HUB_TAG)
ENV_FILE ?= .env
CONTAINER_NAME ?= pipelex-api
define HELP_LOCAL
$(GREEN)Run the API locally — two ways:$(RESET)
$(YELLOW)Native (uvicorn, hot reload — fastest dev loop):$(RESET)
make run$(RESET): Run the API with uvicorn against the pipelex of this repository (requires `make install` first).
$(YELLOW)Docker (closest to what's deployed):$(RESET)
make docker-build$(RESET): Build the API image from local source, with the repository root as the build context.
make docker-run$(RESET): Build + run the image on http://localhost:8081 (foreground, Ctrl+C to stop).
make docker-smoke$(RESET): Boot the local image and check /health and the versions /v1/version reports (SMOKE_IMAGE=<tag> for another).
make docker-run-hub$(RESET): Pull + run the PUBLISHED Docker Hub image (no local build). Tag: make docker-run-hub HUB_TAG=0.5.0
make docker-stop$(RESET): Force-stop the Docker container.
make docker-logs$(RESET): Tail Docker container logs.
$(YELLOW)Local Temporal dev server (when TEMPORAL is enabled in config):$(RESET)
make temporal-server$(RESET) ($(GREEN)ts$(RESET)): Start a local Temporal dev server (:7233, UI :8233) WITH search attributes registered.
make temporal-server-bare$(RESET) ($(GREEN)ts-bare$(RESET)): Start it WITHOUT search attributes (reproduce the missing-attribute error).
make temporal-stop$(RESET) ($(GREEN)tstop$(RESET)): Stop the local Temporal dev server.
$(YELLOW)Send an MTHDS bundle through the API (resolves like `pipelex run bundle`):$(RESET)
make bundle-run$(RESET) BUNDLE=<dir|.mthds>: POST the bundle to a running API and print the response (start `make run` first).
make bundle-validate$(RESET) BUNDLE=<dir|.mthds>: Dry-run validate the bundle via /v1/validate — no pipe_code/inputs, no inference, no cost.
make bundle-resolve$(RESET) BUNDLE=<dir|.mthds>: Resolve the bundle to its normalized crate via /v1/resolve — no inference, no cost.
make bundle-codegen$(RESET) BUNDLE=<dir|.mthds> TARGET=<t>: Project typed artifacts + codegen.lock via /v1/codegen (ts-zod|python-pydantic|python-structures).
make bundle-curl$(RESET) BUNDLE=<dir|.mthds>: Emit a ready-to-run curl command for the bundle.
make bundle-postman$(RESET) BUNDLE=<dir|.mthds>: Push request(s) into the live Pipelex FastAPI Postman collection.
make bundle-dry$(RESET) BUNDLE=<dir|.mthds>: Print the request body only — touch nothing.
Optional: ENDPOINT=execute|start|validate|resolve|codegen|both
PIPE=<code> INPUTS=<path> NAME=<folder> ALLOW_SIGNATURES=1 TARGET=<codegen target>
CALLBACK_URL=<url> BASE_URL=<url> TOKEN=<bearer> ARGS=<extra>
(the async start endpoint needs CALLBACK_URL — set it here, or via CALLBACK_URL in .env)
endef
export HELP_LOCAL
.PHONY: docker-build docker-run docker-smoke docker-run-hub docker-stop docker-logs
.PHONY: temporal-server ts temporal-server-bare ts-bare tsb temporal-stop tstop
.PHONY: check-bundle-arg bundle-run bundle-validate bundle-resolve bundle-codegen bundle-curl bundle-postman bundle-dry
#################################################################################
################################# API #################################
#################################################################################
# Build the generic pipelex-api image from local source. The build context is the repository root,
# because the image installs pipelex from the same commit as the server (see the Dockerfile's header).
docker-build:
@echo "\n=== Build $(LOCAL_IMAGE) from local source ==="
docker build --platform linux/amd64 -f $(CURDIR)/Dockerfile -t $(LOCAL_IMAGE) $(WORKSPACE_ROOT)
# Run the API on http://localhost:8081, foreground. Reads all env from .env.
# Required: OPENAI_API_KEY (only if you keep the bundled backends).
# Optional: AUTH_MODE, API_KEY, JWT_SECRET_KEY (see .env.example).
docker-run: docker-build
@docker rm -f $(CONTAINER_NAME) 2>/dev/null || true
@test -f $(ENV_FILE) || (echo "ERROR: $(ENV_FILE) not found. Copy .env.example to .env and fill it in." && exit 1)
@echo "\n=== Run $(LOCAL_IMAGE) on http://localhost:8081 — Ctrl+C to stop ==="
docker run --rm --name $(CONTAINER_NAME) -p 8081:8081 \
--env-file $(ENV_FILE) \
$(LOCAL_IMAGE)
# Pull and run the PUBLISHED image from Docker Hub — no local checkout/build needed.
# Same env contract as docker-run (reads all env from .env).
# Required: OPENAI_API_KEY (only if you keep the bundled backends).
# Optional: AUTH_MODE, API_KEY, JWT_SECRET_KEY (see .env.example).
# Override the published tag with HUB_TAG, e.g. make docker-run-hub HUB_TAG=0.5.0
docker-run-hub:
@docker rm -f $(CONTAINER_NAME) 2>/dev/null || true
@test -f $(ENV_FILE) || (echo "ERROR: $(ENV_FILE) not found. Copy .env.example to .env and fill it in." && exit 1)
@echo "\n=== Pull $(HUB_IMAGE) from Docker Hub ==="
docker pull $(HUB_IMAGE)
@echo "\n=== Run $(HUB_IMAGE) on http://localhost:8081 — Ctrl+C to stop ==="
docker run --rm --name $(CONTAINER_NAME) -p 8081:8081 \
--env-file $(ENV_FILE) \
$(HUB_IMAGE)
# Boot an image and check that it serves: `/health` answers, and `/v1/version` reports this
# repository's version for both the server and the pipelex it runs, which is the lockstep the release
# promises. Pull-request CI runs it on the image `docker-build` made, and `deploy-docker-hub` runs it
# on the image it is about to push. The OpenAI key is a placeholder: boot requires one, and neither
# route reaches a provider. SMOKE_IMAGE=<tag> names another image.
SMOKE_IMAGE ?= $(LOCAL_IMAGE)
SMOKE_CONTAINER ?= pipelex-api-smoke
SMOKE_PORT ?= 18081
SMOKE_TIMEOUT ?= 90
docker-smoke:
@echo "\n=== Smoke-test $(SMOKE_IMAGE): /health, then /v1/version against $(VERSION) ==="
@docker rm -f $(SMOKE_CONTAINER) >/dev/null 2>&1 || true
@docker run --detach --platform linux/amd64 --name $(SMOKE_CONTAINER) \
-p 127.0.0.1:$(SMOKE_PORT):8081 \
-e OPENAI_API_KEY=smoke-test-placeholder \
$(SMOKE_IMAGE) >/dev/null
@healthy=""; \
for attempt in $$(seq 1 $(SMOKE_TIMEOUT)); do \
if curl -fsS http://127.0.0.1:$(SMOKE_PORT)/health >/dev/null 2>&1; then healthy=1; break; fi; \
if [ "$$(docker inspect --format '{{.State.Running}}' $(SMOKE_CONTAINER) 2>/dev/null)" != "true" ]; then break; fi; \
sleep 1; \
done; \
if [ -z "$$healthy" ]; then \
echo "ERROR: $(SMOKE_IMAGE) did not answer /health within $(SMOKE_TIMEOUT)s. Its logs:"; \
docker logs $(SMOKE_CONTAINER) 2>&1 | tail -60; \
docker rm -f $(SMOKE_CONTAINER) >/dev/null 2>&1; \
exit 1; \
fi; \
python3 $(CURDIR)/scripts/check_served_version.py http://127.0.0.1:$(SMOKE_PORT) --version $(VERSION); \
exit_code=$$?; \
docker rm -f $(SMOKE_CONTAINER) >/dev/null 2>&1; \
exit $$exit_code
docker-stop:
@docker rm -f $(CONTAINER_NAME) 2>/dev/null && echo "Stopped $(CONTAINER_NAME)" || echo "$(CONTAINER_NAME) was not running"
docker-logs:
docker logs -f $(CONTAINER_NAME)
#################################################################################
################################# TEMPORAL #################################
#################################################################################
# Pipelex attaches these five custom Keyword search attributes to every workflow
# start. A namespace missing them rejects StartWorkflow with "Namespace <ns> has
# no mapping defined for search attribute ...". `temporal-server` pre-registers
# them so /v1/execute and /v1/start work out of the box;
# `temporal-server-bare` omits them so you can reproduce the missing-attribute
# error (SearchAttributeRegistrationError). Keep in lockstep with
# [temporal.search_attributes].attributes in the pipelex config.
TEMPORAL_SEARCH_ATTRS := PipeCode PipelineRunId SessionId UserId DomainCode
# Start a local Temporal dev server WITH the search attributes registered. Only
# needed when the API runs with TEMPORAL enabled (selected_server pointed at the
# local server). Runs in the foreground — start it in its own terminal.
temporal-server:
@if ! command -v temporal >/dev/null 2>&1; then \
echo "ERROR: 'temporal' CLI not found. Install it with: brew install temporal"; \
exit 1; \
fi
@echo "• Temporal Web UI at http://localhost:8233"
@echo "• Temporal gRPC service at localhost:7233"
@echo "• Registering search attributes: $(TEMPORAL_SEARCH_ATTRS)"
@echo "• Press Ctrl+C to stop"
temporal server start-dev $(foreach attr,$(TEMPORAL_SEARCH_ATTRS),--search-attribute $(attr)=Keyword)
ts: temporal-server
# Start the dev server WITHOUT the search attributes, to reproduce the
# missing-search-attribute error on /v1/execute and /v1/start.
temporal-server-bare:
@if ! command -v temporal >/dev/null 2>&1; then \
echo "ERROR: 'temporal' CLI not found. Install it with: brew install temporal"; \
exit 1; \
fi
@echo "• Temporal Web UI at http://localhost:8233"
@echo "• Temporal gRPC service at localhost:7233"
@echo "• NO search attributes registered — workflow starts are rejected when [temporal.search_attributes].enabled = true (use this to test the error path)"
@echo "• Press Ctrl+C to stop"
temporal server start-dev
ts-bare: temporal-server-bare
tsb: temporal-server-bare
# Stop the local Temporal dev server. Only kills processes on :7233 whose
# command is the Temporal binary, so an unrelated service bound to that port
# is left alone.
temporal-stop:
@PIDS=$$(lsof -tiTCP:7233 -sTCP:LISTEN 2>/dev/null); \
if [ -z "$$PIDS" ]; then \
echo "• No process found on port 7233"; \
else \
for PID in $$PIDS; do \
CMD=$$(ps -p $$PID -o comm= 2>/dev/null); \
case "$$CMD" in \
*temporal*) kill $$PID && echo "• Killed Temporal server (PID $$PID)";; \
*) echo "• Skipped PID $$PID on :7233 — not a Temporal process ($$CMD)";; \
esac; \
done; \
fi
tstop: temporal-stop
#################################################################################
########################## RUN A BUNDLE VIA THE API #########################
#################################################################################
# Resolve an MTHDS bundle the same way `pipelex run bundle <path>` does and send
# it to the API as a request — run it directly, dry-run validate it, resolve it
# to its normalized crate, project typed codegen artifacts, emit curl, push a
# Postman query, or just print the body. The method travels as `files`, every
# file of its tree. Runs the skill's helper script with OUR venv python, which
# the targets install first: the script lists the tree with the `mthds` package
# and reads the runner's tree limits from `pipelex_api`.
#
# make bundle-run BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
# make bundle-validate BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
# make bundle-resolve BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
# make bundle-codegen BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard TARGET=ts-zod
# make bundle-curl BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
# make bundle-postman BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
# make bundle-dry BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard
#
# Only execute/start trigger inference. bundle-validate (/v1/validate),
# bundle-resolve (/v1/resolve), and bundle-codegen (/v1/codegen) are free —
# parse/load/dry-run only — so they hardcode --run.
#
# Optional pass-throughs: ENDPOINT, PIPE, INPUTS, NAME, ALLOW_SIGNATURES,
# TARGET (codegen only — required), RENDER (validate only — e.g. RENDER=markdown reproduces a skill-driven
# validate, response carries rendered_markdown), CALLBACK_URL (all modes);
# BASE_URL, TOKEN (run/curl); ARGS for anything else.
# The async start endpoint requires CALLBACK_URL — pass it here, or set
# CALLBACK_URL in .env (make exports it to the script). bundle-postman needs
# POSTMAN_API_KEY in the environment (it lives in ~/.zshenv, so any zsh-launched
# make has it).
BUNDLE_SCRIPT := .claude/skills/postman-bundle/scripts/build_postman_query.py
BUNDLE_OPTS = $(if $(ENDPOINT),--endpoint $(ENDPOINT)) $(if $(PIPE),--pipe $(PIPE)) $(if $(INPUTS),--inputs $(INPUTS)) $(if $(NAME),--name $(NAME)) $(if $(ALLOW_SIGNATURES),--allow-signatures) $(if $(TARGET),--target $(TARGET)) $(if $(RENDER),--render $(RENDER)) $(if $(CALLBACK_URL),--callback-url '$(CALLBACK_URL)') $(ARGS)
BUNDLE_RUN_OPTS = $(if $(BASE_URL),--base-url $(BASE_URL)) $(if $(TOKEN),--token $(TOKEN))
check-bundle-arg:
@test -n "$(BUNDLE)" || { echo "ERROR: set BUNDLE=<bundle dir or .mthds file>, e.g. make bundle-run BUNDLE=../../pipelex-demos/mthds-wip/fashion_moodboard"; exit 1; }
bundle-run: install check-bundle-arg
$(call PRINT_TITLE,"Running bundle against the API")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --run $(BUNDLE_RUN_OPTS) $(BUNDLE_OPTS)
# Dry-run validate via /v1/validate — hardcodes --endpoint validate (so don't
# pass ENDPOINT here). NAME/ALLOW_SIGNATURES/RENDER/BASE_URL/TOKEN/ARGS still
# apply (RENDER=markdown reproduces a skill-driven validate); PIPE/INPUTS are
# intentionally omitted — the validate endpoint ignores them.
bundle-validate: install check-bundle-arg
$(call PRINT_TITLE,"Validating bundle via the API - dry-run with no inference")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --run --endpoint validate $(if $(ALLOW_SIGNATURES),--allow-signatures) $(if $(RENDER),--render $(RENDER)) $(if $(NAME),--name $(NAME)) $(BUNDLE_RUN_OPTS) $(ARGS)
# Resolve the bundle's closure to its normalized library crate via /v1/resolve —
# no inference, no dry-run sweep, no cost. PIPE/INPUTS are intentionally
# omitted — the crate routes take neither.
bundle-resolve: install check-bundle-arg
$(call PRINT_TITLE,"Resolving bundle to its normalized crate via the API")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --run --endpoint resolve $(if $(NAME),--name $(NAME)) $(BUNDLE_RUN_OPTS) $(ARGS)
# Project typed artifacts + codegen.lock via /v1/codegen — no inference, no
# cost. TARGET is required: ts-zod | python-pydantic | python-structures.
bundle-codegen: install check-bundle-arg
@test -n "$(TARGET)" || { echo "ERROR: set TARGET=<ts-zod|python-pydantic|python-structures>, e.g. make bundle-codegen BUNDLE=... TARGET=ts-zod"; exit 1; }
$(call PRINT_TITLE,"Generating typed artifacts via the API codegen route")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --run --endpoint codegen --target $(TARGET) $(if $(NAME),--name $(NAME)) $(BUNDLE_RUN_OPTS) $(ARGS)
bundle-curl: install check-bundle-arg
$(call PRINT_TITLE,"Emitting curl for bundle")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --curl $(BUNDLE_RUN_OPTS) $(BUNDLE_OPTS)
bundle-postman: install check-bundle-arg
$(call PRINT_TITLE,"Pushing Postman query for bundle")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) $(BUNDLE_OPTS)
bundle-dry: install check-bundle-arg
$(call PRINT_TITLE,"Bundle request body - dry run only")
$(VENV_PYTHON) $(BUNDLE_SCRIPT) $(BUNDLE) --dry-run $(BUNDLE_OPTS)