ACM Framework

An industry-grade reference implementation of the Agentic Contract Model (ACM) v0.5 - A Spec‑First Contract Layer and Open Reference Runtime for Agentic Systems, delivering contract-first planning, deterministic execution, and replayable decision memory across AI agent stacks. This monorepo hosts the canonical Node.js implementation, specification artifacts, and cross-language architecture guidance.

📢 ACM v0.5 introduces fully typed capability maps, resumable execution, nucleus-governed LLM usage, and replay bundles engineered for regulated environments.

---

Table of Contents

• Why ACM?
• Feature Highlights
• Documentation Index
• Monorepo at a Glance
• Package Matrix
• Quick Start
• Plan → Execute → Replay Flow
• Architecture Overview
• Governance & Compliance
• Roadmap
• Contributing
• Resources & Support
• License

---

Why ACM?

Traditional agent stacks mix stochastic planning with imperative code, making audits and safety reviews brittle. ACM adds a contract layer that binds plans, tools, tasks, and policies into versioned artifacts so you can:

• ✅ Prove compliance — Ship append-only ledgers, guard evaluations, and replay bundles for every run.
• ✅ Control tool access — Curate capabilities and tool envelopes planners may target.
• ✅ Standardize planning — Preserve planner alternatives, rationale, and prompt hashes for reproducibility.
• ✅ Resume safely — Checkpoint deterministic runtime progress and restart mid-plan.
• ✅ Integrate anywhere — Bridge ACM contracts to LangGraph, Microsoft Agent Framework, MCP servers, or custom runtimes with minimal glue.

The framework follows the ACM specification, treating Goal, Context Packet, Plan, Capability, Task, Tool, Policy, and Ledger as first-class artifacts.

---

Feature Highlights

Pillar	What You Get	Key Packages
Contract-First SDK	Typed contracts for tools, tasks, capabilities, ledger entries, guard expressions, policy hooks, and verification adapters. Built-in context tools (query_context, request_context_retrieval), token budget enforcement, and anti-hallucination grounding.	@ddse/acm-sdk
Structured Planning	Multi-plan generation with rationale, prompt digests, tool-call envelopes, context provider integration, and deterministic selectors.	@ddse/acm-planner
Deterministic Runtime	Guard evaluation, policy gates, retries/backoff, checkpointing, streaming sinks, ledger emission, and task scope filtering.	@ddse/acm-runtime
High-Level Orchestrator	Single-call helper that wires planner, runtime, nucleus, context providers, and adapters.	@ddse/acm-framework
Adapters & Integrations	LangGraph / Microsoft Agent Framework bridges plus Model Context Protocol tooling.	@ddse/acm-adapters, @ddse/acm-mcp
Replay & Analysis	Export/import replay bundles with ledger verification and tool-call inspection.	@ddse/acm-replay
Reference Experiences	Deterministic demos and a production-style AI coding assistant with budgeting and streaming UX.	@ddse/acm-examples, @ddse/acm-aicoder

---

Documentation Index

• 📘 Specification: ACM Spec v0.5
• 🧭 Architecture Narrative: framework/architecture.md
• 🏗️ Implementation Plans: framework/node/docs/tdr/
• ⚙️ Framework Guide: framework/node/README.md
• 🧾 Use Cases & Capability Map: ACM Usecases and Capabilities.md
• 📄 Whitepaper: WHITEPAPER.md
• 🧪 Testing Strategy: framework/node/TESTING.md
• 🚀 Getting Started: framework/node/GETTING_STARTED.md

---

Monorepo at a Glance

acm/
├── README.md                 # This document
├── LICENSE                   # MIT license for the project
├── spec/                     # ACM specifications and rationale
├── framework/
│   ├── architecture.md       # Cross-language architecture blueprint
│   ├── node/                 # Node.js reference implementation (pnpm workspace)
│   └── java/, python/        # Language ports (under active development)
└── WHITEPAPER.md             # Strategic positioning and vision

---

Package Matrix

Package	Description	Status
@ddse/acm-sdk	Base contracts, registries, policy/verification interfaces, ledger types, Nucleus with context tools and token budget.	✅ Stable @ v0.5.1
@ddse/acm-runtime	Deterministic runtime, checkpointing, resumable execution, guard evaluation, task scope filtering.	✅ Stable @ v0.5.1
@ddse/acm-planner	Structured LLM planner with plan alternatives, prompt hashing, tool envelopes.	✅ Stable @ v0.5.1
@ddse/acm-framework	High-level façade combining planner + runtime + nucleus wiring.	✅ Stable @ v0.5.1
@ddse/acm-llm	OpenAI-compatible clients for Ollama, vLLM, and custom providers.	✅ Stable @ v0.5.1
@ddse/acm-adapters	LangGraph/MSAF adapters preserving ACM contracts.	✅ Stable @ v0.5.1
@ddse/acm-mcp	Model Context Protocol tooling and registries.	✅ Stable @ v0.5.1
@ddse/acm-replay	Replay bundle export/import, ledger validation utilities.	✅ Stable @ v0.5.1
@ddse/acm-examples	CLI demos, refund/issue flows, replay bundle samples.	✅ Stable @ v0.5.1
@ddse/acm-aicoder	Developer assistant with streaming TUI and budgeting.	✅ Stable @ v0.5.1

Language Ports: Python and Java bindings follow the same specification and architecture; see framework/python/ and framework/java/ for progress trackers.

---

Quick Start

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 8
• Optional: Ollama or vLLM for local LLM experiments

Install & Build

git clone https://github.com/ddse-foundation/acm.git
cd acm/framework/node
pnpm install
pnpm build

Run Reference Demo

