markform 0.1.22 → 0.1.23

package/README.md

@@ -1,10 +1,12 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21885509869)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21885509869)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
 [![npm version](https://img.shields.io/npm/v/markform)](https://www.npmjs.com/package/markform)
 [![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
+### What if your Markdown docs had an agent-friendly semantic API?
+
 **Markform** is a text format for defining structured forms that humans can read,
 machines can parse, and agents can fill via tool calls.
 
@@ -13,12 +15,14 @@ Agents fill forms incrementally via patches.
 Fields are validated, so errors are caught early and can be corrected.
 Humans can review or intervene at any point.
 
-**Why forms?** For deep research or complex AI tasks, you need more than just prompts or
+### Why forms?
+
+For deep research or complex AI tasks, you need more than just prompts or
 flow: you need *structure*, which is precise control over agent output at every stage of
 a workflow. A well-designed form combines instructions, structured data, and validations
 in one place.
 
-**How it works:**
+### How it Works
 
 - A Markform document exposes a programmatic interface: users fill fields via CLI or web
   UI, agents fill via tool calls ([Vercel AI SDK](https://github.com/vercel/ai)
@@ -33,9 +37,25 @@ in one place.
   [precise specification](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md).
   Export Markform syntax to JSON, YAML, JSON Schema, or plain Markdown reports.
 
-Markform syntax is a good source format: token-efficient text you can read, diff, and
-version control. Structure is defined with HTML comment tags (`<!-- field -->`) that
-render invisibly on GitHub, so forms look like regular Markdown.
+- Optionally, the whole thing is wrapped in a harness where large forms can be filled
+  concurrently by any LLM in a structured agentic loop.
+
+### Useful details
+
+- Markform syntax is a good source format: it is **token-efficient text** you can read, diff, and
+  version control and it is **ideal for context engineering** because it combines
+  document context, data schema, and memory (data filled so far).
+
+- Structure is defined with HTML comment tags (`<!-- field -->`) that
+  render invisibly on GitHub, so **forms look like regular Markdown**. (Jinja-style
+  tag syntax also works if you prefer.)
+
+- Optionally, **a fill record** of the form-filling process is kept, so you can see
+  and debug exactly how forms are filled by agents, tool usage, LLM call time, etc.
+
+- The CLI has a built-in web renderer, **`markform serve`**, for easy viewing and debugging
+  of forms (including a form web UI, the form schema, and a waterfall-style overview of the
+  fill record, including performance details, which is useful for large, concurrently filled forms).
 
 ## Simple Example: Research a Movie
 
@@ -364,16 +384,16 @@ flowchart LR
     subgraph SPEC["<b>MARKFORM SPEC</b>"]
         direction TB
 
-        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax and frontmatter (form, group, string-field, checkboxes, etc.)"]
+        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax<br/>and frontmatter (form,<br/>group, string-field, <br/>checkboxes, etc.)"]
         end
 
-        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions for forms, fields, values (in Zod but mappable to JSON Schema or Pydantic)"]
+        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions<br/>for forms, fields, values"]
         end
 
-        subgraph L3["<b>LAYER 3: VALIDATION & FORM FILLING</b><br/>Rules for filling forms via patches, field ids, required field semantics, validation hooks"]
+        subgraph L3["<b>LAYER 3: VALIDATION <br/>AND PATCHES</b><br/>Rules for filling forms<br/>via patches, required<br/>field semantics, validation"]
         end
 
-        subgraph L4["<b>LAYER 4: TOOL API & INTERFACES</b><br/>Abstract API for agents and humans (TypeScript and AI SDK integration)"]
+        subgraph L4["<b>LAYER 4: TOOL API <br/>AND INTERFACES</b><br/>Abstract form-filling<br/>loop, concurrency<br/>model, tool layer"]
         end
 
         L4 --> L3 --> L2 --> L1
@@ -382,19 +402,19 @@ flowchart LR
     subgraph IMPL["<b>THIS IMPLEMENTATION</b>"]
         direction TB
 
-        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface to all features"]
+        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface<br/>to all features"]
         end
 
-        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library using AI SDK tools"]
+        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library><br/>(AI SDK tools)"]
         end
 
-        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Step-by-step form-filling agentic loop"]
+        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Concurrent form-filling<br/>agentic loop<br/>(AI SDK)"]
         end
 
-        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer, patch application, validation (uses jiti for TypeScript rules)"]
+        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer,<br/>patch application,<br/>validation (jiti for rules)"]
         end
 
-        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing with .session.yaml transcripts"]
+        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing<br/>(.session.yaml transcripts)"]
         end
 
         CLI --> ENGINE

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
 import { R as PatchSchema } from "./coreTypes-CTLr-NGd.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-C7mO7VkZ.mjs";
+import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-KzQztrDV.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-C7mO7VkZ.mjs → apply-KzQztrDV.mjs}

@@ -3,7 +3,7 @@ import { n as formatUrlAsMarkdownLink } from "./urlFormat-lls7CsEP.mjs";
 import YAML from "yaml";
 
 //#region src/errors.ts
-const VERSION = "0.1.22";
+const VERSION = "0.1.23";
 /**
 * Base error class for all markform errors.
 * Consumers can catch this to handle any markform error.
@@ -4357,4 +4357,4 @@ function applyPatches(form, patches) {
 
 //#endregion
 export { WEB_SEARCH_CONFIG as $, DEFAULT_FORMS_DIR as A, DEFAULT_ROLES as B, getNumberAttr as C, isTagNode as D, getValidateAttr as E, DEFAULT_MAX_TURNS as F, deriveExportPath as G, MAX_FORMS_IN_MENU as H, DEFAULT_PORT as I, deriveSchemaPath as J, deriveFillRecordPath as K, DEFAULT_PRIORITY as L, DEFAULT_MAX_PARALLEL_AGENTS as M, DEFAULT_MAX_PATCHES_PER_TURN as N, parseOptionText as O, DEFAULT_MAX_STEPS_PER_TURN as P, SUGGESTED_LLMS as Q, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as R, getBooleanAttr as S, getStringAttr as T, REPORT_EXTENSION as U, DEFAULT_ROLE_INSTRUCTIONS as V, USER_ROLE as W, parseRolesFlag as X, detectFileType as Y, transformHarnessConfigToTs as Z, tryParseSentinelResponse as _, isPatchError as _t, validate as a, MarkformConfigError as at, extractOptionItems as b, wrapApiError as bt, computeProgressSummary as c, MarkformParseError as ct, serializeForm as d, ParseError as dt, formatSuggestedLlms as et, serializeRawMarkdown as f, isAbortError as ft, validateSyntaxConsistency as g, isParseError as gt, preprocessCommentSyntax as h, isMarkformError as ht, inspect as i, MarkformAbortError as it, DEFAULT_MAX_ISSUES_PER_TURN as j, AGENT_ROLE as k, computeStructureSummary as l, MarkformPatchError as lt, detectSyntaxStyle as m, isLlmError as mt, getAllFields as n, hasWebSearchSupport as nt, computeAllSummaries as o, MarkformError as ot, serializeReport as p, isConfigError as pt, deriveReportPath as q, getFieldsForRoles as r, parseModelIdForDisplay as rt, computeFormState as s, MarkformLlmError as st, applyPatches as t, getWebSearchConfig as tt, isFormComplete as u, MarkformValidationError as ut, CHECKBOX_MARKERS as v, isRetryableError as vt, getStringArrayAttr as w, extractTableContent as x, extractFenceValue as y, isValidationError as yt, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as z };
-//# sourceMappingURL=apply-C7mO7VkZ.mjs.map
+//# sourceMappingURL=apply-KzQztrDV.mjs.map