generated from john/python-template
zoltan57andCopilot App
2ccea77520
Pure remediation; no behavior change. Every item traces to a finding in docs/architecture_code_review_2026-08-17.md. Deletions - Delete app_state.py, which had zero importers and whose get_session_factory raised TypeError at runtime [HIGH-01]. - Delete services/transcription.py and point build_prompt_execution imports at services/sources.py; drop the store.py compatibility aliases [MED-05]. - Delete ServiceBase.queue and its unparameterized asyncio.Queue [MED-07]. - Delete db/operations.get_next_queued_job, a divergent duplicate [CRIT-01]. - Drop the discarded load_docs parameter from list_jobs [LOW-03]. Config - Delete worker_retry_backoff_seconds; no backoff behavior existed anywhere, so wiring it would have been a new feature [MED-02]. - Wire sqlite_check_same_thread through get_engine. The engine hardcoded the setting's own default, so this preserves behavior exactly [MED-02]. - Replace DATABASE_URL in docker-compose.yml with the nested DATABASE__DRIVER / DATABASE__PATH names. Settings uses env_nested_delimiter with extra="ignore", so DATABASE_URL was silently discarded [MED-10]. UI - Move the 23KB inline VIBESCRIBE_LOGO_SVG to ui/static/vibescribe_logo.svg and load it through a cached read_svg sibling of read_css [MED-09]. - Route the portrait upload failure through error_presenter.show_error [LOW-07]. - Cancel the job detail auto-refresh timer instead of only deactivating it, and name its interval constant [LOW-06]. Worker - Make WorkerNotifier runtime_checkable and validate the resolved object in resolve_worker_notifier, which previously returned any non-None attribute unchecked [LOW-04]. Docs and lint - Fix two stale paths in services.instructions.md, one of which pointed at the module deleted here [LOW-02]. - ruff check --fix to zero [LOW-01]. Verified: 264 passed, 4 skipped; ruff check clean. Co-authored-by: Copilot App <[email protected]>
78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
---
|
|
description: Follow these guidelines when editing the services
|
|
applyTo: 'src/transcription/services/*.py'
|
|
---
|
|
|
|
# Services
|
|
|
|
## Structure
|
|
|
|
- Project core data models defined in [models](../../src/transcription/db/models.py)
|
|
- 1 service class per data model
|
|
- Only services directly interact with the database, and only through async methods
|
|
- Services are completely independent of one another. Any operation that needs to use more than a single service, which is most of them, needs to have a separate orchestration function.
|
|
|
|
## Error Handling
|
|
|
|
- Service-specific errors defined at the top of the respective module and inherit from `AppError`
|
|
- Use a context manager for large `try/except` blocks like `handle_transcription_errors` in [sources](../../src/transcription/services/sources.py)
|
|
|
|
## Checklist
|
|
|
|
- [ ] Uses `ServiceBase` for common logic
|
|
- [ ] CRUD methods created at the top
|
|
- [ ] Session kwarg for `AsyncSession` to pass in a session object to each method
|
|
- [ ] Services use `self._session_scope` in their methods to pass the session thru.
|
|
- Multiple operations on the same object(s) require sharing a session between all the methods used.
|
|
|
|
## CRUD Methods
|
|
|
|
- Create, read, update, and delete, created in that order
|
|
- Name format `<operation>_<model >`, for example `create_document` or `update_job`
|
|
- All services must define these 4 methods first, and in that order
|
|
|
|
## Transaction Finalization
|
|
|
|
When a service method accepts an optional `session` kwarg, write methods must use `self._finalize` to finalize the transaction properly according to whether or not they are sharing a session.
|
|
|
|
- If `session` is `None`: the method owns the transaction and should `commit()`.
|
|
- If `session` is provided: the method must **not** commit; it should `flush()` so IDs and FK values are available to the caller's transaction.
|
|
- Use `refresh()` on returned ORM objects when the caller needs DB-populated values (defaults, triggers, merged state).
|
|
|
|
Recommended helper behavior:
|
|
|
|
- Inputs: active session object, original `session` arg (or a boolean ownership flag), and an optional list of objects to refresh.
|
|
- Logic: `commit` when service-owned session, `flush` when caller-owned session, then refresh requested objects.
|
|
|
|
This keeps orchestration functions atomic: they can pass one shared session across multiple services and commit exactly once at the workflow boundary.
|
|
|
|
## Workflow Transaction Boundaries
|
|
|
|
For multi-step job lifecycles (for example queued transcription jobs), orchestration functions must use explicit transaction phases.
|
|
|
|
Required boundary model:
|
|
|
|
- **Transaction A (claim):** transition `JobStatus.QUEUED -> JobStatus.PROCESSING` and commit immediately.
|
|
- Perform provider/network work **outside** database transactions.
|
|
- **Transaction B (terminal success):** write transcript content and set `JobStatus.TRANSCRIBED` in the same shared-session commit.
|
|
- **Transaction B (terminal failure):** write transcript error detail and set `JobStatus.FAILED` in the same shared-session commit.
|
|
- **Transaction C (retry path):** write transcript error detail, increment retry count, and set `JobStatus.QUEUED` in one shared-session commit.
|
|
|
|
Atomicity rules:
|
|
|
|
- Never commit transcript updates separately from the paired terminal/retry job status change.
|
|
- Terminal state (`TRANSCRIBED` or `FAILED`) and transcript row changes must succeed or roll back together.
|
|
- Retry persistence (`QUEUED` + retry increment + error detail) must succeed or roll back together.
|
|
|
|
Separation of concerns:
|
|
|
|
- Worker modules should stay lightweight and delegate lifecycle transitions to service/workflow orchestration functions.
|
|
- In `workflows.py`, `process_queued_job` should own one complete attempt lifecycle: `QUEUED -> PROCESSING -> TRANSCRIBED|FAILED`.
|
|
- In `workflows.py`, `advance_job` should coordinate broader status progression around attempts (for example retry scheduling from `FAILED -> QUEUED`).
|
|
- Services should expose session-aware write helpers (flush on caller-owned session) so orchestration controls commit boundaries.
|
|
- Backoff/sleep behavior must run outside transactional scopes.
|
|
|
|
# Service Composition
|
|
|
|
Some operations, like uploading a picutre, require modifications to multiple tables, which can be done by composing methods from the service object into a separate function.
|