Carmen Labs

Create an MView with an AI agent

Navigable guide for AI models to generate conformant MViews by accessing structured documentation.

Create an MView with an AI agent

This page is designed to be navigable by AI models. It is not self-contained: it guides you through the structured documentation so you can generate a conformant MView.

For AI models: how to use this page

When a user asks you to create an MView (e.g., "Create a mutation of this sales.csv file showing me charts by sales quantity per month"), follow this flow:

1. Understand what an MView is

Read first: /specs/mview/overview

This will give you:

  • The conceptual model (source file → parser → data model → component → view)
  • Design invariants (never modifies the original file, pure parser, component with no I/O)
  • File structure (mview.json, parser, component, resources/)

2. Identify required capabilities

Consult: /specs/mview/capabilities

Based on the source file type:

  • CSV/XLSX/tabular → ["table"]
  • Markdown → ["markdown", "document"]
  • JSON/YAML/XML → ["tree", "structured"]
  • Logs → ["log", "text"]
  • Source code → ["code", "text"]

Each capability defines the normalized input shape that the runtime will deliver to the parser.

3. Build the mview.json manifest

Full reference: /specs/mview/schema-reference

JSON Schema: https://schemas.carmenlabs.com/mview/v1/schema.json

Required fields:

  • $schema: always "https://schemas.carmenlabs.com/mview/v1/schema.json"
  • id: unique identifier in kebab-case (pattern: ^[a-z0-9][a-z0-9._-]*$)
  • name: human-readable name
  • version: semver MAJOR.MINOR.PATCH
  • prompt: the user prompt that originated this MView
  • runtime: object with environment, renderer, and optionally version
  • entry: object with parser and component (relative paths)

Common optional fields:

  • description: one-line summary
  • accepts: array of required capabilities
  • source: object with path (relative) and optionally contentHash
  • resources: object with path to assets directory
  • settings: initial configuration that affects rendering
  • metadata: provenance (who, when, with what model)

Critical rules:

  • All paths must be relative, never absolute
  • additionalProperties: false at all levels
  • settings may affect rendering, metadata must never do so

4. Write the parser

Full contract: /specs/mview/parser-contract

Signature:

export default async function parse(input: any, context: any) {
  // Return a JSON-serializable data model
}
  • input: normalized data according to the capability declared in accepts
  • context: object with { input, source, settings, resources, workspace }
  • Must be a pure function: same input → same output
  • No filesystem access, no absolute paths
  • Safely re-runnable when the source file changes

5. Write the view component

Full contract: /specs/mview/component-contract

Signature:

export default function Component({ data, settings, source, resources }: any) {
  // Render only `data` and `settings`
}
  • Renders only the received data model
  • No direct file reads
  • No arbitrary fetch calls
  • Degrade gracefully on missing data

6. Validate before delivering

Checklist:

  • mview.json validates against the JSON Schema
  • All paths are relative
  • accepts matches the source file type
  • Parser returns data that the component expects
  • No additionalProperties outside the schema

7. Directory structure

Recommended convention: /specs/mview/directory-layout

Option 1 (next to file):

sales.csv
.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

Option 2 (centralized):

.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

Full worked example

See: /examples/sales-dashboard

Shows a real case with CSV file, complete manifest, functional parser, and React component.

Specification navigation

To dive deeper into specific aspects:

Canonical schema

Validate manifests directly against:

https://schemas.carmenlabs.com/mview/v1/schema.json

Do not hardcode local copies that may become outdated.

  1. Read /specs/mview/overview to understand the model
  2. Consult /specs/mview/capabilities to identify accepts
  3. Reference /specs/mview/schema-reference to build mview.json
  4. Follow /specs/mview/parser-contract to write the parser
  5. Follow /specs/mview/component-contract to write the component
  6. Validate against the JSON Schema before delivering
  7. Review /examples/sales-dashboard if you need a concrete example

This structure allows you to navigate the documentation according to what you need, instead of processing everything at once.

Crear una MView con un agente de IA

Guía navegable para que modelos de IA generen MViews conformes accediendo a la documentación estructurada.

Crear una MView con un agente de IA

Esta página está diseñada para ser navegable por modelos de IA. No es autocontenida: te guía a través de la documentación estructurada para que puedas generar una MView conforme.

Para modelos de IA: cómo usar esta página

Cuando un usuario te pide crear una MView (por ejemplo: "Crea una mutación de este archivo sales.csv mostrándome gráficos por cantidad de ventas por mes"), sigue este flujo:

