Prism Tools

Transform, reshape, visualize, and export data passing through your workflows.

Prism tools operate on data in-flight. They transform structures via natural language, bridge incompatible types between systems, generate charts, render reports, convert formats, paginate large results, and analyze code. Prism generates verified code that executes in a sandboxed runtime – repeated identical requests execute from cache at near-zero cost. All Prism tools are available at data-grout@1/prism.*@1.

prism.refract@1

Reshape a data structure using a natural language instruction. Describe the transformation you want, pass the data, and Refract produces the result.

Parameters

Example

{
  "name": "data-grout@1/prism.refract@1",
  "arguments": {
    "goal": "group invoices by customer and sum totals",
    "payload": [
      { "customer": "Acme", "amount": 500 },
      { "customer": "Globex", "amount": 300 },
      { "customer": "Acme", "amount": 200 }
    ]
  }
}

Response:

{
  "result": [
    { "customer": "Acme", "total": 700, "count": 2 },
    { "customer": "Globex", "total": 300, "count": 1 }
  ]
}

prism.focus@1

Bridge incompatible types between systems. Focus converts data from one semantic type to another, handling field mapping, renaming, and structural differences. The planner inserts Focus steps automatically when a workflow connects tools with mismatched types; you can also call it directly.

Parameters

Example

{
  "name": "data-grout@1/prism.focus@1",
  "arguments": {
    "data": {
      "FirstName": "Jane",
      "LastName": "Chen",
      "Email": "jane@acme.com",
      "Company": "Acme Corp"
    },
    "source_type": "crm.lead@1",
    "target_type": "billing.customer@1"
  }
}

Response:

{
  "result": {
    "customer_name": "Jane Chen",
    "email": "jane@acme.com",
    "company_name": "Acme Corp"
  },
  "adapter_used": "crm.lead@1 -> billing.customer@1",
  "confidence": 0.96
}

If no direct adapter exists, Focus searches for a multi-hop path (e.g. lead -> contact -> customer) and applies each conversion in sequence.

prism.chart@1

Generate a chart from data. Describe the visualization you want, pass the data, and Chart returns a PNG image URL by default. The PNG is rendered by a Rust NIF, uploaded to S3, and served via CDN (or the app host as fallback).

Parameters

Default Response

With default formats ["png"], the response includes:

• image_url — URL to the rendered PNG image (display this to the user)
• text_sparkline — Unicode block sparkline (▁▂▄▆█) — always included
• summary — Statistics: min, max, mean, sum, count — always included
• chart_type — Detected chart type
• spec_hash — Content hash for caching

SVG ("svg") and SVG sparkline ("sparkline") are opt-in only — add them to the formats array to include them.

Example

{
  "name": "data-grout@1/prism.chart@1",
  "arguments": {
    "goal": "bar chart of sales by region",
    "payload": [
      { "region": "North", "sales": 42000 },
      { "region": "South", "sales": 31000 },
      { "region": "East", "sales": 58000 },
      { "region": "West", "sales": 47000 }
    ]
  }
}

prism.render@1

Generate formatted reports or content from structured data. Render produces Markdown, HTML, or other content types based on a payload and optional formatting instructions.

Parameters

Example

{
  "name": "data-grout@1/prism.render@1",
  "arguments": {
    "payload": {
      "total_invoices": 142,
      "total_revenue": 284000,
      "overdue": 12,
      "top_customer": "Acme Corp"
    },
    "content_type": "summary",
    "goal": "executive summary of monthly billing"
  }
}

prism.export@1

Convert content between formats. Export takes rendered content (from Render or any other source) and converts it to a target format.

Parameters

Example

{
  "name": "data-grout@1/prism.export@1",
  "arguments": {
    "content": "| Customer | Revenue |\n|---|---|\n| Acme | $42,000 |",
    "format": "csv"
  }
}

prism.paginate@1

Navigate large result sets page by page. Paginate caches the full result on first call and serves subsequent pages from cache.

Parameters

Example

First call:

{
  "name": "data-grout@1/prism.paginate@1",
  "arguments": {
    "payload": [ "...large array..." ],
    "per_page": 10
  }
}

Response includes a cache_ref. To get the next page:

{
  "name": "data-grout@1/prism.paginate@1",
  "arguments": {
    "cache_ref": "pg_abc123",
    "page": 2
  }
}

Auto-Pagination for -all- Tools

QuickBooks and Salesforce tools with -all- in their name (e.g., get-all-invoices, get-all-accounts) automatically paginate across multiple API pages. Two additional parameters are injected into their schemas:

How it works

1. The tool executes normally, returning the first page of results
2. If more data is available, remaining pages are fetched in parallel (QB) or sequentially (SF)
3. QB continuation queries preserve the original WHERE/ORDER BY clauses from the tool’s IR (no degradation to SELECT * FROM entity)
4. All records are cached in ResultCache — the response includes _cache_ref for prism.paginate
5. If refract is set, the full dataset is piped through prism.refract automatically

Input hardening

User-provided refract goals are sanitized via InputSanitizer before being interpolated into LLM prompts. Goals are wrapped in XML container tags (<user_goal>...</user_goal>) with explicit instructions to the model to treat the content as untrusted data. Field names from custom schemas are validated against a strict allowlist before being injected into queries.

Example: Fetch all invoices and summarize

{
  "name": "quickbooks@v1/get-all-invoice-details-list@v1",
  "arguments": {
    "limit": 5000,
    "refract": "total amount and count of invoices grouped by customer name"
  }
}

The response includes the refracted summary plus a _cache_ref for browsing the raw records via prism.paginate.

Schema-aware query optimization

For Salesforce users with custom fields (__c), the system automatically:

1. Downloads the user’s custom schema at OAuth auth time (via SchemaSyncWorker)
2. Augments SOQL queries to include relevant custom fields
3. When a refract goal is provided, attempts query-level refraction first – generating a targeted SOQL query (with GROUP BY, aggregates, WHERE) that directly answers the goal without fetching all records
4. Falls back to full pagination + in-memory refraction if query generation fails

Data teeing with _cache_ref

The _cache_ref returned by auto-paginated responses can be passed directly to any frame tool (frame.slice, frame.filter, frame.sort, frame.group, frame.pivot, frame.join) via the cache_ref parameter, avoiding re-transmission of large datasets.

prism.code_lens@1

Analyze source code. Code Lens parses code, extracts structure, identifies patterns, and answers questions about implementation.

Parameters

Example

{
  "name": "data-grout@1/prism.code_lens@1",
  "arguments": {
    "code": "def calculate_total(items):\n    return sum(item.price * item.qty for item in items)",
    "language": "python",
    "options": { "complexity": true }
  }
}

prism.diff_analyzer@1

Analyze the differences between two versions of code. Diff Analyzer identifies what changed, why it matters, and whether the change introduces risks.

Parameters

Example

{
  "name": "data-grout@1/prism.diff_analyzer@1",
  "arguments": {
    "before": "def get_user(id):\n    return db.find(id)",
    "after": "def get_user(id, include_deleted=False):\n    return db.find(id, include_deleted)",
    "goal": "check for breaking changes"
  }
}

prism.code_query@1

Run semantic queries against a code repository using predefined invariant query names such as dependency_cycles, test_gaps, security_concerns, or hotspots.

Parameters

Example

{
  "name": "data-grout@1/prism.code_query@1",
  "arguments": {
    "repo_id": "repo_abc123",
    "query": "security_concerns"
  }
}

Caching

Prism tools cache the generated transformation code. When you send an identical request (same goal, same structure), the cached version executes immediately at near-zero cost. This makes repeated transformations in loops or recurring workflows very efficient.