← nyxcore-systems
6 min read

Shipping Ethical AI Reports: A Deep Dive into Ipcha's New Lens

We just rolled out a significant update to our Ipcha AI workflow reports, embedding an ethical lens directly into the analysis and reporting process. Here's how we built it, from raw SQL to UI, with minimal friction.

AIEthicalAISoftwareDevelopmentTRPCTypeScriptReportsFrontendBackend

It’s 2026, and the conversation around AI isn't just about capabilities; it's increasingly about responsibility. At our core, we believe that AI systems must be transparent and accountable, especially when making critical assessments. That's why a recent development session focused on a crucial upgrade to our internal AI analysis tool, Ipcha: integrating an ethical lens directly into its reporting capabilities.

This isn't just about adding a new tab; it's about fundamentally shifting how we understand and present Ipcha's output. We wanted to ensure that ethical considerations weren't an afterthought but an integral part of every report.

The session, captured in a "Letter to Myself" handoff, details the journey from a well-structured plan to a fully implemented, ready-to-deploy feature.

The Mission: Ethical Reports for Ipcha

Our goal was clear: implement a dedicated "Ipcha Reports" section and inject an ethical lens into its findings. This meant:

  1. Detection: Identifying which workflows were "Ipcha" workflows.
  2. Data Retrieval: Fetching relevant reports and completed workflows.
  3. Ethical Context: Augmenting report data with "Accumulated Ethical Findings."
  4. Presentation: Building a robust UI for generating, listing, and managing these reports.
  5. Integration: Ensuring the ethical insights were surfaced at critical points in the analysis prompts.

By the end of the session, all six core tasks were complete, merged, and ready for deployment.

Under the Hood: The Technical Journey

Let's break down how we stitched this together, touching on the key technical decisions and implementations.

1. The Ipcha Identifier: Knowing Our Workflows

First, we needed a reliable way to identify Ipcha workflows. This wasn't just about a name; it was about its underlying configuration. We created a simple, yet effective, helper:

typescript
// src/lib/ipcha-detection.ts
export const isIpchaWorkflow = (workflow: { name: string; providerFanOutConfig?: any }): boolean => {
  // Simple heuristic: either by name convention or a specific config
  return workflow.name.startsWith('Ipcha:') || (workflow.providerFanOutConfig && workflow.providerFanOutConfig.type === 'ipcha');
};

This isIpchaWorkflow() helper became the bedrock, used throughout the backend to filter and contextualize data.

2. Data Plumbing: Fetching Reports via tRPC

For data retrieval, we leaned heavily on tRPC to provide type-safe API endpoints.

  • listByIpcha query in src/server/trpc/routers/reports.ts: This involved a raw SQL join to efficiently pull reports specifically linked to Ipcha workflows. When dealing with complex relationships and potential performance bottlenecks, sometimes a well-crafted raw SQL query is the most pragmatic solution.

  • listCompletedIpcha query in src/server/trpc/routers/workflows.ts: This endpoint provided the list of completed Ipcha workflows, essential for populating the "generate report" picker in the UI.

3. The Ethical Injection: Context is King

This was the core of the "ethical lens." How do we make ethical findings part of the report context? We modified src/server/services/report-context.ts:

typescript
// src/server/services/report-context.ts (conceptual snippet)
export const formatWorkflowContext = async (workflowId: string): Promise<string> => {
  // ... existing context generation logic ...

  const workflow = await getWorkflowById(workflowId);
  let context = `Workflow Details:\n${JSON.stringify(workflow, null, 2)}\n\n`;

  if (isIpchaWorkflow(workflow)) {
    const ethicalFindings = await getAccumulatedEthicalFindings(workflowId); // Hypothetical service call
    if (ethicalFindings) {
      context += `--- Accumulated Ethical Findings ---\n${ethicalFindings}\n\n`;
    }
  }

  // ... rest of context generation ...
  return context;
};

By conditionally appending an "Accumulated Ethical Findings" section for Ipcha workflows, we ensured that this critical data was always available when generating a report.

4. Prompt Engineering for Ethics

Making the ethical findings available in the report context is one thing; making sure the AI model uses them is another. We injected a {{ethics}} template variable into specific prompt steps:

// createIpcha mutation prompt snippets
// Adversarial Analysis Step Prompt:
"Analyze the workflow for potential biases and vulnerabilities, considering the following ethical context: {{ethics}}."

// Arbitration Step Prompt:
"Based on the adversarial analysis and the ethical findings: {{ethics}}, propose arbitration strategies."

This ensures that the AI's analysis and arbitration steps are explicitly guided by the ethical findings, rather than just general context.

5. Building the UI: A Dedicated Reports Section

Finally, the user-facing component. We built out src/app/(dashboard)/dashboard/ipcha/page.tsx. This wasn't just a simple list; it was a full interactive section:

  • Collapsible Card: For a clean dashboard look.
  • Workflow Picker: Using the listCompletedIpcha data.
  • Generate Button: To kick off new report generation.
  • Report List: Displaying existing Ipcha reports.
  • Share Toggle & Delete: Essential management features.

The frontend, powered by React and our tRPC hooks, came together smoothly, providing a complete experience for managing Ipcha's ethical reports.

6. Confidence Through Testing

No feature is complete without testing. We added tests/unit/ipcha-reports.test.ts with four specific tests for isIpchaWorkflow, ensuring its reliability. Crucially, our entire suite of 206 unit tests passed, and the codebase remained type-check clean. This gives us high confidence in the quality and stability of the new feature.

Lessons Learned: Smooth Sailing, Smart Tweaks

One of the most satisfying aspects of this session was the "Pain Log" entry: "No major issues encountered. Plan was well-structured and all steps went smoothly."

The Power of a Solid Plan: This isn't just luck. It underscores the immense value of detailed, upfront planning. Our docs/plans/2026-03-09-ipcha-reports-implementation.md document clearly laid out every task, dependency, and potential pitfall, allowing us to execute with precision. Investing time in planning often saves exponential time in debugging and refactoring later.

Minor Refactors for Major Gains: We did encounter a small hiccup: _utils in ipcha/page.tsx was renamed to utils. This was a minor refactor, but a critical one, as it enabled invalidate() calls for tRPC queries, ensuring our UI correctly reflects data changes after actions like deleting a report. These small, enabling changes are often the unsung heroes of a smooth user experience.

What's Next?

The code is committed to main (commit 100a6e4), but not yet pushed to origin or deployed. Our immediate next steps are:

  1. Push and Deploy: Get this feature into production.
  2. Verify UI: Confirm the /dashboard/ipcha section renders correctly.
  3. End-to-End Test: Run an actual Ipcha analysis and generate a report to test the entire flow.
  4. Future Enhancement: Consider adding the {{ethics}} variable to the Synthesis step prompt as well, to ensure ethical insights permeate every level of the report.

This session was a great example of how a well-defined plan, combined with robust technical execution, can deliver significant value. We're excited to see how this new ethical lens enhances our understanding and responsible use of AI.

json
{"thingsDone":[
  "Created `isIpchaWorkflow()` helper for workflow detection",
  "Added `listByIpcha` tRPC query (raw SQL join) for reports",
  "Added `listCompletedIpcha` tRPC query for workflow picker",
  "Injected 'Accumulated Ethical Findings' into `formatWorkflowContext()` for Ipcha workflows",
  "Added `{{ethics}}` template variable to Adversarial Analysis and Arbitration prompts",
  "Built full Reports section UI (`ipcha/page.tsx`) with picker, generate, list, share, delete",
  "Wrote 4 unit tests for `isIpchaWorkflow`",
  "Ensured all 206 unit tests pass and typecheck is clean"
],"pains":[
  "No major issues encountered, plan was highly effective",
  "Renamed `_utils` to `utils` in `ipcha/page.tsx` to enable `invalidate()` calls"
],"successes":[
  "Seamless implementation due to well-structured plan",
  "Successful integration of ethical insights into AI reporting workflow",
  "Comprehensive UI for report management",
  "Full test suite pass ensuring code quality"
],"techStack":[
  "TypeScript",
  "tRPC",
  "React",
  "Next.js",
  "SQL",
  "Git",
  "Docker"
]}