@ybouhjira/hyperkit-ai-renderer

Transforms raw data and intent strings into validated HyperKit UI schemas using a cheap LLM (Haiku or Gemini Flash by default).

The Problem It Solves

When a smart model like Opus generates a response, it knows what information to present but should not be burdened with memorizing 18 content type schemas, their exact JSON shapes, and the selection rules for when each is appropriate. Making the main model output UI schemas directly is wasteful and error-prone.

This package implements the 2-LLM architecture:

Smart model (Opus)          Renderer model (Haiku)
─────────────────           ──────────────────────
"Here are the metrics:  →   [Receives catalog of 18
 CPU 80%, RAM 60%..."        content types + intent]
                          →   Outputs validated JSON array
                          →   Schema-validated by Effect

The renderer step is cheap, focused, and runs with a compressed system prompt (CONTENT_TYPE_CATALOG) that gives it everything it needs. The main model stays context-clean.

Architecture

renderData(intent, options?)
  │
  ├── rendererStep(options)         ← creates a Step<string, SectionContent[]>
  │     ├── systemPrompt = CONTENT_TYPE_CATALOG + additionalContext?
  │     ├── model = "haiku" (default)
  │     ├── parseResponse = extractJson()   ← strips markdown fences
  │     └── outputSchema = S.Array(SectionContent)  ← Effect Schema validation
  │
  └── Pipeline.run(pipeline, intent)
        └── Returns { content: SectionContent[], trace: PipelineTrace }

LlmProvider is injected via Effect's dependency injection — the renderer itself has no direct dependency on any specific LLM SDK.

Installation

npm install @ybouhjira/hyperkit-ai-renderer

Peer dependencies:

npm install effect @ybouhjira/hyperkit-llm-pipeline @ybouhjira/hyperkit-mcp

Quick Start

import { Effect } from 'effect';
import { renderData } from '@ybouhjira/hyperkit-ai-renderer';
import { CliProvider } from '@ybouhjira/hyperkit-llm-pipeline';

const program = renderData('Show a summary of these server metrics: CPU 80%, Memory 60%, Disk 45%');

const { content, trace } = await Effect.runPromise(program.pipe(Effect.provide(CliProvider())));

console.log(content);
// [{ type: 'summary-grid', items: [{ icon: '💻', title: 'CPU', ... }] }]

console.log(`Rendered in ${trace.totalDurationMs}ms, cost $${trace.totalCostUsd.toFixed(5)}`);

How the Catalog Works

CONTENT_TYPE_CATALOG is a compressed system prompt embedded in this package. It is sent to the renderer LLM on every call and contains:

• 18 content type definitions with their exact JSON schemas and examples
• A RULES section requiring JSON-only output (no markdown, no explanation)
• A SELECTION GUIDE mapping common data patterns to appropriate content types

The catalog is compact by design — it fits comfortably in Haiku's context window with room for the intent and any additional context you provide.

import { CONTENT_TYPE_CATALOG } from '@ybouhjira/hyperkit-ai-renderer';

// Inspect what the renderer LLM receives as its system prompt
console.log(CONTENT_TYPE_CATALOG);

The 18 Content Types

| Type | Use For | | --------------- | -------------------------------------------- | | summary-grid | Key metrics, KPI cards with icons | | table | Structured tabular data | | code | Code snippets with syntax highlighting | | flow-diagram | Architecture layers | | layer-stack | Labeled layer visualization | | gap-analysis | Issues with critical/important/nice severity | | timeline | Step-by-step progress with status | | package-tree | Package/module overviews | | preset-grid | Option cards with gradients | | source-list | Grouped reference links | | text | Rich or plain text blocks | | issue-list | Bug/issue cards with icons | | decision-grid | Interactive option selection | | poll | Interactive quick vote | | form-fields | Interactive form inputs | | mockup-layout | Template-based UI mockups | | mockup-tree | Free-form component trees | | app | Live SolidJS applications |

API Reference

renderData(intent, options?)

Main entry point. Returns an Effect requiring LlmProvider in context.

function renderData(
  intent: string,
  options?: RenderDataOptions
): Effect.Effect<RenderResult, LlmError, LlmProvider>;

Parameters:

• intent — the raw data or description of what to render
• options.model — LLM model alias (default: "haiku")
• options.additionalContext — extra instructions appended to the catalog system prompt
• options.maxAttempts — retry budget for malformed JSON responses (default: 2)

Returns:

interface RenderResult {
  readonly content: readonly SectionContent[]; // validated UI blocks
  readonly trace: PipelineTrace; // timing, tokens, cost, attempts
}

rendererStep(options?)

Creates a Step<string, SectionContent[]> for use in a custom pipeline. Use this when you need to compose the renderer with other steps.

function rendererStep(options?: RendererStepOptions): Step<string, readonly SectionContent[]>;

import { rendererStep } from '@ybouhjira/hyperkit-ai-renderer';
import { Pipeline } from '@ybouhjira/hyperkit-llm-pipeline';

const step = rendererStep({ model: 'gemini-flash', additionalContext: 'Focus on security.' });
const pipeline = Pipeline.from('my-pipeline', step);

extractJson(response)

Strips markdown code fences from an LLM response and parses JSON. Used internally by rendererStep but exported for use in custom steps.

function extractJson(response: string): unknown;

Handles:

• Raw JSON strings
• ```json ... ``` code blocks
• ``` ... ``` blocks without a language tag

Throws SyntaxError on malformed JSON.

CONTENT_TYPE_CATALOG

The system prompt string given to the renderer LLM. Export it directly if you need to inspect or extend it.

const CONTENT_TYPE_CATALOG: string;

Custom Model and Provider

Override the model per call:

const { content } = await Effect.runPromise(
  renderData('intent', { model: 'gemini-flash' }).pipe(Effect.provide(GeminiProvider()))
);

Add domain-specific instructions:

const { content } = await Effect.runPromise(
  renderData('AWS cost report for Q1', {
    additionalContext: 'Prefer table and summary-grid. Use USD for all cost values.',
  }).pipe(Effect.provide(CliProvider()))
);

Testing with MockProvider

MockProvider from @ybouhjira/hyperkit-llm-pipeline intercepts LLM calls without hitting any real API. Pass a fixed response string keyed by model name, or a function that receives the full LlmRequest.

import { Effect } from 'effect';
import { MockProvider } from '@ybouhjira/hyperkit-llm-pipeline';
import { renderData } from '@ybouhjira/hyperkit-ai-renderer';

it('renders a summary-grid from metrics', async () => {
  const mockResponse = JSON.stringify([
    {
      type: 'summary-grid',
      items: [{ icon: '💻', title: 'CPU', description: '80% usage', iconColor: 'teal' }],
    },
  ]);

  const program = renderData('CPU usage is 80%').pipe(
    Effect.provide(MockProvider({ haiku: mockResponse }))
  );

  const { content } = await Effect.runPromise(program);
  expect(content[0].type).toBe('summary-grid');
});

Inspect the actual request sent to the LLM:

import type { LlmRequest } from '@ybouhjira/hyperkit-llm-pipeline';

it('includes the intent in the user prompt', async () => {
  const captured: LlmRequest[] = [];

  const program = renderData('show disk usage').pipe(
    Effect.provide(
      MockProvider((req: LlmRequest) => {
        captured.push(req);
        return mockResponse;
      })
    )
  );

  await Effect.runPromise(program);
  expect(captured[0].userPrompt).toContain('show disk usage');
  expect(captured[0].systemPrompt).toContain('summary-grid');
});

Test retry behavior:

it('succeeds on retry after first attempt fails', async () => {
  let calls = 0;

  const program = renderData('metrics', { maxAttempts: 2 }).pipe(
    Effect.provide(
      MockProvider(() => {
        calls++;
        return calls === 1 ? 'bad json {{{' : validResponse;
      })
    )
  );

  const { trace } = await Effect.runPromise(program);
  expect(trace.steps[0].attempts).toBe(2);
});

Dependencies

| Package | Role | | ---------------------------------- | ------------------------------------------------------------------ | | @ybouhjira/hyperkit-llm-pipeline | Step, Pipeline, LlmProvider, PipelineTrace, MockProvider | | @ybouhjira/hyperkit-mcp | SectionContent Effect Schema (the 18 UI content types) | | effect (peer) | Schema validation, dependency injection, Effect.Effect type |