1. Entiende qué es una MView

Lee primero: /specs/mview/overview

Esto te dará:

  • El modelo conceptual (archivo fuente → parser → modelo de datos → componente → vista)
  • Las invariantes de diseño (nunca modifica el archivo original, parser puro, componente sin I/O)
  • La estructura de archivos (mview.json, parser, componente, resources/)

2. Identifica las capacidades requeridas

Consulta: /specs/mview/capabilities

Según el tipo de archivo fuente:

  • CSV/XLSX/tabular → ["table"]
  • Markdown → ["markdown", "document"]
  • JSON/YAML/XML → ["tree", "structured"]
  • Logs → ["log", "text"]
  • Código fuente → ["code", "text"]

Cada capacidad define la forma normalizada de entrada que el runtime entregará al parser.

3. Construye el manifiesto mview.json

Referencia completa: /specs/mview/schema-reference

Esquema JSON Schema: https://schemas.carmenlabs.com/mview/v1/schema.json

Campos requeridos:

  • $schema: siempre "https://schemas.carmenlabs.com/mview/v1/schema.json"
  • id: identificador único en kebab-case (patrón: ^[a-z0-9][a-z0-9._-]*$)
  • name: nombre legible para humanos
  • version: semver MAJOR.MINOR.PATCH
  • prompt: el prompt del usuario que originó esta MView
  • runtime: objeto con environment, renderer, y opcionalmente version
  • entry: objeto con parser y component (rutas relativas)

Campos opcionales comunes:

  • description: resumen de una línea
  • accepts: array de capacidades requeridas
  • source: objeto con path (relativa) y opcionalmente contentHash
  • resources: objeto con path al directorio de assets
  • settings: configuración inicial que afecta el renderizado
  • metadata: procedencia (quién, cuándo, con qué modelo)

Reglas críticas:

  • Todas las rutas deben ser relativas, nunca absolutas
  • additionalProperties: false en todos los niveles
  • settings puede afectar renderizado, metadata nunca debe hacerlo

4. Escribe el parser

Contrato completo: /specs/mview/parser-contract

Firma:

export default async function parse(input: any, context: any) {
  // Retorna un modelo de datos JSON-serializable
}
  • input: datos normalizados según la capacidad declarada en accepts
  • context: objeto con { input, source, settings, resources, workspace }
  • Debe ser función pura: misma entrada → misma salida
  • Sin acceso al filesystem, sin rutas absolutas
  • Reejecutable de forma segura cuando cambia el archivo fuente

5. Escribe el componente de vista

Contrato completo: /specs/mview/component-contract

Firma:

export default function Component({ data, settings, source, resources }: any) {
  // Renderiza solo `data` y `settings`
}
  • Renderiza solo el modelo de datos recibido
  • Sin lecturas de archivos directas
  • Sin llamadas fetch arbitrarias
  • Degrada con gracia ante datos faltantes

6. Valida antes de entregar

Checklist:

  • mview.json valida contra el JSON Schema
  • Todas las rutas son relativas
  • accepts coincide con el tipo de archivo fuente
  • El parser retorna datos que el componente espera
  • No hay additionalProperties fuera del esquema

7. Estructura de directorios

Convención recomendada: /specs/mview/directory-layout

Opción 1 (junto al archivo):

sales.csv
.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

Opción 2 (centralizada):

.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/

Ejemplo completo trabajado

Ver: /examples/sales-dashboard

Muestra un caso real con archivo CSV, manifiesto completo, parser funcional y componente React.

Para profundizar en aspectos específicos:

Esquema canónico

Valida manifiestos directamente contra:

https://schemas.carmenlabs.com/mview/v1/schema.json

No hardcodees copias locales que puedan desactualizarse.

Flujo de trabajo recomendado para modelos

  1. Leer /specs/mview/overview para entender el modelo
  2. Consultar /specs/mview/capabilities para identificar accepts
  3. Referenciar /specs/mview/schema-reference para construir mview.json
  4. Seguir /specs/mview/parser-contract para escribir el parser
  5. Seguir /specs/mview/component-contract para escribir el componente
  6. Validar contra el JSON Schema antes de entregar
  7. Revisar /examples/sales-dashboard si necesitas un ejemplo concreto

Esta estructura permite que navegues la documentación según lo que necesites, en lugar de procesar todo de una vez.