Averos

A deterministic platform for building and evolving applications from structured intent

<br/> <p align="center"> <img width="400" height="350" src="https://www.wiforge.com/assets/logo/averos.svg"> <br/> <img src="https://img.shields.io/badge/Averos-v2.0.0-blue?logo=data:image/svg+xml;base64,PHN2ZyBpZD0iYXZlcm9zIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1NTggNDg2Ij4gIDxkZWZzPiAgICA8c3R5bGU+ICAgICAgLmNscy0xIHsgICAgICAgIG9wYWNpdHk6IDAuODsgICAgICB9ICAgICAgLmNscy0yIHsgICAgICAgIGZpbGw6ICNmY2RmMTI7ICAgICAgfSAgICAgIC5jbHMtMyB7ICAgICAgICBvcGFjaXR5OiAwLjU7ICAgICAgfSAgICAgIC5jbHMtNCB7ICAgICAgICBmaWxsOiAjOTZjMzMxOyAgICAgIH0gICAgICAuY2xzLTUgeyAgICAgICAgb3BhY2l0eTogMC44NTsgICAgICB9ICAgICAgLmNscy02IHsgICAgICAgIGZpbGw6ICMzZDhkZDg7ICAgICAgfSAgICAgIC5jbHMtNyB7ICAgICAgICBvcGFjaXR5OiAwLjk1OyAgICAgIH0gICAgICAuY2xzLTggeyAgICAgICAgZmlsbDogI2U4MzgyYTsgICAgICB9ICAgICAgLmNscy05IHsgICAgICAgIGZpbGw6Izk0NjQ4NDsgICAgICB9ICAgICAgLmNscy0xMCB7ICAgICAgICBmaWxsOiAjZjI4YzFlOyAgICAgIH0gICAgICAuY2xzLTExIHsgICAgICAgIGZpbGw6ICM5NDU2NzE7ICAgICAgfSAgICAgIC5jbHMtMTIgeyAgICAgICAgb3BhY2l0eTogMC45OyAgICAgIH0gICAgIC5jbHMtMTMgeyAgICAgICAgb3BhY2l0eTogMC44ODsgICAgICB9ICAgICAgLmNscy0xNCB7ICAgICAgICBmaWxsOiAjMmZhNjRmOyAgICAgIH0gICAgPC9zdHlsZT4gIDwvZGVmcz4gIDxnIGNsYXNzPSJjbHMtMSI+ICAgIDxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTI4MS4yNCw5Ny40NmwxODAsMzEwLjhjMTAuMzYtNy44MywyMi40OS0xMS41MywzMS4xNS0xOC4wNkwzMTIuMjQsNzkuNDlDMzAwLjY5LDg0LjEzLDI5MS42Niw5MS44NiwyODEuMjQsOTcuNDZaIi8+ICA8L2c+ICA8ZyBjbGFzcz0iY2xzLTMiPiAgICA8Y2lyY2xlIGNsYXNzPSJjbHMtNCIgY3g9IjQ5NSIgY3k9IjQyMiIgcj0iNjMiLz4gIDwvZz4gIDxnIGNsYXNzPSJjbHMtNSI+ICAgIDxwYXRoIGNsYXNzPSJjbHMtNiIgZD0iTTEyMC4yNSwyMjcuMjdsMjk0LjExLTUwLjhhMTcuNTUsMTcuNTUsMCwwLDAsMTQtMjAuNmMwLS4xNC0uMDUtLjI3LS4wNy0uNDEtMS43NC05LjU2LTEwLjc1LTE2LjA3LTIwLjA3LTE0LjQ2TDExMy44NywxOTJhMTYuOTIsMTYuOTIsMCwwLDAtNS4xMiwxLjc3Yy0yOS40NywxNS44My0yOC44NCwyNy4xNyw1LjU4LDMzLjQ2QTE2LjgyLDE2LjgyLDAsMCwwLDEyMC4yNSwyMjcuMjdaIi8+ICA8L2c+ICA8ZyBjbGFzcz0iY2xzLTciPiAgICA8cGF0aCBjbGFzcz0iY2xzLTgiIGQ9Ik0yNzguOTEsOTUuNDQsOTEuMyw0MDUuNzhjLTExLjM4LTcuNi0yMi4xNS0xMy4yNy0zMC44LTE4LjY0TDI0OC4yNSw3Ni44OUMyNTQuMDYsODEuNjUsMjY1LjExLDg3LjU5LDI3OC45MSw5NS40NFoiLz4gIDwvZz4gIDxnIGNsYXNzPSJjbHMtMyI+ICAgIDxjaXJjbGUgY2xhc3M9ImNscy05IiBjeD0iNjMiIGN5PSI0MjMiIHI9IjYzIi8+ICA8L2c+ICA8ZyBjbGFzcz0iY2xzLTMiPiAgICA8Y2lyY2xlIGNsYXNzPSJjbHMtMTAiIGN4PSIyNzkiIGN5PSI2MyIgcj0iNjMiLz4gIDwvZz4gIDxjaXJjbGUgY2xhc3M9ImNscy0xMCIgY3g9IjI3OSIgY3k9IjY0IiByPSIzOSIvPiAgPGNpcmNsZSBjbGFzcz0iY2xzLTExIiBjeD0iNjMiIGN5PSI0MjQiIHI9IjM5Ii8+ICA8ZyBjbGFzcz0iY2xzLTEyIj4gICAgPGNpcmNsZSBjbGFzcz0iY2xzLTQiIGN4PSI0OTUiIGN5PSI0MjIiIHI9IjM5Ii8+ICA8L2c+ICA8ZyBjbGFzcz0iY2xzLTEzIj4gICAgPHBhdGggY2xhc3M9ImNscy0xNCIgZD0iTTQxOS41MywyMDEuMzcsMTE2Ljc5LDI1MS43YTE3Ljc5LDE3Ljc5LDAsMCwwLTE0LjYxLDIwLjU5YzAsLjE0LDAsLjI3LjA3LjQxYTE3Ljg4LDE3Ljg4LDAsMCwwLDIwLjQ2LDE0LjVsMzAzLTUwLjUzYTE4LjI1LDE4LjI1LDAsMCwwLDUuMjgtMS43NmMzMC40NS0xNS44LDI5LjkzLTI3LjE0LTUuMzYtMzMuNTFBMTcuNzMsMTcuNzMsMCwwLDAsNDE5LjUzLDIwMS4zN1oiLz4gIDwvZz48L3N2Zz4="> <img src="https://img.shields.io/badge/MCP-orange?logo=modelcontextprotocol&logoColor=f5f5f5"> <img src="https://img.shields.io/badge/npm-gray?logo=nodedotjs"> <img src="https://img.shields.io/badge/pnpm-green?logo=pnpm&logoColor=f5f5f5"> <img src="https://img.shields.io/badge/nx-yellow?logo=nx"> <img src="https://img.shields.io/badge/Typescript-blue?logo=typescript&logoColor=f5f5f5"> <img src="https://img.shields.io/badge/Angular-red?logo=angular"> <img src="https://img.shields.io/badge/Jest-darkgreen?logo=jest"> <img src="https://img.shields.io/badge/Vitest-white?logo=vitest"> <img src="https://img.shields.io/badge/Ollama-darkblue?logo=ollama"> <img src="https://img.shields.io/badge/Claude Desktop-gray?logo=claude"> <img src="https://img.shields.io/badge/Git-darkgray?logo=git"> <h4 align="center"> ❝ The AI decides <i>what</i> should exist. </h4> <h4 align="center"> The engine decides <i>how</i> it gets built. ❞</h4> </p> <br/> <br/>

