Metadata-Version: 2.4
Name: anna-arch
Version: 1.3.0
Summary: ANNA — AI-Native Node Architecture. Manifest-driven navigation system for AI coding agents.
Project-URL: Homepage, https://github.com/NikolaiGL/ANNA
Project-URL: Repository, https://github.com/NikolaiGL/ANNA
Project-URL: Issues, https://github.com/NikolaiGL/ANNA/issues
Author: Nikolai GL
License: MIT License
        
        Copyright (c) 2026 NikolaiGL
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,ai-agents,architecture,code-navigation,coding-agent,llm,manifest
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<p align="center">
  <img src=".github/assets/logo_git.png" alt="ANNA — AI-Native Node Architecture" width="100%">
</p>

<p align="center">
  <a href="https://pypi.org/project/anna-arch/"><img src="https://img.shields.io/pypi/v/anna-arch.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/anna-arch/"><img src="https://img.shields.io/pypi/pyversions/anna-arch.svg" alt="Python versions"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
  <a href="./CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
  <a href="https://github.com/NikolaiGL/ANNA/stargazers"><img src="https://img.shields.io/github/stars/NikolaiGL/ANNA?style=social" alt="GitHub stars"></a>
</p>

Anyone who has built software with AI knows how it usually goes: the code grows quickly, turns into spaghetti, duplication creeps in everywhere, and things start breaking in unexpected places.

While looking for a solution, I realized that AI is being trained and pushed to write code the way a human would. But what's needed is a different approach — a set of instructions designed to be understood by both humans and AI. That's how ANNA was born.

ANNA represents your codebase as a dependency graph, with each node clearly described. An AI agent uses this representation to quickly understand the architecture and the relevant parts of the system, and only then dives into the specific section of code to execute changes with surgical precision. No wasted tokens, no unnecessary rewrites, no guesswork — just clean results.

## The Problem

AI coding agents are powerful — but no agent sees the full architecture at once. Given a task, an agent needs time and tokens just to map out where to act — and the larger the project, the more of both it takes. It lists directories, opens files, traces imports, and by the time it starts coding, most of the context window is already spent. Worse: even then it only sees fragments. It doesn't know what a module is *supposed* to do, what it guarantees, or what it must never do.

The agent improvises. It duplicates logic that already exists elsewhere. It bypasses contracts it didn't know about. It fixes a bug in one place without realizing the same assumption is embedded in three others. It lacks architectural memory.

ANNA gives the agent that context upfront. Every node in the graph carries its intent, its public contract, and its constraints. Before touching a single line of code, the agent reads simple manifests — and already knows the architecture, the rules, and exactly where to operate.

## How It Works

ANNA uses two core manifests: a **global manifest** that maps all nodes and their dependencies within a service, and a **local manifest** per file that describes its intent, public contract, and constraints. For microservice architectures, a **system manifest** *(planned)* will describe the services themselves and how they interconnect.

```
You:  "Add a DELETE /users/{id} endpoint"

Agent reads index.json (global manifest) → sees api.py → user_service.py
Agent reads user_service.py.json (local manifest) → sees get_user, create_user contracts
Agent writes code → adds delete_user → updates manifests

Total navigation: 2 file reads instead of 12.
```

## Quick Start

```bash
pip install anna-arch
cd your-project
anna init
```

`anna init` scaffolds the complete `.anna/` structure: `manifests/`, `audit/` (15 automated integrity checks), QA agent skills, infrastructure manifest, `.annaignore` with sensible defaults, and the full spec (`ANNA_RULES.md`).

Then two steps remain:

**1. Configure your agent's memory.** Run `anna agent-rules` — it prints ready-to-paste instructions and a table of where to put them for each agent (Cursor, Claude Code, Windsurf, Copilot, etc.).

**2. Ask your AI agent to generate the manifests:**

> *Read `.anna/ANNA_INIT.md` and initialize ANNA for this project.*

For projects with **30+ source files**, initialization runs in **batches** across multiple chat sessions — this is built into the init document and tracked via a progress file.

