yuqei/ai-contract-platform
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
1d6a56146dc0be8bd2f8c15cee78c7e73ecee6e3
ai-contract-platform/project-docs/V2-phase3-ai-platform-trace-policy-config-2026-07-03.md
T
yuqei a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
Details
release: freeze V2 release candidate
2026-07-12 15:32:24 +08:00

6.6 KiB
Raw Blame History

V2 Phase 3 AI Platform Trace Policy Configuration

Date: 2026-07-03

Status

Local implementation completed.

This slice makes AI Trace retention, redaction, and archive behavior configurable without changing the production worker enablement decision.

Current operational decision:

  • Smoke can keep YUQEI_WORKER_TRACE_GOVERNANCE_ENABLED=true.
  • Production keeps Trace governance disabled for now.
  • The 24-hour smoke observation remains a pre-production checklist item, not a blocker for current development.

Schema

New AI Platform migration:

20260703_0021_add_trace_governance_policies.py

New table:

trace_governance_policies

The first slice stores one policy per tenant:

  • tenant_id
  • enabled
  • default_retention_days
  • default_redaction_policy
  • require_redaction
  • auto_archive
  • changed_by
  • change_note
  • updated_at

Default policy is intentionally conservative:

  • enabled=false
  • default_retention_days=90
  • default_redaction_policy=default
  • require_redaction=false
  • auto_archive=true

Because the default is disabled, existing production/smoke behavior does not change until an administrator enables the policy for a tenant.

Runtime API

New endpoints:

GET /api/v1/runtime/trace-governance/policy
PUT /api/v1/runtime/trace-governance/policy

The endpoints use the existing tenant context:

  • With X-Tenant-Id, the tenant-specific policy is read/written.
  • Without X-Tenant-Id, the default tenant policy is used.

Contract Web local proxy:

GET /api/ai-platform/runtime/trace-governance/policy
PUT /api/ai-platform/runtime/trace-governance/policy

Worker Behavior

The policy is applied in two places:

  1. When a new AI run audit is created.
  2. At the start of each Trace governance worker run, for a bounded batch of existing unconfigured traces.

Rules:

  • Existing explicit retention_until is not overwritten.
  • Existing non-default redaction policy is not overwritten.
  • Existing redaction_status=redacted is not reverted.
  • If policy is disabled, existing explicit redaction_status=pending|required and explicit expired retention_until behavior remains unchanged.
  • If policy is enabled and require_redaction=true, unconfigured traces are marked redaction_status=required.
  • If policy is enabled and auto_archive=false, the worker does not archive traces only because of retention due dates.

Admin UI

/admin/ai-runtime now includes a Trace policy form in the Trace governance panel.

Controls:

  • Enabled
  • Retention days
  • Redaction policy
  • Require redaction
  • Auto archive
  • Change note

The existing Trace governance status panel still shows heartbeat, last-30-minute execution count, recent run count, failed count, latest runs, and manual run action.

Validation

Local validation passed:

python -m py_compile `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\repository.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\persistence\audit.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\persistence\worker_runtime.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\api\system.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\schema_check.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\models.py

python -m pytest yuqei-ai-platform\services\ai-platform-api\tests -q
python -m pytest yuqei-ai-platform\services\worker\tests -q
npm run web:typecheck

Results:

  • AI Platform API tests: 61 passed.
  • Worker tests: 6 passed.
  • Contract Web typecheck: passed.

Targeted behavior verified:

  • Policy GET returns a tenant-scoped disabled default.
  • Policy PUT persists tenant-scoped retention/redaction/archive settings.
  • New traces inherit enabled policy defaults.
  • Existing unconfigured SQLAlchemy traces are picked up by the next governance run.
  • answer_only and prompt_only redaction semantics remain intact.
  • schema-check now verifies the policy table and policy columns.

Remaining Items

  • Keep production Trace governance disabled until the pre-production observation gate is completed.

Smoke Verification

Remote smoke verification completed on 192.168.3.90.

Deployment artifacts:

  • Full smoke deploy: project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-03T17-18-54
  • Web proxy environment fix redeploy: project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-03T17-30-17

Schema:

AI Platform Alembic version: 20260703_0021
GET http://192.168.3.90:18101/api/v1/runtime/schema-check -> ok

Schema-check highlights:

  • Database: yuqei_ai
  • Alembic actual/expected: 20260703_0021
  • Core tables checked: 16
  • Tenant column tables checked: 8
  • Trace governance columns checked: 11
  • PostgreSQL extensions: pg_trgm,vector
  • pgvector schema: ok

Policy API:

GET /api/v1/runtime/trace-governance/policy
PUT /api/v1/runtime/trace-governance/policy
POST /api/v1/runtime/trace-governance/run-once

Verified tenant: trace-policy-smoke-20260703

Applied smoke policy:

{
  "enabled": true,
  "default_retention_days": 0,
  "default_redaction_policy": "answer_only",
  "require_redaction": true,
  "auto_archive": true
}

Verified real Trace:

  • Created smoke AI Trace: run-c2f71bb35a9f.
  • New Trace inherited policy fields: redaction_status=required, redaction_policy=answer_only, retention_until populated.
  • Manual governance run: worker-run-55d177effe2b.
  • Governance stats: scanned=1, redacted=1, archived=1, failed=0.
  • Detail after governance: answer=[REDACTED], quality_summary=[REDACTED], archive_status=archived.

Worker:

  • Smoke .env.smoke: YUQEI_WORKER_TRACE_GOVERNANCE_ENABLED=true.
  • Worker container settings verified: trace_governance_enabled=True, interval 300, batch limit 100.
  • Recent worker_run_executions show scheduled trace-governance-worker runs with status=succeeded.

Admin UI:

  • GET http://192.168.3.90:13000/admin/ai-runtime: HTTP 200.
  • Browser-rendered page contains Trace governance panel, Trace policy form, retention days input, and manual run button.
  • Screenshot artifact: project-docs/qa-artifacts/v2-trace-policy-smoke-verification/ai-runtime-remote-trace-policy.png.
  • Layout check at 1440px: no horizontal overflow.

Implementation note:

  • Contract Web needed AI_PLATFORM_API_BASE_URL=http://ai-platform-api:8101 in Docker compose so server-side Next API proxies can reach AI Platform from inside the container.

Remaining Items

  • Keep production Trace governance disabled until the pre-production observation gate is completed.
Reference in New Issue View Git Blame Copy Permalink