Skip to content

AGENTS.md

Latest commit

 

History

History
60 lines (52 loc) · 7.48 KB

AGENTS.md

File metadata and controls

60 lines (52 loc) · 7.48 KB

TRDR Hub LCopilot Agent Playbook

Agent Goals

  • Guard the LCopilot pipeline end to end so backend ingestion, rule execution, AI reasoning, and frontend delivery work from one deterministic payload.
  • Run security, audit, and data-shape reviews before touching code so every change records who/what/why alongside AuditService hooks.
  • Patch OCR adapters, validator.py, crossdoc helpers, shared types, and UI mappers in unison to avoid shape drift.
  • Maintain stable document IDs, names, and type enums so validation history, analytics, and exporters' submissions remain referentially sound.
  • Enforce structured Expected/Found/SuggestedFix messaging on every discrepancy card and keep the Overview, Documents, Issues, and Analytics tabs wired to the same contract.

System Architecture Summary

  • LCopilot flow: Upload (1-6 docs) -> OCR + extraction -> UCP600 deterministic rules -> AI cross-document analysis -> Processing summaries/analytics -> UI tabs.
  • Upload (apps/api/app/routers/documents.py:37-180): Accepts up to six PDFs/images, validates headers, hashes files for audit, stores in S3, and records metadata.
  • OCR & extraction (apps/api/app/services.py:309-390): DocumentProcessingService pulls the session docs, runs OCR (DocAI primary, Textract fallback), saves structured entities plus documents_presence.
  • Deterministic rules (apps/api/app/services/validator.py:600-760): Loads icc.ucp600 domains, enforces UCP600/ISBP logic, and stamps each document summary with success/warning/error.
  • AI crossdoc engine (apps/api/app/services/crossdoc.py:41-276): Runs goods, amount, document matching, B/L, insurance, and timing checks under the icc.lcopilot.crossdoc domain with doc references.
  • Validation aggregator (apps/api/app/routers/validate.py:392-518, 1640-1752): Produces processing_summary, document_status, timeline, analytics, and persisted extracted LC data while appending crossdoc issues.
  • Response mapper + UI (apps/web/src/lib/exporter/resultsMapper.ts:26-210, apps/web/src/pages/ExporterResults.tsx:1077-1087): Normalizes payloads for use-lcopilot and feeds the Overview/Documents/Issues/Analytics tabs.

Allowed Operations

  • Audit impacted services, payload schemas, and UI consumers before coding; document findings in the Dev Agent Record.
  • Coordinate edits across OCR adapters, validators, and frontend mappers whenever payload fields or shapes move.
  • Update backend payload builders (validate.py, validator.py, crossdoc.py) and immediately mirror shared Pydantic/TypeScript types.
  • Extend deterministic rule coverage or AI crossdoc cases as long as doc IDs, labels, and severity semantics remain stable.
  • Run focused unit/integration/UI tests touching OCR, validators, crossdoc, and tabs prior to handoff.

Required Conventions

  • Follow Audit -> Plan -> Patch -> Test -> Summarize for every change set and log each phase.
  • Keep backend and frontend payload shapes identical by updating packages/shared-types/src/api.ts and packages/shared-types/python/schemas.py with any schema change.
  • Preserve document identifiers generated by the backend; do not rename or reorder documents in transit.
  • Emit discrepancy data with explicit Expected, Found, and SuggestedFix fields (resultsMapper.formatExpectedFound guides formatting).
  • Wire every Overview/Documents/Issues/Analytics tab to the real validation payload; no tab should rely on simulated UI state.
  • Leave UCP600 rule execution deterministic; AI assistance is scoped to cross-document reasoning and summarization.

Payload Contract (Backend -> Frontend)

  • processing_summary (apps/api/app/routers/validate.py:480-518, 1640-1665): carries documents, verified, warnings, errors, discrepancies, compliance_rate, processing_time_seconds, and processing_time_display plus an internal status_counts.
  • document_status (apps/api/app/routers/validate.py:483, 1630-1638; apps/web/src/lib/exporter/resultsMapper.ts:51-56): {success, warning, error} counters derived from document summaries and used for Overview chips and analytics gauges.
  • timeline (apps/api/app/routers/validate.py:1669-1695; apps/web/src/lib/exporter/resultsMapper.ts:59-72): ordered events [Documents Uploaded, LC Terms Extracted, Document Cross-Check, Customs Pack Generated] with statuses, descriptions, and timestamps.
  • analytics (apps/api/app/routers/validate.py:1699-1752; apps/web/src/lib/exporter/resultsMapper.ts:73-139): exposes extraction_accuracy, lc_compliance_score, customs_ready_score, documents_processed, document_status_distribution, document_processing[], performance_insights, and processing_time_display.
  • issues[] / issue_cards (apps/api/app/services/validator.py:600-760; apps/api/app/services/crossdoc.py:41-276; apps/web/src/lib/exporter/resultsMapper.ts:120-152): every entry must include rule, title, severity, document names/IDs, and structured expected, actual, suggestion.
  • documents[] (apps/api/app/routers/validate.py:392-514; apps/web/src/lib/exporter/resultsMapper.ts:153-192; apps/web/src/hooks/use-lcopilot.ts:36-138): stable id, name, type/documentType, status, discrepancyCount, extractedFields, ocrConfidence, and extraction_status, plus documents_presence metadata for per-tab rendering.
  • Shared definitions live in packages/shared-types/src/api.ts and packages/shared-types/python/schemas.py; keep them synchronized whenever contracts move.

AI Crossdoc Instructions

  • run_cross_document_checks (apps/api/app/services/crossdoc.py:41-276) must remain deterministic and always tag results with ruleset_domain="icc.lcopilot.crossdoc".
  • Each rule has to resolve document names/IDs, set severity, and fill Expected vs Found strings so the Issues tab can display the discrepancy without extra formatting.
  • Register new crossdoc domains in validator.py (domain sequencing) and ensure _build_document_lookup plus _resolve_doc_references cover any new document types.
  • Let AI provide insights only where deterministic checks need narrative context (e.g., ai_enrichment summaries); do not move core UCP600 logic into LLM prompts.
  • Keep documents_presence (apps/api/app/routers/validate.py:1019-1141) aligned with crossdoc assumptions so UI doc badges never desync from backend facts.

Donts

  • Never introduce mock or placeholder data into backend responses or frontend state; rely on real validation payloads only.
  • Do not allow backend/frontend schema drift or skip updates to shared typings when adding/changing fields.
  • Avoid sweeping refactors; implement minimal, surgical patches scoped to the affected OCR, validator, or mapper path.
  • Do not make UCP600 rule outcomes probabilistic or reroute them through AI; determinism is mandatory.
  • Never mutate document_id ordering mid-session or drop Required Expected/Found/SuggestedFix messaging.

Examples (short)

  • Add analytics insight: extend _build_document_processing_analytics (apps/api/app/routers/validate.py:1699-1752), mirror the field in buildDefaultAnalytics (apps/web/src/lib/exporter/resultsMapper.ts:73-139), and render it inside the Analytics tab.
  • Tighten crossdoc tolerance: update CROSSDOC-AMOUNT-1 (apps/api/app/services/crossdoc.py:94-133), keep Expected/Found strings intact, and rerun validator tests.
  • Surface OCR confidence: persist the metric in DocumentProcessingService (apps/api/app/services.py:309-390), confirm it flows through documents[], and bind it to the Documents tab badges.