---

What is Averos ?

Averos is a deterministic execution and evolution layer between AI intent and production software.

It turns structured intent into reviewable, reproducible code — providing a controlled path from what AI decides should exist to software that can actually be built, inspected, evolved, and maintained.

Unlike AI coding assistants that generate source code directly, Averos generates and evolves a structured application model — making software construction reproducible, explainable, and incremental

---

📖 Introduction

Modern AI coding assistants generate code.

Averos generates software systems. It is designed specifically for long-lived business applications that evolve safely over time.

Instead of treating code as the source of truth, Instead of asking an LLM to produce thousands of lines of source code, Averos treats a structured application model as the source of truth.

AI produces the application model.

The deterministic Averos engine produces the application.

The result is software that is reproducible, explainable, and evolves safely through conversation.

Works with:

| Provider | Type | |---|---| | Claude Desktop | MCP client | | Any MCP-compatible client | MCP | | Anthropic API | Cloud LLM | | Google Gemini | Cloud LLM | | OpenAI | Cloud LLM | | Ollama | Local LLM | | LM Studio / LocalAI / vLLM | Local LLM |

🚀 Try It Out

Assuming an application manifest has already been created (either using AI or averos designer).

npm install -g @averos/cli

1- Copy the ToDo application manifest to your working folder: todoapp-manifest.json

2- In your working folder, create the following file averos.config.json with the content below:

{
  "mode":           "resilient",
  "timeoutMs":      1800000,
  "maxAttempts":    1,
  "workspaceRoot":  "./generated-app",
  "manifestPath":   "../todoapp-manifest.json",
  "logsDir":        "./generated-app/averos-logs",
  "statePath":      "./generated-app/state.json",
  "checkpointPath": "./generated-app/checkpoints.json"
}