After initialization, **review what the agent created** — check that `index.json` reflects your project topology, that node intents match the actual purpose of your files, and that dependencies are accurate. The manifests are plain JSON — easy to read and verify. Then run `anna audit` to verify integrity.

### CLI Commands

| Command | What it does |
|---|---|
| `anna init` | Scaffold `.anna/` in the current project |
| `anna audit` | Run all integrity checks (same as `python .anna/audit/run_all.py`) |
| `anna update` | Upgrade framework files (audit checks, rules) to the installed version — your manifests, `.annaignore`, and configs are preserved |
| `anna agent-rules` | Print agent rules for your agent's config file |

<details>
<summary><b>Manual setup (without pip)</b></summary>

Point your AI agent to the initialization document — it will handle everything:

> *Read [ANNA_INIT.md](./ANNA_INIT.md) and initialize ANNA for this project.*

Your agent will create the `.anna/manifests/` structure, copy `audit/` into `.anna/audit/`, create `.annaignore` with sensible defaults, then analyze your codebase and generate all manifests.

To configure your agent's memory, copy the rules from **[ANNA_AGENT_RULES.md](./ANNA_AGENT_RULES.md)** into your agent's rules configuration file. Place **[ANNA_RULES.md](./ANNA_RULES.md)** in your project's `.anna/` folder — your agent will use it as the day-to-day operational reference.

Once set up, you can delete **[ANNA_INIT.md](./ANNA_INIT.md)** — it's only needed for the initial setup.

</details>

## The READ → CODE → SYNC Cycle

Every task follows three mandatory phases:

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│  READ   │ ──→ │  CODE   │ ──→ │  SYNC   │
│manifests│     │  write  │     │ update  │
│  first  │     │  code   │     │manifests│
└─────────┘     └─────────┘     └─────────┘
```

| Phase | What happens |
|---|---|
| **READ** | Agent reads `index.json` → finds affected nodes → reads their local manifests → reads their code if necessary |
| **CODE** | Agent writes code following contracts and constraints from manifests |
| **SYNC** | Agent updates manifests to reflect code changes. **Never skip.** |

> **Zero footprint.** ANNA lives entirely inside the `.anna/` folder and your agent's rules file. To remove ANNA completely, just delete `.anna/` and remove ANNA's rules from your agent's config — the next chat session will have no memory of it.

## Key Concepts

| Concept | Description |
|---|---|
| **Global Manifest** | `index.json` — map of all nodes and dependencies of the project, or of an individual service (for microservice architectures) |
| **Local Manifest** | Per-node `.json` file — full contract, constraints, and invariants for one file |
| **Node** | One source file = one node = one local manifest |
| **Node ID** | File path with `/` → `.` and extension after `:` (e.g., `backend.api:py`) |
| **Intent** | What the file does (1–2 sentences) — stored in global manifest |
| **Context** | How the file fits into the architecture (1–3 sentences) — stored in local manifest |
| **Contract** | Public API: methods with typed inputs/outputs |
| **Constraints** | Prescriptive rules — "don't do X", "always do Y" |
| **Invariants** | Verifiable assertions — "X is always true in this code" |
| **Dependencies** | Which other nodes this file imports from |
| **Broker** | Node excluded from cycle detection (for bidirectional deps like WebSocket hubs) |
| **Zero-Degree Rule** | A file with no incoming AND no outgoing dependencies is NOT a node — it stays outside ANNA until connected |
| **.annaignore** | Glob-pattern file that excludes tests, migrations, build configs, and other non-architectural files from manifests |
| **BUG-TO-CONSTRAINT** | Every bug fix adds a constraint to the manifest, preventing the same error from recurring |

## File Structure

```
your-project/
├── .anna/
│   ├── manifests/
│   │   ├── index.json                 ← Global: all nodes + deps
│   │   ├── backend/
│   │   │   ├── main.py.json           ← Local: contract for main.py
│   │   │   └── services/
│   │   │       └── user_service.py.json
│   │   └── frontend/
│   │       └── src/
│   │           └── App.tsx.json
│   ├── audit/                         ← Integrity checks (run after SYNC)
│   ├── qa/                            ← QA agent framework
│   │   ├── QA AGENT.md                ← QA agent skill
│   │   ├── QA AGENT INIT.md           ← First-run scaffold skill
│   │   ├── config.json                ← Test credentials & timeouts (generated)
│   │   ├── schemas.py                 ← Report models (generated)
│   │   ├── reporter.py                ← Report renderer (generated)
│   │   └── reports/                   ← JSON + Markdown test reports
│   ├── infra/                         ← Infrastructure manifest
│   │   └── infra.json                 ← Deployment topology & secrets map
│   ├── .annaignore                    ← Files excluded from ANNA
│   └── ANNA_RULES.md                  ← Full specification
├── backend/
│   ├── main.py
│   └── services/
│       └── user_service.py
└── frontend/
    └── src/
        └── App.tsx
