averos

KO | EN

gitlite — search

#data-science #proxy #ai #go #generative-ai #java #computer-vision #postgresql #agent #claude-code

(★ 9)

Deterministic execution & evolution layer between AI intent and production software — turning structured intent into reviewable, reproducible code. 🔥

File Explorer

ZIP Download

- - bug_report.md
  - config.yml
  - feature_request.md
- PULL_REQUEST_TEMPLATE.md
- config.yml
- extensions.json
- launch.json
- settings.json
- - angular.json
  - eslint.config.mjs
  - ngsw-config.json
  - package.json
  - project.json
  - tsconfig.app.dev.json
  - tsconfig.app.json
  - tsconfig.json
  - tsconfig.spec.json
- - eslint.config.mjs
  - package.json
  - playwright.config.ts
  - project.json
  - tsconfig.json
- - .spec.swcrc
  - eslint.config.mjs
  - jest.config.cts
  - package.json
  - project.json
  - README.md
  - tsconfig.json
  - tsconfig.lib.json
  - tsconfig.spec.json
- - .spec.swcrc
  - eslint.config.mjs
  - jest.config.cts
  - package.json
  - project.json
  - README.md
  - tsconfig.json
  - tsconfig.lib.json
  - tsconfig.spec.json
- - .spec.swcrc
  - eslint.config.mjs
  - jest.config.cts
  - package.json
  - project.json
  - README.md
  - tsconfig.json
  - tsconfig.lib.json
  - tsconfig.spec.json
- - eslint.config.mjs
  - ng-package.json
  - package.json
  - project.json
  - README.md
  - tsconfig.json
  - tsconfig.lib.json
  - tsconfig.lib.prod.json
  - tsconfig.spec.json
- - eslint.config.mjs
  - package.json
  - project.json
  - README.md
  - tsconfig.json
  - tsconfig.lib.dev.json
  - tsconfig.lib.json
  - tsconfig.spec.json
  - vitest.config.mts
- .gitkeep
- - README.md
  - run-local-angular.sh
  - run-real-angular.sh
  - run-real-angular.ts
  - tsconfig.json
  - wiforge-averos-2.0.0.tgz
- - todoapp-manifest.json
- - integration-test-ai.sh
  - integration-test-ai.ts
  - integration-test-executor.sh
  - integration-test-executor.ts
  - README.md
  - tsconfig.json
- - golden-reference-plan.sh
  - golden-reference-run.sh
  - minimal-plan.sh
  - minimal-run.sh
  - README.md
  - tsconfig.json
- project.json
- README.md
- tsconfig.json
.gitignore
.npmrc
.prettierignore
.prettierrc
CLA.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
eslint.config.mjs
jest.config.ts
jest.preset.js
LICENSE
nx.json
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.base.json
tsconfig.json
vitest.workspace.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

#### _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>

---

## 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).

```bash
npm install -g @averos/cli
```
1- Copy the `ToDo` application manifest to your working folder: [todoapp-manifest.json](/scripts/golden-reference/todoapp-manifest.json)

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

```json
{
  "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:

```bash
averos plan --config=averos.config.json
```

4- Generate the application:

Use `--verbose` for detailed tracing.

```bash
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 :

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

5- Explore your application:

Navigate to your application folder then build and serve:

```bash
cd generated-app/ToDoApp
npx ng serve 
```

Open your browser and navigate to : [http://localhost:4200](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?"**

```text
Prompt
  ↓
AI
  ↓
Code
  ↓
Application
```

**Averos** asks:

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

```text
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`, `approve_plan`) that force every change through validation and an approval gate before anything is written. **The agent proposes. The engine plan. You control execution.**

Averos is built on an adapter pattern, so this deterministic core isn't tied to one framework by design — Angular schematics is the first production adapter, demonstrating the pipeline end to end, with the same execution model designed to extend to other stacks over time.

**Built for software evolution:**

Software is not generated once. It is continuously changed.

Averos is designed around **software evolution**, not just initial generation.

For example:

```text
Initial application
        ↓
"Add priority to tasks"
        ↓
Manifest revision
        ↓
Semantic diff
        ↓
1 required operation
        ↓
Deterministic execution
        ↓
Updated application
```