3- Verify the Plan:

averos plan --config=averos.config.json

4- Generate the application:

Use --verbose for detailed tracing.

averos run --config=averos.config.json --verbose

This application has 320 nodes so the generation time may exceed the configured timeout (30 minutes) depending on your machine configuration.

Upon timeout failure (timeout = 30 minutes), re-execute the command with --resume to resume from last checkpoint :

averos run --config=averos.config.json --verbose --resume

5- Explore your application:

Navigate to your application folder then build and serve:

cd generated-app/ToDoApp
npx ng serve 

Open your browser and navigate to : http://localhost:4200

Use admin/admin123 to log into your application (Dummy Auth)

---

💡 Why Averos?

Most "AI coding" today works like this: you describe what you want, the model writes code, and if you want a change, you describe it again and hope the model doesn't quietly rewrite something you didn't ask it to touch. The prompt is the source of truth — which means there is no source of truth. The prompt is the source of truth — which means there is no durable, structured source of truth. Changes are difficult to reason about before execution, reproducibility is difficult to guarantee, and every revision risks becoming another round of code generation.

Averos exists to fix that. It inserts a deterministic execution and evolution layer between AI intent and your running codebase — a structured, validated intermediate representation (the manifest) that the AI produces and everything downstream is built from. The AI still decides what should exist. Averos decides how it gets built — and that half of the process is no longer a guess.

AI provides intelligence. Averos provides control.

---

The fundamental difference

Most AI coding tools generate source code directly.

That approach is fast, but often produces:

• inconsistent architectures
• non-reproducible outputs
• difficult maintenance
• vendor lock-in
• unpredictable behavior

Averos takes a different approach.

Instead of generating source code directly, Averos generates and manages a structured Application Manifest (IR — Intermediate Representation) that describes an application in a deterministic format.

The manifest is then:

1. Validated
2. Normalized
3. Converted into an execution plan
4. Executed through a deterministic DAG engine

The result is a system that combines Natural Language, AI Assistance, and Deterministic Engineering into a single workflow.

Conventional AI coding asks:

"What code should I generate?"

Prompt
  ↓
AI
  ↓
Code
  ↓
Application

Averos asks:

"What software state should exist, and what deterministic operations are required to get there?"

Intent
  ↓
AI
  ↓
Application Manifest
  ↓
Validation
  ↓
Semantic Diff
  ↓
Execution Plan
  ↓
Deterministic Engine
  ↓
Application

The AI is responsible for understanding intent and producing a structured representation.

The Averos engine is responsible for validating that representation, determining what changed, resolving dependencies, producing an execution plan, and applying the required transformations.

Why this matters

| Challenge | Conventional AI Coding | Averos | |---|---|---| | Source of truth | Prompts and generated code | Structured application manifest | | Architecture | Implicit in generated code | Explicit in the application model | | Planning | Left to the AI agent | Explicit, dependency-aware execution plan | | Determinism | Model-dependent | Deterministic execution engine | | Validation | Agent- or tool-dependent | Structured manifest validation (structural, referential, constraint) | | Change detection | File- or code-level diffing | Semantic manifest diff | | Incremental evolution | Regenerate or manually edit | Apply only the required operations | | Dependencies | Inferred during generation | Explicitly modeled and planned | | Execution | Agent-driven side effects | Controlled execution through adapters | | Failure handling | Agent- or tool-dependent | Checkpoints, state, resumable execution | | Rollback / revisions | Usually external to the AI workflow | First-class application revisions | | Explainability | Inspect the generated code | Inspect manifest → validation → diff → plan → execution | | AI independence | Often coupled to a specific agent or model | LLM-agnostic architecture | | MCP / agent integration | Agent- or tool-dependent | Native, governed AI interaction layer | | Reproducibility | Difficult to guarantee | Core architectural objective |

Three architectural principles make this possible:

• The manifest is the contract, not the transcript. Because the AI's job ends at producing a validated manifest — not at writing code — the deterministic Averos engine can reproduce the same execution plan from the same defined state and engine configuration. You can hand the same manifest to Averos twice and get the same output twice. That's not true of prompt-to-code generation, no matter how good the model is.

• Evolution is a diff, not a do-over. Change one field on one entity, and Averos recomputes only the affected nodes in the dependency graph and touches only what actually changed. In direct AI coding workflows, a requested change often becomes another round of code generation or agent-driven editing. Averos treats the application as a living graph rather than a disposable generation.

• AI agents get a governed environment, not open access. Through @averos/mcp, an AI agent doesn't get raw file or shell access to your project — it gets a bounded set of tools (update_ir, validate_ir, build_execution_plan,