How to Create an Extractor

Last verified: 2026-07-26 against dev at f0388abb.

Use this guide when SDP needs a new worker that can extract fields from a document type.

Inputs

• Extractor name. It must be a valid Python identifier.
• Supported document types and dependencies.
• Target schemas/processors.
• Local and deployed queue/function-app names.
• Infrastructure owner for Azure resources.

Procedure

1. Create the extractor package.

Add extractor_apps/extractors/<extractor_name>/extractor.py with a class implementing the DocumentExtractor protocol.

1. Add extractor dependencies.

Update extractor_apps/pyproject.toml dependency groups and include the group in local development if needed.

1. Wire local container support.

Update extractor_apps/Dockerfile and compose.dev.yaml so the extractor can run locally.

1. Register the backend extractor.

Update backend/src/altaforge_sdp/extractors/extractor_registry.py.

1. Add Service Bus and infrastructure wiring.

Add a queue named after the extractor and update the relevant Terraform in altaforge-infrastructure.

1. Run locally.

Use Run extractor workers locally and extractor_apps/README.md.

1. Verify end-to-end.

Upload a representative document, process it through a batch run, and review extracted fields in the frontend or API.

Known Pitfalls

• Backend registry entries and deployed function apps are not automatically synchronized.
• Renaming/removing extractors can leave stale rows in the database.
• Some extractors have large memory requirements; deployed code 137 failures usually indicate container memory pressure.