DEV Community: John Joseph Bassey

[Boost]

John Joseph Bassey — Tue, 03 Nov 2026 23:09:07 +0000

John Joseph Bassey

Nov 3

SynapseHealer: Building an Autonomous, Self-Healing Interoperability DLQ with InterSystems IRIS AI Hub

#ai #interoperability #vectorsearch #intersystemsiris

5 min read

SynapseHealer: Building an Autonomous, Self-Healing Interoperability DLQ with InterSystems IRIS AI Hub

John Joseph Bassey — Tue, 03 Nov 2026 22:36:09 +0000

Built for the InterSystems Programming Contest: AI Agents in Interoperability Workflows (2026)

The problem: the DLQ is a graveyard

In healthcare and supply-chain integrations, the dead-letter queue is where transactions go to die. A vendor renames client_uuid to customer_id with no warning. An EHR bridge emits 1985-02-31, an impossible calendar day. An HL7 ADT^A01 arrives with PV1 before PID. A lab note contains an unescaped pipe. The integration engine rejects the message, and it sits in the queue until an engineer opens a hex dump, decodes the schema violation, writes a one-off script, and resubmits — days later, if at all.

SynapseHealer replaces that manual bottleneck with an autonomous pipeline on InterSystems IRIS AI Hub: a custom inbound adapter, native vector search over repair runbooks, a governed %AI.Agent, and a tri-branch router that auto-heals, escalates to the InterSystems Workflow Engine, or quarantines.

1. AI Hub experience: DeadLetterHealerBP orchestrates the agent

Synapse.Process.DeadLetterHealerBP is the arbitrator. OnRequest takes a Synapse.Msg.DeadLetterRequest from ChaosIngestService, and ProcessDeadLetter picks the execution mode: live when SYNAPSE_MODE=live and an API key exists, otherwise replay — a deterministic mode that needs zero API keys.

In live mode it instantiates Synapse.Agent.DeadLetterHealerAgent, an %AI.Agent bound to Synapse.Agent.HealerToolSet, sends it the payload ID, source system, format, validation error, and raw body, strips any markdown fences, and parses the JSON contract: decisionBranch, confidenceScore, riskLevel, matchedPatternId, healedPayload, reasoning.

The agent cannot improvise. Its toolset — Synapse.Agent.HealerToolSet (%AI.ToolSet) wrapping Synapse.Agent.HealerTools (%AI.Tool) — exposes exactly three governed calls: SearchRunbookRAG, ValidateRepairedPayload, and CalculateRiskScore. It looks up the nearest verified runbook in the 384-dimensional vector index (VECTOR_COSINE, sub-45ms), applies the deterministic transformation, and must pass validation before anything is resubmitted.

Credentials never appear in plaintext logs. Synapse.Config.AIHubSetup.StoreWalletSecret writes the API key into the IRIS Wallet (%Wallet.KeyValue, collection SynapseSecrets, key SynapseSecrets.LLMKey) at startup, and BuildProviderSettings references it through @{env:LLM_API_KEY} indirection instead of embedding the literal key. The same setup registers %ConfigStore and Ens.Config.Credentials when those classes exist, with graceful fallback on builds that lack them.

2. Models and cost control

We default to gemini-1.5-flash (gpt-4o-mini is the OpenAI alternative). Heal decisions are structural, not creative, so a fast, cheap model is the right choice.

Every inference lands in Synapse.Data.AuditTelemetry, a persistent table storing prompt tokens, completion tokens, estimated USD cost, latency, the full tool-call trace, decision branch, risk level, and workflow status. Cost is computed from the counts — prompt × 0.00000015 + completion × 0.0000006 — and written to the table in real time; the Next.js dashboard reads /api/synapse/status and shows the cumulative USD counter and auto-heal rate live.

Across our 10 regression suites: 479 prompt tokens, 176 completion tokens, $0.00018 per heal, ~145 ms end to end, 90% auto-heal rate across the seven canonical chaos scenarios. Replay mode consumes no tokens, and the telemetry table is pre-seeded with golden traces for every scenario, so the dashboard is populated from the first second.

3. Observability and tracing: the three-step spine

Each heal produces a governed three-step trace, stored in ToolTraceJSON:

SearchRunbookRAG — error and format in, matched runbook and similarity out (~42 ms)
ValidateRepairedPayload — strict HL7 v2 / JSON syntax and schema check (~56 ms)
CalculateRiskScore — clinical and financial risk classification (~35 ms)

The trace is surfaced live in the Next.js console: a step gauge per call, side-by-side diff of the corrupted and healed payloads, and the agent's reasoning. HUMAN_WORKFLOW messages land in the workflow queue where an operator Approves (→ ResubmitDeliveryOp) or Rejects (→ QuarantineVaultOp) with reviewer notes. Everything is queryable via /api/synapse/workflow/tasks and the persistent audit ledger.

