[recipes] Brain health monitoring views#194
Open
alanshurafa wants to merge 4 commits into
Open
Conversation
github-actions
Bot
added
recipe
alanshurafa
added
area: recipes
Collaborator
Author
|
Conflicts with |
…class Why: views 6-8 reference public.ingestion_jobs and public.entity_extraction_queue, which live in optional companion schemas (schemas/smart-ingest and schemas/entity-extraction). Running ops-views.sql on a stock install created views 1-5, then failed at view 6 with "relation does not exist" and left the user in an ambiguous half-installed state. Wrap each optional view in DO $$ IF to_regclass(...) IS NOT NULL THEN EXECUTE 'CREATE OR REPLACE VIEW ...' END IF $$ so the file runs cleanly on any shape of install. Move the matching GRANT SELECT ... TO service_role statements inside each DO block so grants only run when the view was actually created. Emit a NOTICE for each skipped view pointing at the schema that enables it. Also refresh the file-header comment block to match the corrected schema paths (schemas/smart-ingest, schemas/entity-extraction) and note that views 6-8 are gracefully skipped rather than erroring.
Why: the Prerequisites section and the "requires" labels in the views table pointed at schemas/smart-ingest-tables and schemas/knowledge-graph, neither of which exists under those names. The actual schema directories shipped by the Wave 3 PRs are schemas/smart-ingest (ships public.ingestion_jobs) and schemas/entity-extraction (ships public.entity_extraction_queue). Users following the README literally would hit broken paths and not know where to install the optional prerequisites. Replace every reference with the real directory names (incl. the Troubleshooting section and the Steps §1 review block), and reframe the "comment out views 6-8" guidance now that the SQL guards missing tables with to_regclass instead of erroring. Paired with the SQL guard commit, this closes HIGH-1 end-to-end.
…w views Why: ops_recent_thoughts and ops_enrichment_gaps both emit left(content, 180) as a preview column without filtering on sensitivity_tier. Today the views are service_role-only, so there is no blast radius -- but the README markets them as queryable via PostgREST and "your dashboard", which primes a future maintainer to add GRANT SELECT ... TO authenticated. The moment that happens, the first 180 chars of every restricted thought flow out through these views. Add WHERE sensitivity_tier IS DISTINCT FROM 'restricted' to both views. This matches the convention used by search_thoughts_text(p_exclude_restricted) in schemas/enhanced-thoughts/schema.sql and costs one clause per view. Cheap insurance against a future "widen the grants for the dashboard" regression.
alanshurafa
force-pushed
the
contrib/alanshurafa/brain-health-monitoring
branch
from
96377dc to
3ff5306
Compare
Collaborator
Author
|
Rebased onto |
alanshurafa
added
review: ready-for-maintainer
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a recipe of operational views for monitoring an Open Brain deployment — enrichment coverage, source volume trends, stalled ingestion/extraction queues.
Five core views work on any stock Open Brain install; three additional views unlock if companion schemas are installed (smart-ingest, entity-extraction). Optional views are wrapped in
to_regclassguards so missing companion tables produce aNOTICEand skip, not an error.ops_recent_thoughts— last N thoughts with source/type/importance (restricted content excluded from preview)ops_enrichment_gaps— thoughts pending classification, grouped by sourceops_source_volume_by_day— capture volume per source over 30 daysops_type_distribution— type-class breakdown with percentagesops_quality_distribution— quality_score distribution bucketsops_ingestion_summary— (optional, requires smart-ingest schema) jobs by statusops_stalled_entity_queue— (optional, requires entity-extraction schema) items stuck in pending/retryops_graph_coverage— (optional, requires entity-extraction schema) fraction of thoughts with extracted entitiesWhy
Hitting the Supabase dashboard + writing ad-hoc SQL is fine for one-brain inspection, but once a brain exceeds 10k thoughts, operators need recurring views to notice enrichment drift, source outages, and queue stalls. These views are a zero-dependency reference set anyone can
psql -f ops-views.sqland get.Grants are service_role only — no anon, no authenticated. Previews filter
WHERE sensitivity_tier IS DISTINCT FROM 'restricted'to match the convention from the enhanced-thoughts schema.Test plan
ops-views.sqlto a stock Open Brain project — verify views 1-5 appear, views 6-8 emitNOTICEand skipSELECT * FROM ops_recent_thoughts LIMIT 5;— verify no restricted content in preview columnmetadata.jsonpasses.github/metadata.schema.json