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.

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.	`@ddse/acm-sdk`
Structured Planning	Multi-plan generation with rationale, prompt digests, tool-call envelopes, and deterministic selectors.	`@ddse/acm-planner`
Deterministic Runtime	Guard evaluation, policy gates, retries/backoff, checkpointing, streaming sinks, and ledger emission.	`@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.	✅ Stable @ v0.5.0
`@ddse/acm-runtime`	Deterministic runtime, checkpointing, resumable execution, guard evaluation.	✅ Stable @ v0.5.0
`@ddse/acm-planner`	Structured LLM planner with plan alternatives, prompt hashing, tool envelopes.	✅ Stable @ v0.5.0
`@ddse/acm-framework`	High-level façade combining planner + runtime + nucleus wiring.	✅ Stable @ v0.5.0
`@ddse/acm-llm`	OpenAI-compatible clients for Ollama, vLLM, and custom providers.	✅ Stable @ v0.5.0
`@ddse/acm-adapters`	LangGraph/MSAF adapters preserving ACM contracts.	✅ Stable @ v0.5.0
`@ddse/acm-mcp`	Model Context Protocol tooling and registries.	✅ Stable @ v0.5.0
`@ddse/acm-replay`	Replay bundle export/import, ledger validation utilities.	✅ Stable @ v0.5.0
`@ddse/acm-examples`	CLI demos, refund/issue flows, replay bundle samples.	✅ Stable @ v0.5.0
`@ddse/acm-aicoder`	Developer assistant with streaming TUI and budgeting.	✅ Stable @ v0.5.0

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

Normalize Goal & Context — IDs, provenance, and scope metadata are enforced before planning.
Structured Planning — @ddse/acm-planner generates multiple plan candidates with rationale, tool envelopes, and prompt hashes recorded in the ledger.
Policy-Aware Execution — @ddse/acm-runtime executes the selected plan, evaluates guards, invokes policy and verification hooks, and checkpoints progress.
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.
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, and streaming support.
External Context Provider Adapter: Bridges nucleus context directives (request_context_retrieval) to developer-owned retrieval tools.
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.0 (Current) — 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:

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)

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.github/workflows		.github/workflows
docs/site		docs/site
framework		framework
spec		spec
.gitignore		.gitignore
LICENSE		LICENSE
PRESS_RELEASE_v0.5.0.md		PRESS_RELEASE_v0.5.0.md
README.md		README.md
RELEASE_NOTES_v0.5.0.md		RELEASE_NOTES_v0.5.0.md
WHITEPAPER-Usecases.md		WHITEPAPER-Usecases.md
WHITEPAPER.md		WHITEPAPER.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

ACM Framework

Table of Contents

Why ACM?

Feature Highlights

Documentation Index

Monorepo at a Glance

Package Matrix

Quick Start

Prerequisites

Install & Build

Run Reference Demo

Launch the AI Coder Experience

Build Your First Plan Programmatically

Plan → Execute → Replay Flow

Architecture Overview

Governance & Compliance

Roadmap

Contributing

Resources & Support

License

About

Uh oh!

Releases 1

Packages

Contributors 2

Languages

License

ddse-foundation/acm

Folders and files

Latest commit

History

Repository files navigation

ACM Framework

Table of Contents

Why ACM?

Feature Highlights

Documentation Index

Monorepo at a Glance

Package Matrix

Quick Start

Prerequisites

Install & Build

Run Reference Demo

Launch the AI Coder Experience

Build Your First Plan Programmatically

Plan → Execute → Replay Flow

Architecture Overview

Governance & Compliance

Roadmap

Contributing

Resources & Support

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Languages

Packages