4. IRIS agentic development: MCP build tooling, guardrails, %AI syntax, and IPM packaging

We separated development-time agentic tooling from runtime governance. During development, we paired our IDE with the iris-agentic-dev MCP toolkit (iris_symbols_local for local AST verification across 150+ symbols and objectscript-guardrails to enforce method-scoped Quit rules and $IsObject checks before container compilation). At runtime inside the container, governance is 100% native to IRIS AI Hub—powered by an %AI.ToolSet of %AI.Tool methods rather than an external sidecar.

The ObjectScript guardrails are the part I trust most:

Every class is ProcedureBlock, and the business process checks %Dictionary.CompiledClass.%ExistsId before instantiating the agent, so a missing compile fails closed instead of guessing.
The agent's system prompt enforces a response contract: one JSON document with fixed fields, no prose.
ValidateRepairedPayload rejects messages that don't start with MSH, put PV1 before PID, use non-YYYYMMDD dates in PID-7, leave unescaped pipes in OBX, or retain legacy keys like client_uuid after a v2 migration. CalculateRiskScore quarantines anything matching <script, eval(, union select, drop table, --, or javascript:, and escalates impossible dates like February 31 to human review.
We learned the container-startup <DIRECTORY> bug the hard way: Config.Databases.Create registers the database in iris.cpf but does not format the physical IRIS.DAT file, crashing auto-start on restart. The fix: a declarative merge.cpf ([Actions]: CreateDatabase, CreateNamespace, Interop=1) plus an iris.script fallback that initializes IRIS.DAT via SYS.Database when absent.

For %AI syntax, the agent resolves its provider via AIHubSetup.GetProviderConfig and BuildProviderSettings, creates %AI.Provider, calls agent.CreateSession() then agent.Chat(session, prompt), and parses the result with %DynamicObject.%FromJSON. It compiled cleanly on the IRIS 2027.1 AI Hub EAP build.

Packaging is automated: module.xml declares <SystemRequirements Version=">=2026.3" Interoperability="enabled"/>, and SetupAll — run by IPM on install — executes Configure() (Wallet, config store, credentials), seeds the runbooks and replay telemetry, then starts Synapse.Production. zpm install synapse-healer or zpm load /opt/irisapp -v gives you a running production with a seeded dashboard. The module shipped with +11 contest bonus points across the custom adapter, embedded Python, vector search, workflow engine, and IPM integration.

Try it

# Prerequisite: Load the InterSystems AI Hub EAP tarball (Build 109 or 154)
# docker image load -i iris-community-2027.1.0AI.109.0-docker.tar.gz

git clone https://github.com/josephjbassey/synapse-healer.git
cd synapse-healer
docker compose up -d
cd ui && npm install && npm run dev

Open http://localhost:3000, press 1–7 to inject chaos payloads, and watch the pipeline heal them. No API key required; set SYNAPSE_MODE=live with an LLM_API_KEY for live AI Hub inference.

It's not magic. It's governed tool calls, deterministic validation, and a telemetry table that actually gets read.

Restoring Academic Due Process: How We Built Margin with Next.js 16 and Clocked AI

John Joseph Bassey — Thu, 22 Oct 2026 12:35:48 +0000

"An 87% AI probability score is not evidence. It is an expulsion notice without due process."

In the age of large language models (LLMs), universities face an academic integrity crisis. Commercial AI detectors produce opaque, probabilistic verdicts that can disproportionately affect non-native English speakers, trigger flawed disciplinary proceedings, and erode trust between students and faculty.

Meanwhile, traditional plagiarism checkers focus on finding copied passages across the public web. They can miss intra-cohort collusion (two students in the same seminar sharing work) and ungrounded factual claims, including fabricated research papers, invented benchmarks, and unsupported assertions.

We built Margin for the Clocked Build Challenge 2026 to address these problems.

Margin is an academic review system that helps course conveners and lecturers examine batches of student submissions using a transparent, evidence-first workflow.

Our guiding principle is simple:

The machine flags; the educator decides.

Why We Built Margin with Clocked AI

Margin uses Clocked's inference endpoints to build an evidentiary pipeline that helps educators investigate potential inconsistencies without treating AI-generated scores as proof of misconduct.

Here is how the system works:

Student Manuscripts (.txt / .docx)
              |
              v
    1. Clocked Protect
       Remove direct identifiers
              |
              v
     2. Clocked Compare
       Compare submissions pairwise
              |
              v
      3. Clocked Verify
       Ground claims in course materials
              |
              v
       4. Clocked Rerank
       Prioritize supporting evidence
              |
              v
      Human Reviewer Ledger
       Compare evidence and record decisions

Figure 1: The tactile side-by-side verification sheet highlighting contradictory empirical findings.