```

📖 **Full specification:** [ANNA_RULES.md](./ANNA_RULES.md) · 📂 **Real-world example:** [examples/](./examples/.anna/manifests/)


## Audit System

ANNA includes **15 automated integrity checks** that run after every SYNC phase to catch manifest drift:

```bash
anna audit
# or directly:
python .anna/audit/run_all.py
```

Exit code `0` — all checks pass. Exit code `1` — errors found that **must be fixed before ending the task**.

The checks cover:
- **Structural integrity** — missing/orphan manifests, node ID consistency, required fields
- **Graph validity** — broken dependency refs, cycles (DAG enforcement), unreachable nodes
- **Source sync** — missing source files, `.annaignore` compliance
- **Contract sync** — every public function and parameter in code is reflected in manifests (0 errors AND 0 warnings)
- **Duplicate detection** — no duplicate node IDs in `index.json` or across local manifests

The runner auto-discovers all `check_*.py` modules in `.anna/audit/`, so adding a new check is as simple as creating a `check_<name>.py` file with a `run()` function.

📖 Full check catalog with remediation steps: [ANNA_RULES.md §10](./ANNA_RULES.md)

## QA Framework

ANNA includes a QA agent framework that provides structured, manifest-driven testing.

The QA agent tests your application against ANNA manifests — every constraint becomes a test case, every invariant becomes an assertion. It produces dual-format reports: JSON (for AI consumption) and Markdown (for developers).

To set up QA for your project, point your agent to the initialization skill:

> *Read [QA AGENT INIT.md](./qa/QA%20AGENT%20INIT.md) and scaffold the QA infrastructure.*

This creates `config.json`, `schemas.py`, `reporter.py`, and the `reports/` directory — all tailored to your project. Once scaffolded, the **[QA AGENT](./qa/QA%20AGENT.md)** skill handles test execution and reporting.

## Infrastructure Manifest

The `infra/` directory contains a single `infra.json` file — a complete map of your deployment topology: VPS, Docker services, networking, SSH access, CI/CD pipelines, environment variables, and deploy procedures.

This gives any agent (or new team member) instant context on how the system is deployed and operated, without reading Dockerfiles, CI configs, and wiki pages scattered across the project.

Fill it in once, keep it updated — the same way you maintain code manifests.

## Why ANNA?

| Without ANNA | With ANNA |
|---|---|
| Agent reads 10–15 files to understand structure | Agent reads 2 manifests and starts coding |
| No architectural memory between sessions | Manifests persist knowledge across agents and chats |
| Agent accidentally breaks contracts | Constraints and invariants prevent violations |
| Same bugs recur after fixes | BUG-TO-CONSTRAINT captures root causes permanently |
| "What does this file do?" — read 200 lines | "What does this file do?" — read intent (1–2 sentences) |

Impact scales with project size — the larger the codebase, the greater the time and token savings.

## Agent Support

ANNA works with any AI coding agent. Copy the universal rule file into your agent's config — run `anna agent-rules`, or use the file directly:

📄 **[ANNA_AGENT_RULES.md](./ANNA_AGENT_RULES.md)** — ready-to-paste instructions with a table of where to copy for each agent.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). ANNA is designed to evolve with the community.

## License

[MIT](./LICENSE) — use it everywhere, fork it, build on top.

---

**⭐ Star this repo if ANNA helps your AI agent work smarter.**
