LOGIC.md — declarative reasoning contracts that compile to LangGraph StateGraph

OSS Product Help LangGraph
1

Been building a declarative spec format for multi-agent reasoning, and the LangGraph adapter is the most developed integration. Posting here for feedback from people running StateGraph systems in production.

What LOGIC.md is

A YAML file that declares step DAGs, output contracts, quality gates, tool permissions, and fallback chains. Framework-agnostic, compiles to LangGraph today (CrewAI and AutoGen planned).

Why this might matter for LangGraph users

Right now, if you want StateGraph to enforce output contracts, quality gates, or tool permissions, you write it imperatively — validation logic in each node function, retry logic scattered across the graph. With LOGIC.md you declare it once:

yaml

contracts:
  outputs:
    sources: { type: array, items: { type: object } }
quality_gates:
  post_output:
    - check: "outputs.sources.length > 0"
      action: retry
      max_retries: 3

The adapter compiles this to StateGraph node definitions with:

  • Type-validated state schemas

  • Pre/post node hooks for contract enforcement

  • Automatic retry logic for failed quality gates

  • Per-node tool permission checks

  • Fallback edge routing

typescript

import { compile_to_langgraph } from "@logic-md/adapters/langgraph";

const spec = parse(markdownContent);
const graph_builder = compile_to_langgraph(spec);
const graph = graph_builder.compile();
// graph is a LangGraph StateGraph with LOGIC.md contracts baked in

Adapter state (honest)

Proof of concept. Core node compilation works. Quality gates and tool permissions are stubbed. Needs real workflows to validate the API — I built it in isolation so there are almost certainly design issues a production LangGraph user would catch immediately.

What I’m looking for feedback on

  1. Does the LOGIC.md data model fit how you actually build LangGraph workflows, or are there primitives missing?

  2. For those running LangGraph at scale — what do you currently do for output contracts and quality gates? Imperative code, or something else?

  3. Streaming: how should declarative contracts behave when reasoning happens incrementally? Open design question.

  4. Are there LangGraph patterns you’d want the adapter tested against?

Links

Happy to pair with anyone who wants to push the adapter forward, or take feedback issues on the repo.