HUMAN Framework

Human-to-Agent Mapping & Navigation. Turn messy human thoughts into structured, validated Agent Contracts that any AI agent can execute. v1.0 — the Agent Contract is now a stable, documented protocol (PROTOCOL.md).

▶ Try the live demo — paste a messy thought, get an Agent Contract. Runs fully in your browser.

People don't speak in prompts. We talk in incomplete, informal, chaotic thoughts. AI agents need structure: a goal, constraints, tasks, quality criteria. HUMAN is the translation layer between the two.

messy human thought ──▶ HUMAN loop ──▶ Agent Contract ──▶ any AI agent
                        H·U·M·A·N       (JSON/YAML/prompt)

Highlights

• The HUMAN loop as a real pipeline — Hear → Understand → Map → Agentize → Navigate, five composable stages you can extend or replace.
• Zero runtime dependencies — the deterministic engine works offline, instantly, predictably.
• Structured extraction — intent (scored, with confidence), constraints, and entities: deadlines, budgets, audience, technologies.
• Sessions — follow-up questions with stable ids; answers are folded back into the right part of the contract.
• Six renderers + registry — prompt, system, json, yaml, markdown, xml, or register your own.
• Optional LLM refinement — Anthropic/OpenAI adapters (plain fetch, no SDKs) or any custom model; invalid or failed LLM output safely falls back to the deterministic contract.
• Runtime validation — validateContract() plus a formal JSON Schema, so any tool in any language can interoperate.
• Bilingual contracts — English and Slovak, auto-detected from the input.
• Executor with self-verification — run the contract via any adapter; the output is judged against the contract's own verification checks and repaired if it fails.
• Custom domains — register your own domains (legal, fitness, …) with keywords and presets; no forking.
• Quality tooling — contract linter with a 0–100 score, structural diff/merge, and follow-up revisions ("actually, use Vue").
• Measured, not promised — a bilingual eval suite (human eval) benchmarks intent accuracy, entity P/R/F1 and constraint extraction on every CI run. Current score: 100% across all metrics in both languages.
• Explainable — result.explain() narrates every decision: which keywords voted for which domain, where each constraint came from, why the input is ambiguous.
• Strict verifier protocol — stable check ids, boolean-only verdicts, an optional independent judge model, timeouts and AbortSignal.
• Execution policies — the contract bounds the agent: allowed tools, forbidden actions, human-approval gates, time/cost/token budgets. Rendered into every prompt and enforceable in code.
• Understands negation, dates and money — "don't use react" becomes { name: "react", mode: "forbidden" }; "do piatku" becomes an ISO date with a certainty score; "300 eur" becomes { amount: 300, currency: "EUR" }.
• Integrates everywhere — export contracts as MCP or OpenAI tools; adapters for Anthropic, OpenAI, Ollama (local models) and a Vercel AI SDK bridge; project-wide defaults via human.config.json.
• Observable — executeContractStream() emits every lifecycle event; every result carries telemetry: traceId, per-call durations, token usage, estimated cost.
• Stable protocol — frozen v1.0 schema, documented guarantees, and migrateContract() upgrading any contract since 0.2.

Install

npm install human-framework

Quick start

import { human } from "human-framework";

const result = human("Môj web padá s chybou 500, oprav to do zajtra");

result.contract.detectedDomain;          // "debug"
result.contract.context.entities;        // { deadline: "zajtra", language: "sk" }
console.log(result.toPrompt());          // paste into any AI chat

Ask before executing — the Navigate loop:

import { HumanSession } from "human-framework";

const s = HumanSession.create("I want to build an app");
s.pendingQuestions;                       // what the agent should ask first
s.answer("outcome", "an app my mom can use");
s.answer("limits", "free hosting only");
console.log(s.render("yaml"));

Optional LLM sharpening with a safe fallback:

import { human, AnthropicAdapter, refineContract } from "human-framework";

const draft = human("build a landing page, launch is friday").contract;
const { contract, refined } = await refineContract(
  draft,
  new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
);
// refined === false ⇒ contract is still the valid deterministic draft

Close the whole loop — execute with self-verification and repair:

import { human, AnthropicAdapter, executeContract } from "human-framework";

const contract = human("write a launch tweet, no emojis").contract;
const result = await executeContract(contract, new AnthropicAdapter({ apiKey }));
result.verified;            // true | false | null
result.verificationReport;  // per-check pass/fail with notes
result.repaired;            // whether a failing draft was auto-fixed

CLI

npx human "compare notion and obsidian for a small team" --format=prompt
npx human ask "I want to build an app"
npx human lint contract.json
npx human revise contract.json "actually use react, budget 50 €"
ANTHROPIC_API_KEY=... npx human exec "write a launch tweet, no emojis"
npx human validate contract.json

Ask "why?" — the pipeline explains itself:

console.log(human("build it or maybe compare tools first").explain());
// Domain: build (confidence 0.4)
//   Matched terms: build
//   Other candidates: research (0.2)
//   Status: AMBIGUOUS — … includes an intent-clarify follow-up question

Benchmark it yourself:

npx human eval          # 43 bilingual cases: intent, entities, constraints, adversarial

Watch it work, measure what it costs:

for await (const event of executeContractStream(contract, adapter)) {
  console.log(event.type); // execution.started → … → execution.completed
}
const { telemetry } = await executeContract(contract, adapter, {
  costPerMTokens: { input: 3, output: 15 },
});
telemetry.totalUsage;        // { inputTokens, outputTokens }
telemetry.estimatedCostUsd;  // 0.0042

Plug it into agent ecosystems:

contractToMcpTool(contract);     // MCP tool definition
contractToOpenAITool(contract);  // OpenAI function-calling tool

Documentation

• The Agent Contract Protocol — the frozen v1.0 spec and its guarantees
• Architecture — the pipeline, design rules, diagrams
• API reference
• Migration from 0.2.x
• Agent Contract JSON Schema
• Runnable examples in examples/

The Agent Contract

The contract is the interoperable unit of the framework — a validated JSON object with intent, agentRole, goal, context (incl. extracted entities), constraints, tasks, outputFormat, qualityBar, verification, followUpQuestions, and meta (engine, stages, confidence). The long-term ambition: a schema that different agent frameworks can produce and consume.

Contributing

Issues, stars, and pull requests are very welcome — see CONTRIBUTING.md. MIT licensed.