feat(integrations): AppLookupService aggregator — Phase 3 complete

[strausmann]

Summary

Phase 3 final PR. Adds the AppLookupService aggregator that routes lookup(source_app, id) calls to the right per-app client (Snipe-IT, Grocy, Spoolman). Phase 3 (App-Lookup-Service) closes here.

The aggregator is dependency-free of its clients via a _LookupClient Protocol — no concrete-class imports, no circular dependencies. New apps (e.g. OpenFoodFacts) plug in by extending _AppName and the constructor.

What's in this PR

backend/app/services/lookup_service.py

• _LookupClient(Protocol) — minimal async lookup(identifier) -> LabelData contract. All three concrete clients satisfy it structurally.
• _AppName = Literal["snipeit", "grocy", "spoolman"] — static-analysis aid.
• AVAILABLE_APPS = get_args(_AppName) — runtime constant derived from the Literal, so adding a new app touches one place.
• UnknownAppError(Exception) — explicitly does NOT inherit from AppLookupNotFoundError. The two errors are semantically distinct: "misconfigured request" vs "entity doesn't exist".
• AppLookupService(*, snipeit, grocy, spoolman) — keyword-only init, dict-based dispatch, available_apps precomputed in __init__.

backend/tests/unit/services/test_lookup_service.py — 8 tests

• Dispatch paths for each of the three clients (verified via assert_awaited_once_with).
• UnknownAppError with bad app name in message.
• UnknownAppError lists all available apps.
• AppLookupNotFoundError from underlying client propagates unchanged.
• AVAILABLE_APPS and service.available_apps agree (cross-check).
• Non-inheritance invariant: UnknownAppError is NOT a subclass of AppLookupNotFoundError.

What's NOT in this PR

• FastAPI endpoint wiring — Phase 6.
• LabelRenderer, Templates, persistence — Phases 4, 5.

Test plan

• pytest -q → 111/111 (103 prior + 8 new).
• ruff format --check . clean.
• ruff check . clean.
• mypy app/ (strict) clean — 22 source files.

Review history (subagent-driven)

1. Implementer 3feae15 — initial commit with Protocol-typed dispatch + Literal + AVAILABLE_APPS + UnknownAppError + 8 tests.
2. Spec compliance: ✅ — every spec point + intentional improvement (kw-only init, Protocol, Literal, AVAILABLE_APPS, non-inheritance invariant) verified line-by-line.
3. Code quality: APPROVED_WITH_NITS — flagged duplicated string literals between _AppName and AVAILABLE_APPS, available_apps re-sorting on every call, and absence of docstring note about Literal being doc-only.
4. Fix commit 29ba1ad — AVAILABLE_APPS = get_args(_AppName) eliminates duplication, available_apps precomputed as plain attribute, lookup docstring extended.

Phase 3 status

With this merge, the entire Phase 3 App-Lookup-Service layer is in place:

LabelData (schemas)
   ↑
   │ produced by
   │
SnipeITClient → 8 tests   ╮
GrocyClient  → 9 tests    │← all inherit AppLookupNotFoundError
SpoolmanClient → 9 tests  ╯
   ↑
   │ dispatched by
   │
AppLookupService → 8 tests  (Protocol-typed, route by source_app)

Phase 4 (LabelRenderer + TemplateService) builds on LabelData.

Linked plan

docs/superpowers/plans/2026-05-11-label-printer-hub.md Task 3.5 closes Phase 3.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request completes Phase 3 of the label printer hub project by introducing the AppLookupService aggregator. This service acts as a central dispatcher, routing lookup calls to the appropriate per-application client (Snipe-IT, Grocy, Spoolman) without direct dependencies on their concrete implementations. The design leverages Python's Protocol for flexible client integration and provides clear error differentiation for misconfigured requests versus missing entities, enhancing the system's robustness and extensibility.

Highlights

• Protocol-based Client Integration: Introduced _LookupClient(Protocol) to define a minimal contract for per-app clients, ensuring dependency-free integration and avoiding circular dependencies by relying on structural subtyping.
• Dynamic App Management: Implemented _AppName = Literal[...] and AVAILABLE_APPS using get_args for static analysis and runtime management of available applications, simplifying the addition of new apps to a single point of modification.
• Distinct Error Handling: Defined UnknownAppError to specifically handle configuration mismatches when an unregistered app is requested, clearly distinguishing it from AppLookupNotFoundError which indicates a missing entity within a known app.
• Robust AppLookupService: Created AppLookupService with keyword-only initialization for its client dependencies and dict-based dispatch, precomputing available_apps at construction for efficiency and immutability.
• Comprehensive Unit Tests: Added 8 new unit tests covering client dispatch for Snipe-IT, Grocy, and Spoolman, UnknownAppError scenarios (including message content), AppLookupNotFoundError propagation, and consistency checks for AVAILABLE_APPS.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

Adds a new backend “App Lookup” aggregation layer that dispatches lookup(source_app, identifier) to the appropriate per-integration client (Snipe-IT, Grocy, Spoolman), providing a single entrypoint for Phase 3 of the label lookup pipeline.

Changes:

• Introduces AppLookupService with Protocol-typed client dispatch, AVAILABLE_APPS, and an UnknownAppError for unregistered apps.
• Adds unit tests covering routing, error semantics, and invariants (including non-inheritance from AppLookupNotFoundError).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
backend/app/services/lookup_service.py	New aggregator service that routes lookups to the correct integration client and exposes available-app metadata.
backend/tests/unit/services/test_lookup_service.py	New unit tests verifying dispatch behavior and error semantics for the aggregator.

[gemini-code-assist]

Code Review

This pull request introduces the AppLookupService to route lookup requests to specific application clients (Snipe-IT, Grocy, and Spoolman) using an asynchronous protocol, supported by comprehensive unit tests. Feedback identifies opportunities to improve type safety by using the _AppName literal for internal attributes and to optimize an error message by utilizing a pre-computed list of available apps.

[gemini-code-assist]

The type hints for _clients and available_apps can be made more precise by using the _AppName Literal instead of str. This improves type safety and aligns with the project's emphasis on strict typing and mypy compliance.

Suggested change

	self._clients: dict[str, _LookupClient] = {
	"snipeit": snipeit,
	"grocy": grocy,
	"spoolman": spoolman,
	}
	# Computed once at construction — _clients never mutates after __init__.
	self.available_apps: tuple[str, ...] = tuple(sorted(self._clients))
	self._clients: dict[_AppName, _LookupClient] = {
	"snipeit": snipeit,
	"grocy": grocy,
	"spoolman": spoolman,
	}
	# Computed once at construction — _clients never mutates after __init__.
	self.available_apps: tuple[_AppName, ...] = tuple(sorted(self._clients))

References

1. The repository style guide prioritizes type safety and strict mypy compliance (Rule 7). ^(link)

[gemini-code-assist]

The error message re-calculates sorted(self._clients), which is redundant as this value is already pre-computed and stored in self.available_apps during initialization. Using the existing attribute is more efficient and maintains consistency within the class.

Suggested change

	raise UnknownAppError(f"Unknown app {source_app!r}. Available: {sorted(self._clients)}")
	raise UnknownAppError(f"Unknown app {source_app!r}. Available: {self.available_apps}")