Each stage produces information for human review rather than an automatic academic misconduct verdict.

1. Privacy-Conscious Ingestion

Endpoint: POST /clocked/pii

Before submissions enter the comparison workflow, Margin sends them through Clocked Protect to identify and remove direct identifiers such as student names, matriculation numbers, and email addresses.

The system then uses anonymous tokens such as S-01 and S-02 to distinguish submissions throughout the downstream workflow.

This design helps reduce the influence of identifying information during evidence review and supports a more privacy-conscious assessment process.

An important distinction: removing direct identifiers is a privacy safeguard, not a guarantee of FERPA compliance. Actual compliance depends on the complete system, its data handling, institutional obligations, and applicable law.

2. Pairwise Collision and Contradiction Analysis

Endpoint: POST /clocked/compare

Instead of relying exclusively on public-web plagiarism searches, Margin compares submissions within the same cohort.

For a group of (n) submissions, the number of unique pairs is:

n × (n - 1) / 2

Figure 2: Pairwise review interface sorting direct contradictions to the top with pen-wash highlights.

The comparison pipeline looks for two important patterns.

Contradictions: Direct factual inconsistencies between submissions. For example, two papers might describe an apparently identical experiment but report 45 and 120 iterations, respectively.

Shared facts and near-duplicates: Similar reasoning or overlapping passages that may warrant closer inspection. Margin uses pen-wash highlights to make relevant text easier to compare.

These signals are leads for investigation, not proof of copying. Similarity can have legitimate explanations, and contradictory results can arise from different methods, assumptions, or reporting errors.

3. Syllabus-Grounded Verification

Endpoint: POST /clocked/grounding

A submission can sound convincing while containing unsupported claims. Margin addresses this by checking student assertions against the course syllabus or assigned reading pack.

Claims are classified into three categories:

supported — evidence in the supplied course materials supports the claim.
partial — the materials provide incomplete or qualified support.
unsupported — the supplied materials do not provide sufficient support.

Unsupported claims are prioritized for faculty review.

Figure 3: Claims check interface validating student statements directly against the course syllabus.

The distinction matters: a claim that cannot be verified against a particular reading pack is not necessarily false. It may require another source, additional context, or a more careful interpretation.

4. Citation Triage and Evidence Prioritization

Figure 4: The faculty decision ledger with downloadable audit-ready Markdown report.

Endpoint: POST /clocked/rerank

Once Margin identifies claims that need further investigation, Clocked Rerank helps evaluate relevant reading-pack excerpts and determine how useful each piece of context is.

The triage process assigns one of three actions:

use — the evidence is relevant enough to include in the review.
expand — additional surrounding context may be necessary.
skip — the excerpt is unlikely to help resolve the claim.

This helps reviewers focus on meaningful evidence instead of manually inspecting every passage with equal priority.

The final step is the Human Reviewer Ledger, where educators can examine submissions side by side, inspect character-offset evidence, and record their own decisions.

What We Learned: Engineering Margin for Reliability

Building an application around an AI API involves more than connecting endpoints. We also had to consider API costs, repeated requests, concurrency, and failure handling.

1. Guarding Against the O(n²) Pair Explosion

Consider a seminar containing 30 student submissions:

30 × 29 / 2 = 435 unique comparisons

Making hundreds of API calls for a single batch can become expensive quickly.

We introduced two safeguards.

Local n-gram pre-filtering

Submissions are tokenized into character n-grams in memory. Pairs with no detected vocabulary overlap can be pruned before making an API request, reducing unnecessary calls.

This is a cost-saving heuristic, not a definitive test of whether two submissions are related. It must be interpreted accordingly.

The MAX_PAIRS guard

The interface displays a live estimate of the number of comparisons required. A server-side limit, configured through MAX_PAIRS with a default of 20, prevents unexpectedly large batches from proceeding without an appropriate limit configuration.

This adds a second line of defence against accidental credit depletion.

2. Deterministic Content-Hash Disk Cache

Repeated development requests should not needlessly consume API credits.

To address this, we implemented a file-backed cache under clocked_cache/ using SHA-256 content hashes.

The cache-key function looks like this:

export function computeCacheKey(
  endpoint: string,
  payload: unknown
): string {
  const serialized = canonicalJson(payload);

  return crypto
    .createHash("sha256")
    .update(`${endpoint}:${serialized}`)
    .digest("hex");
}

The canonicalJson helper recursively sorts JSON object keys before serialization. This means equivalent payloads produce the same cache key regardless of object-key insertion order.

We also implemented a strict Never-Cache-Error policy. Transient failures are not stored as successful cache results, allowing subsequent requests to retry rather than reusing stale errors.

3. Concurrency Limits, Backoff, and Jitter

Unrestricted parallel requests can overwhelm an external API or cause avoidable rate-limit failures.

