Feat/build insight generation service

[AAdewunmi]

Summary

Builds the insight generation service for StudyBuddy’s deterministic NLP workflow.

Changes

• Added service-owned insight generation through generate_insight_for_session.
• Added note aggregation, deterministic analysis, source hashing, persistence, and idempotent reuse.
• Added user-scoped insight selectors through session ownership.
• Added integration tests for generation, persistence, permissions, idempotency, changed notes, empty notes, and selector scoping.
• Added an architecture boundary test to prevent views from importing NLP internals directly.
• Allowed empty keyword lists for low-information insights with a schema migration.

Behaviour

• Users can generate insights only for their own study sessions.
• Unchanged notes reuse the existing StudyInsight.
• Changed notes produce a new source hash and a new insight.
• Sessions without notes still produce a low-confidence, honest result.
• Views are expected to call services/selectors instead of NLP helpers directly.

Why

Keeps insight generation behind a service boundary so future views and UI work can use one workflow without duplicating NLP, permission, hashing, or persistence logic.

Validation

• python -m black . --check
• python -m ruff check .
• pytest -q
• Host-side PostgreSQL suite with TEST_DATABASE_URL=postgres://studybuddy:studybuddy@localhost:5432/studybuddy_test

Result

Docker suite passed with 158 passed. Host-side suite passed after fixing empty keyword validation.

Notes

Docker Compose does not bind-mount the source tree into web, so rebuild the image before relying on container test results for local code changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!