entity linkage (STIT-342)

[AlexAxthelm]

Introduce the first of the stitch "friends": Entity-linkage.

This is still a proof-of-concept (intentionally simple logic), but captures the flow of a more complex process:

• Query the paginated list endpoint to accumulate an in-memory representation of resources sufficient to identify potential matches.
• for each potential match: get the "detail" info, and confirm match.
• optionally: post to the merge endpoint

Stands as an independent FastAPI service, and includes a minimal frontend for demo purposes.

Copies parts of the api service as a framework, then some alterations to simplify. Frontend section written by chatGPT.

Auth Note: This currently passes through the user's token, rather than trying machine auth.

confirmed locally with all 3 main entrypoints in Makefile

[Copilot]

Pull request overview

Adds a new stitch-entity-linkage FastAPI deployment (copied from the existing API service patterns) and wires it into the local dev stack + frontend so a user can kick off an entity-linkage run and optionally apply merges via the Stitch API.

Changes:

• Add a new deployments/entity-linkage service (FastAPI app, auth relay, Stitch API client, /health + /start endpoints) and register it in the uv workspace/lockfile.
• Extend local dev orchestration (docker-compose + Makefile profiles) to run the new service.
• Add a minimal frontend page + config for calling the entity-linkage /start endpoint and displaying raw JSON.

Reviewed changes

Copilot reviewed 23 out of 25 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
uv.lock	Adds locked workspace package entry for stitch-entity-linkage and its dependencies.
pyproject.toml	Registers deployments/entity-linkage as a uv workspace member.
Makefile	Enables an additional compose profile for dev stack commands.
docker-compose.local.yml	Adds entity-linkage service definition, profiles, and dependencies.
deployments/stitch-frontend/src/pages/EntityLinkagePage.jsx	New UI to POST /start and display results/errors.
deployments/stitch-frontend/src/config/env.js	Adds entityLinkageBaseUrl configuration.
deployments/stitch-frontend/src/App.jsx	Adds route and navigation link to Entity Linkage page.
deployments/seed/data/004-merge-demo.json	Adds seed dataset intended to demonstrate merge scenarios.
deployments/entity-linkage/src/stitch/entity_linkage/settings.py	New settings model (env, CORS origin, auth toggle).
deployments/entity-linkage/src/stitch/entity_linkage/routers/start.py	Implements in-memory linkage run and optional merge application.
deployments/entity-linkage/src/stitch/entity_linkage/routers/health.py	Adds /health endpoint.
deployments/entity-linkage/src/stitch/entity_linkage/routers/init.py	Initializes routers package (currently whitespace-only).
deployments/entity-linkage/src/stitch/entity_linkage/py.typed	Marks package as typed for type checkers.
deployments/entity-linkage/src/stitch/entity_linkage/middleware.py	Registers CORS middleware mirroring API patterns.
deployments/entity-linkage/src/stitch/entity_linkage/main.py	Defines FastAPI app, lifespan auth validation, and router mounting.
deployments/entity-linkage/src/stitch/entity_linkage/errors.py	Adds Stitch API error wrapper type.
deployments/entity-linkage/src/stitch/entity_linkage/entities.py	Adds request/response/auth entities used by the service.
deployments/entity-linkage/src/stitch/entity_linkage/client.py	Adds httpx client for calling Stitch API list/detail/merge endpoints.
deployments/entity-linkage/src/stitch/entity_linkage/auth.py	Adds JWT validation + “transparent relay” bearer propagation.
deployments/entity-linkage/src/stitch/entity_linkage/main.py	Adds CLI entrypoint for running with uvicorn.
deployments/entity-linkage/src/stitch/entity_linkage/init.py	Adds template stub main() function (currently prints).
deployments/entity-linkage/README.md	Documents the new service at a high level.
deployments/entity-linkage/pyproject.toml	New package metadata + deps + pytest config for the deployment.
deployments/entity-linkage/Dockerfile	Docker image build for entity-linkage service using uv.
deployments/entity-linkage/.python-version	Pins Python version for this deployment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 26 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AlexAxthelm]

@jdhoffa The client for seed is set up a little differently from this one, but it looks very translatable to this structure (additions to this client).

For an llm service, I would use the mechanisms here to get resource details, then generate a set of resources (iterator, see deployments/seed/src/stitch/seed/payloads.py), and post them (payloads again, also deployments/seed/src/stitch/seed/openapi_validate.py to get validation before post). Then this branch has the mechanisms to add those new resources to the merge review pile, and boom, that's the llm review flow.

[jdhoffa]

This PR ships a new service that can perform destructive merges, but it currently doesn't have any automated test coverage.

For a new service that both decides merge candidates and can apply them, I’d block merge until there is at least coverage for the matching logic and the /start happy-path / failure-path behavior.