# Refund workflow demo with vLLM (tested with Qwen)
pnpm --filter @ddse/acm-examples demo -- --provider vllm --model Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 --base-url http://localhost:8001/v1 --goal refund

# Export a replay bundle while running the issue-resolution flow
pnpm --filter @ddse/acm-examples demo -- --goal issues --save-bundle --checkpoint-dir ./checkpoints

Launch the AI Coder Experience

pnpm --filter @ddse/acm-aicoder demo \
  --provider vllm \
  --model Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 \
  --base-url http://localhost:8001/v1 \
  --workspace $PWD/../../

Build Your First Plan Programmatically

import { ACMFramework, ExecutionEngine } from '@ddse/acm-framework';
import { SimpleCapabilityRegistry, SimpleToolRegistry } from '@ddse/acm-examples/registries';
import { createVLLMClient } from '@ddse/acm-llm';
import { MemoryLedger } from '@ddse/acm-runtime';

const registry = new SimpleCapabilityRegistry();
const tools = new SimpleToolRegistry();
const llm = createVLLMClient('Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8', 'http://localhost:8001/v1');

const framework = ACMFramework.create({
  capabilityRegistry: registry,
  toolRegistry: tools,
  nucleus: {
    call: llm.generateWithTools!,
    llmConfig: {
      provider: llm.name(),
      model: 'Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8',
      temperature: 0.1,
      baseUrl: 'http://localhost:8001/v1',
    },
    allowedTools: tools.listNames(),
  },
  planner: { planCount: 2 },
  execution: { engine: ExecutionEngine.ACM, checkpointInterval: 1 },
});

const ledger = new MemoryLedger();
const run = await framework.execute({
  goal: 'Resolve a priority refund ticket for order 1234.',
  context: { facts: { orderId: '1234', severity: 'P1' } },
  ledger,
});

console.log(run.plan.id);
console.log(run.execution.outputsByTask);

---

Plan → Execute → Replay Flow

1. Normalize Goal & Context — IDs, provenance, and scope metadata are enforced before planning.
2. Structured Planning — @ddse/acm-planner generates multiple plan candidates with rationale, tool envelopes, and prompt hashes recorded in the ledger.
3. Policy-Aware Execution — @ddse/acm-runtime executes the selected plan, evaluates guards, invokes policy and verification hooks, and checkpoints progress.
4. Ledger & Replay — Every planner and runtime decision streams into the MemoryLedger, enabling replay bundle export via @ddse/acm-replay for audits, testing, or regression harnesses.
5. Adapters & Integrations — Optional hooks route execution through LangGraph/MSAF engines or hydrate context via MCP tools without breaking ACM contracts.

---

Architecture Overview

• Three-Layer Intent: Planner (reasoning), Framework (coordination), Runtime (deterministic execution) — see framework/architecture.md.
• Nucleus Gateway: Centralized LLM governance with prompt hashing, deterministic tool allow-lists, built-in context tools (query_context, request_context_retrieval), anti-hallucination grounding, token budget enforcement, and streaming support.
• External Context Provider Adapter: Bridges nucleus context directives (request_context_retrieval) to developer-owned retrieval tools, with inline fulfillment during the tool loop.
• Decision Memory: Append-only ledger + checkpoints produce tamper-evident replay bundles for compliance and analytics.
• Interoperability: Adapters maintain parity with popular agent ecosystems while preserving ACM guarantees.

Refer to the sequence diagrams in framework/architecture.md for deep dives.

---

Governance & Compliance

• Policy Engine Hooks — Connect Open Policy Agent (OPA/Rego) or custom evaluators via PolicyEngine interfaces.
• Verification Grammar — Enforce acceptance criteria separate from task logic through VerificationEngine adapters.
• Tool & Capability Certification — Registry-driven capability maps ensure planners only target approved execution paths.
• Replay Bundles — Capture planner outputs, runtime telemetry, policies, and checkpoints in one exportable artifact.
• Audit Trails — Ledger entries include plan IDs, guard outcomes, retries, verification results, and tool-call digests.

Runbook for resumable execution lives in framework/node/docs/tdr/RUNBOOK_RESUMABLE.md.

---

Roadmap

• ✅ v0.5.1 (Current) — Nucleus context intelligence, token budget enforcement, anti-hallucination grounding, task scope filtering, two-stage planner.
• ✅ v0.5.0 — Contract-complete Node implementation, resumable runtime, replay bundles, MCP integration, AI Coder experience.
• 🚧 Python Port — Tracking in framework/python/ with parity milestones.
• 🚧 Java Port — Tracking in framework/java/ aligned to the same spec artifacts.
• 🧭 Future — Unified CLI (@ddse/acm-cli), extended verification grammars, hosted replay dashboards.

Detailed plans live in:

• Phase 1–4 Implementation Plans
• TDR: Resumable Executor

---

Contributing

We welcome contributions across contracts, runtime, adapters, and language ports.

• Read the Contribution Guide for branching, coding standards, and CI tasks.
• Explore framework/node/TESTING.md to understand per-package test surfaces.
• Bug reports and feature ideas belong in GitHub Issues.

Before submitting a PR, run pnpm build from framework/node/ to ensure cross-package builds succeed.

---

Resources & Support

• 📂 Examples: framework/node/packages/acm-examples/
• 🧑‍💻 AI Coder Docs: framework/node/packages/acm-aicoder/docs/
• 🔌 Adapters: framework/node/packages/acm-adapters/
• 🧠 LLM Gateway: framework/node/packages/acm-llm/
• 📝 Change Log: framework/node/CHANGELOG.md
• 🙋 Questions? Open a discussion or ping the maintainers via GitHub Issues.

---

License

This project is licensed under the MIT License.

---

Author: Mahmudur R. Manna — Founder & Principal Architect, DDSE Foundation (Dhaka, Bangladesh)