[Story-751] Add agents schema foundation

Story 751 Epic 749🔗 Chain of CustodyAgent Platform6 files · +792/−2

PR #186 · pramaan-io/pramaan-functions · merged 2026-05-20

How it flows

sequenceDiagram
  autonumber
  participant mig as Migration 0044
  participant lib as Shared lib
  participant set as Settings
  participant tst as Tests
  mig->>lib: schema + RLS + partitions + seeds
  set->>lib: agents bucket name
  lib->>lib: expose SQLAlchemy Core metadata
  lib->>lib: offload_if_large → inline or S3
  lib->>lib: fetch_offloaded → return
  tst-->>lib: verify round-trip

8e7a6b5c4d3f_0044_agents_schema_foundation.py · +433 — new methods

Method	in → out	what it does
`_create_monthly_partitions`	`(table_name, timestamp_column) → None`
`_drop_monthly_partitions`	`(table_name) → None`
`_enable_firm_rls`	`(table_name) → None`

What changed, file by file

alembic/versions/8e7a6b5c4d3f_0044_agents_schema_foundation.py+433

Alembic migration that creates the agents schema with foundation tables, RLS policies, monthly partitions, runtime grants, and MatterChatAgent tool registry seeds (per PR body).

new method	signature
`_create_monthly_partitions`	`(table_name, timestamp_column) → None`
`_drop_monthly_partitions`	`(table_name) → None`
`_enable_firm_rls`	`(table_name) → None`
`_enable_registry_rls`	`() → None`
`_disable_rls`	`(table_name) → None`
`upgrade`	`() → None`
`downgrade`	`() → None`

src/shared/s3_offload.py+114

Shared helper module with offload_if_large and fetch_offloaded that decides between inline DB storage and S3 bucket offload for agent payloads (per PR body).

new method	signature
`_s3_client`	`(settings) → Any`
`_object_key`	`(firm_id, run_id, kind, sha256, created_at) → str`
`offload_if_large`	`(content, threshold_bytes, firm_id, run_id, kind, settings, s3_client) → tuple[Stor`
`fetch_offloaded`	`(storage_mode, s3_key, inline_content, settings, s3_client) → str`

src/shared/settings.py+12

Settings module that adds the agents bucket name field and a resolver for the pramaan-agents-{env} S3 bucket (per PR body).

new method	signature
`resolved_agents_bucket_name`	`() → str`

New fields: agents_bucket_name : str | None

Kya fail ho sakta hai

alembic upgrade head stuck at 0037 (NULL client names)
full pytest fails — missing pramaan_app role
full ruff shows pre-existing lint in old migrations
mypy without targets errors out (repo quirk)

targeted ruff clean

targeted mypy clean

new s3_offload unit tests pass

import smoke passes

pre-existing DB state not this PR's scope

missing role / fixtures not introduced here

Files changed (6)

File	±
`alembic/env.py`	+4 −2
`alembic/versions/8e7a6b5c4d3f_0044_agents_schema_foundation.py` ★	+433
`src/shared/agents_db_models.py` ★	+112
`src/shared/s3_offload.py` ★	+114
`src/shared/settings.py`	+12
`tests/unit/shared/test_s3_offload.py`	+117