The application is not regenerated from scratch.
Its desired state changes, the difference is calculated, and only the necessary operations are executed.

This enables a software development model based on:

- **Reproducibility** — the same defined state can produce the same planned result.
- **Explainability** — every transformation can be inspected before execution.
- **Incremental evolution** — applications change through explicit revisions rather than uncontrolled regeneration.
- **Control** — AI proposes intent; the deterministic engine controls execution.
- **Recoverability** — execution state and checkpoints support failure recovery and resumption.
- **Extensibility** — execution is separated from the core engine through adapters.
- **AI independence** — the deterministic core does not depend on a particular LLM.

### In one sentence

> **Averos is the deterministic execution and evolution layer between AI intent and production software.**

---

## 📜 Why a Manifest?

Because source code is difficult for AI to evolve safely.

### Traditional AI

```
Prompt → Source Code → Manual fixes → Regenerate → Lose edits
```

### Averos

```
Prompt → Application Manifest → Validation → Execution Plan → Generated Application
                                                                        ↓
                                                             Incremental evolution
```

A manifest is:

| Property | Description |
|---|---|
| ✅ Deterministic | Same manifest always produces the same output |
| ✅ Versionable | Every revision is stored and retrievable |
| ✅ Diffable | Changes are computed precisely — only deltas execute |
| ✅ Reviewable | Every planned operation is inspectable before execution |
| ✅ Rollbackable | Any revision can be restored instantly |
| ✅ Executable | The manifest is the direct input to the execution engine |

The generated source code becomes a product of the manifest—not the other way around.

---

## 👥 Who is Averos for?

| Audience | Use case |
|---|---|
| Enterprise software teams | Repeatable, governed application generation |
| Internal tooling | Rapid generation from structured specs |
| CRUD business applications | Full stack from a single manifest |
| Low-code / no-code platforms | AI-driven form and workflow generation |
| AI agents | Structured tool-based application construction |
| CI/CD pipelines | Deterministic generation in automated pipelines |

## 🚀 Quick Start

### 1. Install the CLI
```bash
npm install -g @averos/cli
```

### 2. Generate a manifest (two options)

Now there are two ways for generating application manifest:

🟦 Generate application manifest using AI
<br/>
🟦 Generate application manifest using the [**Online Averos Designer** 🛠️](https://appbuilder.wiforge.com/averos-designer/averosdesigner)

**Option A — AI-generated manifest:**

```bash
npm install -g @averos/ai

averos generate "Build a CRM with contacts and deals" \
  --output=/tmp/crm-manifest.json
```

Using Ollama (local LLM, `averos.config.ollama.json`):

**Averos Config - `averos.config.ollama.json`**

```json
{
 "timeoutMs":      600000,
 "llmTimeoutMs":   600000,
 "llmProvider":   "ollama",
 "ollamaBaseUrl": "http://192.168.136.1:11434",
 "ollamaModel":   "qwen2.5-coder:7b",
 "maxAttempts":    5
}
```

```bash
averos generate "Build a CRM" \
    --output=/tmp/averos-application-manifest.json \
    --config=/averos.config.ollama.json
```

**Option B — Online Averos Designer:**

Use the [**Averos Designer** 🛠️](https://appbuilder.wiforge.com/averos-designer/averosdesigner)
to visually build your application manifest.

### 3. Preview the execution plan

```bash
averos plan /tmp/crm-manifest.json --workspace=/tmp/crm-app
```

### 4. Execute

```bash
# Dry-run — no side effects
averos run /tmp/crm-manifest.json --workspace=/tmp/crm-app --dry-run

# Real execution
averos run /tmp/crm-manifest.json --workspace=/tmp/crm-app
```

Using a config file (`averos.config.json`):

**Averos Config: `averos.config.json`**

```json

{
  "mode":           "resilient",
  "timeoutMs":      120000,
  "maxAttempts":    1,
  "workspaceRoot":  "/tmp/averos-applications/",
  "manifestPath":   "/tmp/averos-application-manifest.json",
  "statePath":      "/tmp/averos-applications/state.json",
  "checkpointPath": "/tmp/checkpoints.json",
  "logsDir":        "/tmp/averos-applications/averos-logs"
}
```

```bash
# Dry-run via config file
averos run --config=averos.config.json --dry-run
```

```bash
# Execute the application manifest via config file
averos run --config=averos.config.json
```

The application is generated at `workspaceRoot`.

---

## ⚙️ Averos DAG Engine

A deterministic, compiler-style pipeline for generating averos applications from structured JSON manifests — with LLM-assisted design, validation, dependency-ordered execution, and full resumability.

---

### Four-Layer Pipeline

```
┌─────────────────────────────────────────────────────┐
│  LAYER 1 — INTENT                                   │
│  LLM or designer produces a JSON manifest           │
│  (natural language → structured application model)  │
└────────────────────┬────────────────────────────────┘
                     │ Manifest (JSON IR)
                     ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 2 — VALIDATION                               │
│  Schema compliance · referential integrity          │
│  Constraint checking · naming rules                 │
└────────────────────┬────────────────────────────────┘
                     │ Validated Manifest
                     ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 3 — ORCHESTRATION                            │
│  Diff against current state · DAG construction      │
│  Topological sort · Execution plan                  │
└────────────────────┬────────────────────────────────┘
                     │ Approved Execution Plan
                     ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 4 — EXECUTION                                │
│  Execution Adapter · Checkpointing · State sync     │
│  Resumable · Idempotent · Dry-run safe              │
└─────────────────────────────────────────────────────┘
```

The LLM is powerful but unreliable. 
The execution engine is reliable but dumb. 
The validation and orchestration layers safely connect the two.

### Core Idea

**Traditional AI workflow:**

```
Prompt → LLM → Source Code
```

**Averos:**

```
Prompt → AI → Application Manifest (IR)
                              ↓
                  Deterministic DAG Execution
                              ↓
                  Generated Application
```

The AI decides *what* should exist.

The engine decides *how* it gets built.

---

### Example

User:

```text
Build a task management application with:
- ToDo items
- Subtasks
- Priorities
- Authentication
```

AI generates a manifest. Averos then:

```
Validate Manifest → Normalize → Build Execution Plan → Execute DAG → Generated Application
```

The same manifest always produces the same result.

---

## 📐 Design Principles

**The Application Manifest is the source of truth — not source code, not prompts.**

| Principle | Description |
|---|---|
| **Deterministic** | Same manifest always produces the same application |
| **Explainable** | Every step — manifest, validation, plan, execution — is inspectable |
| **Incremental** | Only changed nodes are re-executed; existing work is preserved |
| **Resumable** | Interrupted executions resume from the last checkpoint |
| **Idempotent** | Running the same manifest twice produces no duplicate artifacts |
| **AI-Friendly** | Designed for LLM-driven workflows and MCP tool interfaces |
| **Adapter-Agnostic** | The engine is decoupled from any specific generation target |

---

## 📦 Public Packages

### @averos/cli

Command-line interface for Averos.

```bash
npm install -g @averos/cli

```

**Useful for:**

* CI/CD
* Local development
* Testing
* Automation

**Usage:**

```bash
# Run averos
$> averos

Averos CLI v2.0.0

Usage:
  averos run   [<manifest>] [options]
  averos plan  [<manifest>] [options]
  averos status             [options]
  averos generate "<intent>" [options]

Commands:
  run       Execute a manifest against a workspace (real or dry-run)
  plan      Preview the execution plan without running anything
  status    Show the last build state for a workspace
  generate  Generate a manifest from natural language (requires @averos/ai)

Run options:
  --manifest=<path>          Manifest file path
  --mode=resilient|strict    Execution mode (default: resilient)
  --dry-run                  Preview commands without executing
  --resume                   Resume from last checkpoint on failure
  --timeout=<ms>             Per-session timeout in milliseconds
  --max-attempts=<n>         Retry attempts per node (default: 1)
  --tgz=<path>               Path to local @averos/workflow .tgz
                             (installs from npm registry when omitted)
  --development              development mode
  --averos-version=<semver>  Version string (required with --development)
  --logs-dir=<path>          Directory for per-node execution logs
                             (default: <workspace>/logs)

Plan options:
  --manifest=<path>          Manifest file path
  --json                     Output plan as JSON

Generate options:
  --run                      Execute the generated manifest immediately
  --output=<path>            Where to write the generated manifest
                             (default: averos-app.json)

Global options:
  --workspace=<path>         Workspace root (default: cwd)
  --config=<path>            Config file (default: averos.config.json)
  --verbose                  Debug output — all node names, paths, timings

Examples:

# Using a config file:
  averos run --config=/my/project/averos.config.json --dry-run

# Real run from npm registry:
  averos run app.json --workspace=/tmp/myapp

# Real run from local tgz:
  averos run app.json --workspace=/tmp/myapp \
    --tgz=./averos-lib-2.0.0.tgz \
    --averos-version=2.0.0

# Dry-run:
  averos run app.json --workspace=/tmp/myapp --dry-run

# Preview plan as JSON:
  averos plan app.json --workspace=/tmp/myapp --json

# Show last build status:
  averos status --workspace=/tmp/myapp

```

**Key :**

```bash
averos plan generated-manifest.json --workspace=/tmp/gen-test app.json
averos run --config=averos-app-config.json

```

**Commands:**

- `averos run`:      Execute a manifest against a workspace
- `averos plan`:     Preview the execution plan without running
- `averos status`:   Show the last build state for a workspace
- `averos generate`: Generate a manifest from natural language

**Key Examples:**

```bash
# Preview plan as JSON
averos plan app.json --workspace=/tmp/myapp --json

# Dry-run
averos run app.json --workspace=/tmp/myapp --dry-run

## Real run
averos run app.json --workspace=/tmp/myapp

# Run via config file
averos run --config=averos.config.json

# Show last build status
averos status --workspace=/tmp/myapp --verbose

# Generate manifest
averos generate "A CRM with contacts" --output=manifest.json
```

**Config file (`averos.config.json`):**

```json
{
  "workspaceRoot":  "/tmp/my-application",
  "manifestPath":   "/tmp/my-manifest.json",
  "mode":           "resilient",
  "timeoutMs":      600000,
  "maxAttempts":    1,
  "logsDir":        "/tmp/my-application/logs"
}
```

📙 See [packages/cli/README.md](packages/cli/README.md) for full reference

---

### @averos/mcp

Model Context Protocol server — exposes Averos as tools for Claude Desktop
and any MCP-compatible AI client.

```bash
npm install -g @averos/mcp
```

**Add to `claude_desktop_config.json`:**

```json
{
  "mcpServers": {
    "averos": {
      "command": "node",
      "args": ["/path/to/node_modules/@averos/mcp/dist/index.js"],
      "env": {
        "AVEROS_SESSION_DIR": "/home/user/.averos/sessions"
      }
    }
  }
}
```

**Available tools:**

| Tool | Purpose |
|---|---|
| `create_session` | Start a new design session |
| `update_ir` | Edit the manifest (JSON Patch RFC 6902) |
| `validate_ir` | Validate the manifest |
| `build_execution_plan` | Build and preview the execution plan |
| `approve_plan` | Approve or reject the plan |
| `execute_plan` | Execute the approved plan |
| `get_status` | Check session state |
| `list_revisions` | View manifest revision history |
| `rollback_revision` | Restore a previous manifest revision |
| `diff_ir` | Compare manifest versions semantically |

📙 See [packages/mcp/README.md](packages/mcp/README.md) for full reference

---

### @averos/ai

LLM conversation and manifest generation layer.

```bash
# Full install including LLM generation
npm install -g @averos/cli @averos/ai
```

**Provides:**

* Multi-turn conversations
* Manifest generation
* Manifest refinement
* Validation-aware retries
* LLM abstraction layer

**Supported providers:**

| Provider | Env variable | Default model |
|---|---|---|
| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
| Google Gemini | `GEMINI_API_KEY` | `gemini-2.0-flash` |
| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
| Ollama | — | `qwen2.5-coder:7b` |
| Local (LM Studio, vLLM...) | — | configurable |

**Config for local Ollama:**

```json
{
  "llmProvider":   "ollama",
  "ollamaBaseUrl": "http://localhost:11434",
  "ollamaModel":   "qwen2.5-coder:7b",
  "llmTimeoutMs":  600000
}
```

**Config for remote Ollama (LAN or VM host):**

```json
{
  "llmProvider":   "ollama",
  "ollamaBaseUrl": "http://192.168.1.50:11434",
  "ollamaModel":   "qwen2.5-coder:7b",
  "llmTimeoutMs":  600000
}
```

**Example conversation:**

```
User:   "Build a CRM with contacts and deals"
AI:     → Generates manifest

User:   "Add a priority field to deals"
AI:     → Updates manifest (surgical edit)

User:   "Add keycloak authentication"
AI:     → Updates manifest

User:   "Run it"
Averos: → Validates → Plans → Executes
```

**Generate and execute:**

```bash
# Generate manifest only
averos generate \
  "A project management app with Projects and Tasks. Tasks belong to Projects." \
  --output=/tmp/project-manifest.json \
  --workspace=/tmp/gen-run \

# Generate and dry-run
averos generate \
  "A project management app with Projects and Tasks. Tasks belong to Projects." \
  --output=/tmp/project-manifest.json \
  --workspace=/tmp/gen-run \
  --run \
  --dry-run

# Generate and execute
averos generate \
  "A project management app with Projects and Tasks. Tasks belong to Projects." \
  --output=/tmp/project-manifest.json \
  --workspace=/tmp/gen-run \
  --run 
  ```
📙 See [packages/ai/README.md](packages/ai/README.md) for full reference

---

### @averos/workflow

Workflow runtime and Angular Schematics adapter for the Averos execution platform.

Contains the complete library of Averos custom Angular schematics responsible for generating
and updating application artifacts throughout the software lifecycle.

📙 See [packages/workflow/README.md](packages/workflow/README.md) for full reference

---

### @averos/ui-platform

Reusable Angular UI components, layouts, themes and application building blocks designed to integrate seamlessly with Averos-generated applications.

Includes:

- Forms
- Tables
- Form validators
- Navigation
- Authentication
- Responsive layouts
- Services
- Configurations

📙 See [packages/ui-platform/README.md](packages/ui-platform/README.md) for full reference

---

## ⚙️ Averos Core (internal)

The platform is internally powered by two deterministic engines:

- Planning Engine
- Execution Runtime

These are internal implementation details that power
the public packages.

### Planning Engine

The deterministic application planning engine.

Responsible for:

- Manifest parsing and normalization
- Structural, referential, and constraint validation
- Dependency graph construction (DAG)
- Topological sorting with deterministic tie-breaking
- Execution plan generation

**Example:**

```
Manifest → Validator → Normalizer → DAG Builder → ExecutionPlan
```

---

### Execution Runtime

Executes execution plans generated by the DAG engine.

Responsible for:

- Dependency-ordered node scheduling
- Adapter invocation with mutable workspace state
- Per-node checkpointing for resumability
- State persistence for incremental execution
- Strict and resilient failure modes
- Dry-run support (zero side effects)

**Example:**

```
ExecutionPlan → Scheduler → Adapter → Checkpoint → State → Generated Output
```

---

## 🏗️ Platform Architecture

```text

┌──────────────────────────────────────────────────────┐
│                    Entry Points                      │
│                                                      │
│     @averos/cli           @averos/mcp                │
│     (command line)        (MCP server / Claude       │
│                          Desktop / AI agents)        │
└──────────────┬──────────────────┬────────────────────┘ 
			         │                  │
               ▼                  ▼
┌──────────────────────────────────────────────────────┐
│                   @averos/ai                         │
│         LLM Conversation + Manifest Generation       │
│   Anthropic · Gemini · OpenAI · Ollama · Local LLM   │
│													                             │
│				        AI Conversation Layer				           │
└──────────────────────────┬───────────────────────────┘
                           │  Application Manifest (JSON IR)
						               ▼
┌──────────────────────────────────────────────────────┐
│              Planning Engine (core / internal)       │
│                                                      │
│  Parse → Validate → Normalize → Diff → DAG → Plan    │
│													                             │
│				        Validation & Planning 				         │
└──────────────────────────┬───────────────────────────┘
                           │  Execution Plan
                           ▼
┌──────────────────────────────────────────────────────┐
│             Execution Runtime (core / internal)      │
│                                                      │
│  Schedule → Execute → Checkpoint → Persist State     │
│													                             │
│				        Deterministic Runtime				           │  
└──────────────────────────┬───────────────────────────┘
						               │
						               ▼
┌──────────────────────────────────────────────────────┐
│              ExecutionAdapter (pluggable)            │
│                                                      │
│  @averos/workflow  ·  Custom adapters                │
│													                             │
│				      Execution Runtime Adapter			           │
└──────────────────────────┬───────────────────────────┘
						               │
						               ▼
              ┌─────────────────────────┐
              │  Generated Application  │
              └─────────────────────────┘
```

---

## 🧮 Deterministic by Design

Averos intentionally separates intent from execution:

| Concern | Owner |
|---|---|
| Understanding user intent | LLM |
| Structural correctness | Validator |
| Execution ordering | DAG engine |
| Execution correctness | Execution runtime |
| Side effects | ExecutionAdapter |

This separation provides:

- **Reproducibility** — same manifest, same result, always
- **Auditability** — every operation is logged and inspectable
- **Versionability** — manifests are diffable, rollbackable artifacts
- **Safety** — nothing executes before validation passes
- **Incremental evolution** — only changed nodes are re-executed

---

## 🔄 Revision-Based Development

Every application evolves through revisions.

```
Revision 1 → Revision 2 → Revision 3 → ...
```

Changes are represented as structured manifest updates.

This enables:

- Diffing between any two revisions
- Instant rollback to any previous state
- Full audit trail of every change
- Human approval before execution

---

## 🤖 AI-Native Workflow

Averos is designed around conversations that evolve an application over time.

**Example:**

```
User:    "Build a task management app"
AI:      Creates manifest → validates → shows plan
User:    "Looks good, proceed"
Averos:  Executes plan → generates application

User:    "Add a priority field to tasks"
AI:      Updates manifest (one field added)
Averos:  Diffs → 1 operation needed → executes only that

User:    " Actually a task has several task items"
AI:      Updates manifest (create task item and add a relationship with task)
Averos:  Diffs → 2 operation needed → executes only that
```

---

## 🎯 Design Goals

| Goal | Description |
|---|---|
| **Deterministic** | Same manifest → same result, every time |
| **Explainable** | Manifest · Validation · Plan · Execution — Every step is visible |
| **Incremental** | Applications evolve through revisions, not regeneration |
| **AI-Friendly** | Designed specifically for modern LLM and MCP workflows |
| **Engine-First** | The deterministic engine is the source of truth, not the LLM |

---

## 🚦 Package Status

| Package | Status | Description |
|---|---|---|
| `@averos/cli` | ✅ Available | Command-line interface |
| `@averos/ai` | ✅ Available | LLM manifest generation |
| `@averos/mcp` | ✅ Available | MCP server for AI clients |
| `@averos/workflow` | ✅ Available | Angular schematics adapter |
| `@averos/ui-platform` | ✅ Available | Reusable Angular UI components |

---

## 🔭 Vision

We believe software engineering will evolve from writing code to designing systems.

Humans describe intent.
AI structures requirements.
Deterministic engines guarantee correctness.
Applications evolve through conversation.

The goal is not simply to generate code.

**The goal is to make software construction reproducible, explainable, and evolvable.**

---

## 📙 Documentation

Full documentation: [**wiforge.com**](https://www.wiforge.com)

Online Averos Designer: [**appbuilder.wiforge.com**](https://appbuilder.wiforge.com/averos-designer/averosdesigner)

---

## ⚖️ License

Released under the [MIT License](LICENSE).

---

<p align="center">
  Built with ❤️ by the <a href="https://github.com/wiforge">Wiforge</a> team ·
</p>

averos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README