Margin wraps outbound requests in a four-worker concurrency pool using p-limit.

For HTTP 429 and 5xx responses, the retry strategy uses exponential backoff with randomized jitter. This spaces retries out and reduces the likelihood that simultaneous requests will repeatedly collide with the same rate limit.

Together, these measures make API usage more controlled and predictable.

Design System: Why Paper, Ink, and Cobalt?

We deliberately avoided another dark dashboard filled with purple gradients and neon effects.

Margin uses a tactile Paper–Ink–Cobalt design language inspired by printed examination scripts, annotated documents, and academic journals.

Warm Paper — #F4F1EA

The background evokes physical exam scripts, term papers, and archival documents.

Deep Ink — #101426

One-pixel borders and hard shadows, such as 3px 3px 0 #101426, create a sense of physical depth and make interface elements feel deliberate.

Translucent Pen-Wash — #C5CEFF

Evidence highlights use an inset box shadow:

box-shadow: inset 0 -0.5em 0 0 var(--wash);

The effect resembles a professor's highlighter passing over a relevant passage.

No UI framework bloat

The interface uses vanilla CSS custom properties rather than Tailwind or an external UI component library.

The result is a focused, document-oriented experience where evidence and reviewer decisions take priority over decorative dashboard elements.

One-Click Judge Mode and Reproducibility

We wanted judges and developers to evaluate Margin without unnecessary setup friction.

One-click judge access

The landing page includes a ⚖️ Judge Access option that authenticates the reviewer into a pre-seeded GNS102 Informatics & Formal Methods batch.

Offline mock engine

When CLOCKED_API_KEY is not configured, Margin falls back to deterministic, precomputed fixture data. This allows developers and judges to explore the workflow without live API credentials.

Automated tests

The project includes 34 automated tests across six test suites, run through Node.js's native test runner using:

npm test

These features make the application easier to evaluate, reproduce, and develop locally.

Try Margin Yourself

Repository: github.com/Josephjbassey/margin-review

Clone the project and start the development server:

git clone https://github.com/Josephjbassey/margin-review.git
cd margin-review
npm install
npm run seed
npm run dev

You can explore the application with the offline mock engine when CLOCKED_API_KEY is omitted. Live Clocked API functionality requires the appropriate credentials and configuration.

Final Thoughts

Academic integrity tools should help educators ask better questions, not replace their judgment with a probability score.

Margin explores a different approach: compare submissions within their actual cohort, check claims against assigned materials, surface relevant evidence, and give educators the context they need to make informed decisions.

There are still difficult questions around privacy, false positives, interpretation, and the limits of automated analysis. Those questions deserve to be part of the design process, not an afterthought.

Our goal is not to automate accusations. It is to make academic review more transparent, evidence-based, and fair.

Built by Joseph John Bassey for the Clocked Build Challenge 2026.

Explore the code: Margin on GitHub

[Boost]

John Joseph Bassey — Thu, 09 Jul 2026 22:52:16 +0000

John Joseph Bassey

Jul 9

I got tired of Django being left behind in UI, so I built a shadcn/ui equivalent.

#webdev #python #django #llm

2 min read

I got tired of Django being left behind in UI, so I built a shadcn/ui equivalent.

John Joseph Bassey — Thu, 09 Jul 2026 22:48:29 +0000

For years, the React and Next.js ecosystems have had a massive advantage: premium, plug-and-play UI components. Tools like shadcn/ui completely changed how developers build interfaces by offering beautifully styled, accessible components with zero vendor lock-in.

Meanwhile, if you were building a monolith with Django, htmx, and Alpine.js, you were left out in the cold. You either had to wire up custom HTML/CSS from scratch, fight with the complex configurations of heavy runtime libraries, or rely on locked pip packages where changing a simple button color required CSS overrides or forking a repo.

I realized Django didn't need another heavy library. It needed a delivery system.

Enter Djinn UI.

Djinn UI (available now on PyPI) is a CLI-based component registry for Django. It brings the copy-paste ownership model directly to your Python backend.

How it works:
Instead of adding a dependency to your INSTALLED_APPS, you simply run:
djinn add dashboard

Djinn drops the raw, perfectly styled HTML and Tailwind code directly into your templates/ folder. It uses native

{% include %}

tags. No custom syntax to learn, no runtime overhead. It is your code, and you own it completely.

Built for the Agentic Era:
We aren't just catching up to React; we are jumping ahead. Djinn UI is the first Django UI system built with AI in mind. It ships with a built-in MCP server. If you use tools like Cursor, you can simply say, "Build a pricing page using my Djinn components," and watch your AI agent scaffold your UI seamlessly.

Stop wasting weeks building components. Reclaim the power of the monolith.

Try it out: pip install djinn-ui
Check out the pypi package here: https://pypi.org/project/djinn-ui/