Reports #756

Activity

1. ngoiyaeric commented on Jul 25, 2026

   

   ngoiyaeric

   on Jul 25, 2026

   CollaboratorAuthor

   More actions

   @coderabbitai plan
2. coderabbitai commented on Jul 25, 2026

   

   coderabbitaibot

   on Jul 25, 2026 – with coderabbitai

   Contributor

   More actions

   Coding Plan

   Summary

   • Extend (do not replace) the existing two-agent report pipeline by adding a report domain/type parameter threaded from the UI through submit() into generateReportContext.
   • Add a dedicated, domain-parameterized compliance synthesis agent that produces structured, standards-aligned output for mining and agriculture, grounded in existing chat context, sensor-fusion findings, and drawn AOI geometries.
   • Render a new "Regulatory Compliance Assessment" section plus a GIS-enriched spatial appendix in the report template, and provide KML/GeoJSON exports of mapped AOIs to satisfy GIS-format expectations.
   • Default general reports remain unchanged, and jurisdiction-specific GIS nuances are surfaced as flagged assumptions rather than hard regulatory assertions.

   Design Choices

   Design Choice 1: How should mining/agriculture compliance domain knowledge be injected into report generation?

   Options Considered:

   1. Inject compliance knowledge via the user's custom system prompt (users.systemPrompt).
   2. Add a dedicated compliance report agent + schema, selected by a report domain/type parameter, running alongside the existing report agents.

   Chosen Option: 2

   Rationale: The codebase offers two hooks: the per-user users.systemPrompt override (a full replacement of the researcher prompt) or the report-agent pipeline. The system-prompt override is global-per-user, wholesale (loses tool-routing rules), and free-text (cannot produce structured, standard-aligned output), making it unsuitable for deterministic compliance sections. A dedicated agent keyed by report domain produces structured, standard-aligned compliance content without sacrificing the researcher's tool-routing behavior, and slots cleanly into the existing report pipeline and template.

   Design Choice 2: What GIS-compatible export format should accompany the compliance report?

   Options Considered:

   1. Generate ESRI Shapefiles.
   2. Generate KML/KMZ and GeoJSON from drawn AOIs/geometries.

   Chosen Option: 2

   Rationale: The ticket stresses GIS-compatible formats (shapefiles, KML/KMZ). Shapefiles are binary multi-file archives requiring heavier libraries; drawn features are already WGS84 GeoJSON. KML and GeoJSON are text-based, generated client-side from existing drawnFeatures, satisfy the "GIS-compatible format" requirement, and are the formats certifiers/agencies most commonly accept for verification.

   💡 User Tips

   Regenerate the plan with different choices with @coderabbitai <feedback>.

   Implementation Steps

   Phase 1: Introduce a report domain/type model and selection workflow

   Establish the concept of a "report domain" (general / mining exploration / agriculture) with optional document-type subtypes (e.g., JORC/NI 43-101 technical report, reclamation/disturbance report; organic certification farm map, FSMA traceability plan). The goal is to let the user choose what kind of compliance document they are producing and thread that choice end-to-end through the report pipeline, while keeping the current generic report as the default so existing behavior is unchanged.

   Task 1: Define the report domain taxonomy and shared types

   Create a single source of truth describing the supported report domains, their document subtypes, and the standards each references.

   • Add a new config/module (e.g., under lib/schema/ or lib/config/) defining a ReportDomain union ('general' | 'mining' | 'agriculture') and, per domain, a list of document subtypes with human-readable labels and the associated standards (JORC, NI 43-101, S-K 1300, PERC; USDA NOP, EU 2018/848, FSMA, GLOBALG.A.P., HELC/WC).
   • Define a Zod schema for validating the incoming reportType/domain parameter, following the existing lib/schema/* pattern.
   • Export TypeScript types to be reused by the server action, the report agents, and the template props.

   Task 2: Add report-type selection to the report trigger UI

   Give the user a way to pick a domain/subtype before generating the report.

   • Update components/download-report-button.tsx to present a lightweight selector (dropdown/menu) driven by the taxonomy from Task 1.1; default selection is general to preserve current behavior.
   • Append the chosen reportType (and optional subtype) to the FormData sent to actions.submit(), alongside the existing action and messages.
   • Pass the selected domain into <ReportTemplate> as a new prop so the template can conditionally render domain-specific sections.

   Task 3: Thread the report domain through the server action and context builder

   Propagate the selected domain from the request into the report-generation logic.

   • Update the generate_report_context branch of submit() in app/actions.tsx to read and validate the new reportType field and forward it to generateReportContext.
   • Update generateReportContext in lib/actions/chat.ts to accept an optional reportType/domain argument and, when it is a compliance domain, invoke the new compliance agent (Phase 2) in addition to the existing executive-summary/strategic-synthesis agents, extending the returned object with a new complianceOutput field (kept undefined for general).

   🤖 Prompt for AI agents

   Implement the report domain/type taxonomy and thread it end-to-end from the
   report trigger UI to the report context builder, keeping `general` as the
   default and preserving existing behavior when no compliance domain is selected.
   
   - Create a new config/schema module (e.g., under `lib/schema/` or `lib/config/`)
   defining a `ReportDomain` union type (`'general' | 'mining' | 'agriculture'`),
   per-domain document subtypes with human-readable labels, and the associated
   standards (JORC, NI 43-101, S-K 1300, PERC for mining; USDA NOP, EU 2018/848,
   FSMA, GLOBALG.A.P., HELC/WC for agriculture). Define a Zod schema validating the
   `reportType`/`domain` parameter, following the existing `lib/schema/*` pattern,
   and export TypeScript types for reuse by the server action, report agents, and
   template props.
   - Update `components/download-report-button.tsx` to add a lightweight selector
   (dropdown/menu) driven by this taxonomy, defaulting to `general`. Append the
   chosen `reportType` (and optional subtype) to the `FormData` sent to
   `actions.submit()` alongside the existing `action` and `messages` fields. Pass
   the selected domain as a new prop into `<ReportTemplate>`.
   - Update the `generate_report_context` branch of `submit()` in `app/actions.tsx`
   to read and validate the new `reportType` field and forward it to
   `generateReportContext`.
   - Update `generateReportContext` in `lib/actions/chat.ts` to accept an optional
   `reportType`/domain argument. When the domain is a compliance domain
   (mining/agriculture), it should also invoke the compliance agent (built in a
   later phase) alongside the existing `executiveSummaryAgent` and
   `strategicSynthesisAgent`, and extend the returned object with a new
   `complianceOutput` field, which stays `undefined` for `general`.
   

   Phase 2: Add a domain-aware compliance synthesis agent

   Introduce structured, standards-aligned compliance content generation. The agent consumes the same conversation transcript, sensor-fusion findings, and drawn AOI geometries already available to the report pipeline, but produces a compliance-oriented, structured assessment framed around the selected domain's regulatory expectations and spatial-data requirements (coordinates, boundaries, datum/projection, disturbance/field areas, traceability).

   Task 1: Implement the compliance report agent

   Create a new report agent parallel to the existing two, selecting a domain-specific prompt and output structure.

   • Create a new module in lib/agents/report/ (e.g., compliance-synthesis.ts) exposing an agent function that accepts the domain, subtype, active messages, sensor-fusion findings, and drawn-feature/spatial context.
   • Use generateText (matching the existing report-agent pattern) with a domain-specialized system prompt: for mining, frame output around tenure boundaries, drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned disclosure expectations; for agriculture, frame around field/parcel boundaries, buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
   • Return a structured complianceOutput (parsed JSON) with clearly named subsections (e.g., regulatory framework references, spatial-data summary/metadata, key compliance observations, gaps/recommended actions), following the JSON-parsing-with-fallback approach already used by executive-summary.ts/strategic-synthesis.ts.
   • Explicitly note in the prompt that jurisdiction-specific GIS formats/coordinate systems/metadata vary, so the output should flag assumptions rather than assert regulatory certainty.

   Task 2: Derive spatial-metadata context for the agent and template

   Assemble the coordinate/boundary/measurement details the compliance domains require, from data already present in the app.

   • Add a helper (co-located with the compliance agent or in lib/actions/chat.ts) that transforms drawnFeatures (GeoJSON geometries + measurements from map-data-context) into a normalized spatial summary: feature identity, geometry type, area/length, bounding coordinates, and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
   • Feed this spatial summary into the compliance agent (Task 2.1) and also surface it to the template (Phase 3) so the rendered appendix and the AI narrative are consistent.

   🤖 Prompt for AI agents

   Build a new domain-aware compliance synthesis agent that mirrors the existing
   report-agent pattern, and a spatial-metadata helper that feeds both the agent
   and the template.
   
   - Create a new module in `lib/agents/report/` (e.g., `compliance-synthesis.ts`)
   exposing an agent function accepting the domain, subtype, active messages,
   sensor-fusion findings, and drawn-feature/spatial context.
   - Use `generateText` (matching the existing
   `executive-summary.ts`/`strategic-synthesis.ts` pattern) with a
   domain-specialized system prompt: for mining, frame around tenure boundaries,
   drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned
   disclosure expectations; for agriculture, frame around field/parcel boundaries,
   buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
   - Return a structured `complianceOutput` (parsed JSON) with clearly named
   subsections: regulatory framework references, spatial-data summary/metadata, key
   compliance observations, and gaps/recommended actions. Follow the same
   JSON-parsing-with-fallback approach already used by the existing report agents
   so malformed responses never break downstream rendering.
   - In the prompt, explicitly instruct the model that jurisdiction-specific GIS
   formats/coordinate systems/metadata vary, and that it should flag assumptions
   rather than assert regulatory certainty.
   - Add a helper (co-located with the compliance agent or in
   `lib/actions/chat.ts`) that transforms `drawnFeatures` (GeoJSON geometries +
   measurements from `map-data-context`) into a normalized spatial summary
   containing feature identity, geometry type, area/length, bounding coordinates,
   and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
   - Feed this spatial summary into the compliance agent as context, and also make
   it available to the report template (for the spatial appendix) so the AI
   narrative and rendered appendix stay consistent.
   

   Phase 3: Render compliance sections and enable GIS-compatible export

   Extend the report document to display the compliance assessment and a GIS-oriented spatial appendix, and give the user GIS-compatible file exports of the mapped AOIs so the report package matches what mining/agriculture submissions expect.

   Task 1: Add compliance sections to the report template

   Render the new domain-specific content when a compliance domain is selected.

   • Update components/report-template.tsx ReportTemplateProps to accept the selected reportType/domain, complianceOutput, and the spatial summary from Task 2.2.
   • Add a new numbered "Regulatory Compliance Assessment" section (rendered only when complianceOutput is present), following the existing "render only if prop truthy" and data-pdf-nosplit conventions; render its structured subsections (framework references, observations, gaps/recommended actions) via the existing ReactMarkdown pattern.
   • Enhance the Quantitative/Spatial Appendix to include GIS-relevant columns (coordinates/bounding box, datum/projection, computed area/length) driven by the spatial summary, so the appendix reads as a compliance-grade spatial data table.
   • Adjust the hardcoded section numbering to accommodate the inserted section (or convert the numbering to a small ordered list to insert cleanly).

   Task 2: Add KML/GeoJSON export of drawn AOIs

   Provide GIS-compatible spatial file outputs alongside the PDF.

   • Add a utility (near lib/utils/report-generator.ts) that converts drawnFeatures GeoJSON into KML and standalone GeoJSON files (WGS84), with feature names/labels derived from the compliance context.
   • Wire an export affordance into components/download-report-button.tsx (available for compliance domains) that triggers download of the KML/GeoJSON in addition to the generated PDF.
   • Keep this purely client-side/text-based to avoid new heavy dependencies.

   🤖 Prompt for AI agents

   Extend the report template to render the new compliance content and spatial
   appendix enhancements, and add client-side GIS export utilities for drawn AOIs.
   
   - Update `components/report-template.tsx` `ReportTemplateProps` to accept the
   selected `reportType`/domain, `complianceOutput`, and the spatial summary
   produced in Phase 2.
   - Add a new numbered "Regulatory Compliance Assessment" section that renders
   only when `complianceOutput` is present, following the existing "render only if
   prop truthy" and `data-pdf-nosplit` conventions used elsewhere in the template.
   Render its structured subsections (framework references, observations,
   gaps/recommended actions) via the existing ReactMarkdown pattern.
   - Enhance the existing Quantitative/Spatial Appendix to include GIS-relevant
   columns (coordinates/bounding box, datum/projection, computed area/length)
   driven by the spatial summary, making the appendix read as a compliance-grade
   spatial data table.
   - Adjust the hardcoded section numbering (sections `00`–`03`) to accommodate the
   newly inserted section, or convert the numbering scheme to a small ordered list
   so sections can be inserted cleanly.
   - Add a new utility near `lib/utils/report-generator.ts` that converts
   `drawnFeatures` GeoJSON into KML and standalone GeoJSON files (WGS84), with
   feature names/labels derived from the compliance context.
   - Wire an export affordance into `components/download-report-button.tsx`,
   available for compliance domains, that triggers a download of the KML/GeoJSON
   files in addition to the generated PDF. Keep this implementation purely
   client-side/text-based to avoid introducing new heavy dependencies (e.g., avoid
   shapefile libraries).
   

   Research

   QCX-Terra is a Next.js + Vercel AI SDK conversational geospatial assistant. Chat orchestration runs through the submit() server action in app/actions.tsx, which branches on a FormData action string. Report export is an on-demand, two-agent pipeline: download-report-button.tsx captures a Mapbox snapshot and chat history, calls submit(action='generate_report_context'), which invokes generateReportContext(messages) in lib/actions/chat.ts. That function runs executiveSummaryAgent and strategicSynthesisAgent (lib/agents/report/*) and returns { title, summary, strategicOutput }, which are rendered by components/report-template.tsx (fixed, hardcoded sections 00–03) and rasterized to PDF via lib/utils/report-generator.ts. Map-drawn AOIs/geometries flow from components/map/map-data-context.tsx as drawnFeatures (GeoJSON + measurement). There is no existing report-type/domain concept, and no mining/agriculture/compliance logic anywhere in the codebase — this is greenfield domain work that extends the existing report pipeline rather than replacing it.

   ---

   🚀 Next Steps

   🤖 All AI agent prompts combined

   Task: 1
   
   Implement the report domain/type taxonomy and thread it end-to-end from the
   report trigger UI to the report context builder, keeping `general` as the
   default and preserving existing behavior when no compliance domain is selected.
   
   - Create a new config/schema module (e.g., under `lib/schema/` or `lib/config/`)
   defining a `ReportDomain` union type (`'general' | 'mining' | 'agriculture'`),
   per-domain document subtypes with human-readable labels, and the associated
   standards (JORC, NI 43-101, S-K 1300, PERC for mining; USDA NOP, EU 2018/848,
   FSMA, GLOBALG.A.P., HELC/WC for agriculture). Define a Zod schema validating the
   `reportType`/`domain` parameter, following the existing `lib/schema/*` pattern,
   and export TypeScript types for reuse by the server action, report agents, and
   template props.
   - Update `components/download-report-button.tsx` to add a lightweight selector
   (dropdown/menu) driven by this taxonomy, defaulting to `general`. Append the
   chosen `reportType` (and optional subtype) to the `FormData` sent to
   `actions.submit()` alongside the existing `action` and `messages` fields. Pass
   the selected domain as a new prop into `<ReportTemplate>`.
   - Update the `generate_report_context` branch of `submit()` in `app/actions.tsx`
   to read and validate the new `reportType` field and forward it to
   `generateReportContext`.
   - Update `generateReportContext` in `lib/actions/chat.ts` to accept an optional
   `reportType`/domain argument. When the domain is a compliance domain
   (mining/agriculture), it should also invoke the compliance agent (built in a
   later phase) alongside the existing `executiveSummaryAgent` and
   `strategicSynthesisAgent`, and extend the returned object with a new
   `complianceOutput` field, which stays `undefined` for `general`.
   ===============================================================================
   
   Task: 2
   
   Build a new domain-aware compliance synthesis agent that mirrors the existing
   report-agent pattern, and a spatial-metadata helper that feeds both the agent
   and the template.
   
   - Create a new module in `lib/agents/report/` (e.g., `compliance-synthesis.ts`)
   exposing an agent function accepting the domain, subtype, active messages,
   sensor-fusion findings, and drawn-feature/spatial context.
   - Use `generateText` (matching the existing
   `executive-summary.ts`/`strategic-synthesis.ts` pattern) with a
   domain-specialized system prompt: for mining, frame around tenure boundaries,
   drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned
   disclosure expectations; for agriculture, frame around field/parcel boundaries,
   buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
   - Return a structured `complianceOutput` (parsed JSON) with clearly named
   subsections: regulatory framework references, spatial-data summary/metadata, key
   compliance observations, and gaps/recommended actions. Follow the same
   JSON-parsing-with-fallback approach already used by the existing report agents
   so malformed responses never break downstream rendering.
   - In the prompt, explicitly instruct the model that jurisdiction-specific GIS
   formats/coordinate systems/metadata vary, and that it should flag assumptions
   rather than assert regulatory certainty.
   - Add a helper (co-located with the compliance agent or in
   `lib/actions/chat.ts`) that transforms `drawnFeatures` (GeoJSON geometries +
   measurements from `map-data-context`) into a normalized spatial summary
   containing feature identity, geometry type, area/length, bounding coordinates,
   and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
   - Feed this spatial summary into the compliance agent as context, and also make
   it available to the report template (for the spatial appendix) so the AI
   narrative and rendered appendix stay consistent.
   ===============================================================================
   
   Task: 3
   
   Extend the report template to render the new compliance content and spatial
   appendix enhancements, and add client-side GIS export utilities for drawn AOIs.
   
   - Update `components/report-template.tsx` `ReportTemplateProps` to accept the
   selected `reportType`/domain, `complianceOutput`, and the spatial summary
   produced in Phase 2.
   - Add a new numbered "Regulatory Compliance Assessment" section that renders
   only when `complianceOutput` is present, following the existing "render only if
   prop truthy" and `data-pdf-nosplit` conventions used elsewhere in the template.
   Render its structured subsections (framework references, observations,
   gaps/recommended actions) via the existing ReactMarkdown pattern.
   - Enhance the existing Quantitative/Spatial Appendix to include GIS-relevant
   columns (coordinates/bounding box, datum/projection, computed area/length)
   driven by the spatial summary, making the appendix read as a compliance-grade
   spatial data table.
   - Adjust the hardcoded section numbering (sections `00`–`03`) to accommodate the
   newly inserted section, or convert the numbering scheme to a small ordered list
   so sections can be inserted cleanly.
   - Add a new utility near `lib/utils/report-generator.ts` that converts
   `drawnFeatures` GeoJSON into KML and standalone GeoJSON files (WGS84), with
   feature names/labels derived from the compliance context.
   - Wire an export affordance into `components/download-report-button.tsx`,
   available for compliance domains, that triggers a download of the KML/GeoJSON
   files in addition to the generated PDF. Keep this implementation purely
   client-side/text-based to avoid introducing new heavy dependencies (e.g., avoid
   shapefile libraries).
   

   💡 Iterate on the plan with: `@coderabbitai` <feedback>

   Example Feedback
   - `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
   - `@coderabbitai` For design choice 1 go ahead with option 3 and replan.
   

   ---

   💬 Have feedback or questions? Drop into our discord!