Metadata-Version: 2.4
Name: iris-dev
Version: 1.8.0
Summary: AI-powered CLI agent with controlled, structured access to your codebase
Author-email: Anasteyshen666 <fangishanonim@gmail.com>
License: See LICENSE
Keywords: ai,agent,cli,coding,ollama,llm
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: ollama
Requires-Dist: pyyaml
Requires-Dist: windows-curses

# 🤖 asgu

> AI-powered CLI agent that gives language models controlled, structured access to your codebase through simple YAML instruction files.

**Version:** v1.6 — April 9, 2026

---

## 😤 The Problem with Existing AI Coding Agents

Most AI coding tools today share the same fundamental flaws:

- **🚫 No boundaries.** The agent reads and modifies whatever it wants across your entire project. One wrong instruction and critical files get overwritten or deleted.
- **🎲 No structure.** You write a prompt in natural language, the AI guesses what files to touch, and you hope for the best.
- **👻 No accountability.** After the agent runs, you have no clear record of what changed, why, or what it noticed along the way.
- **💸 Token waste.** Feeding the entire codebase into context on every request is slow and expensive.
- **🐛 Logical errors go unnoticed.** If there's no console error, most agents won't catch that styles aren't applied or that an import is pointing at the wrong file.

Tools like Cursor, Copilot, and other agents are powerful — but they operate with too much freedom and too little transparency for serious development workflows.

---

## ✅ What asgu Does Differently

asgu introduces a **YAML instruction file** that you write before the agent runs. This file defines exactly what the agent can read, what it can write, what it must never touch, and what it needs to fix. The agent operates strictly within these boundaries.

You stay in control. The agent stays in its lane.

---

## ⚙️ How It Works

1. 📝 You create a `.yaml` instruction file in your project folder
2. ▶️ You run `asgu run <file.yaml>` in the terminal
3. 🤖 asgu reads your instruction, collects the relevant context, sends a structured prompt to the AI model, parses the response, and writes only the files you allowed
4. 📊 Optionally, it saves a report with what changed, tips from the model, and a backup of the original files

---

## 🛠️ Stack

- **Language:** Python
- **AI model:** `qwen2.5-coder:7b` via [Ollama](https://ollama.com) (runs fully locally, no API key needed)
- **Libraries:**
  - `ollama` — local model inference
  - `pyyaml` — YAML instruction parsing
  - `pyinstaller` — builds the project into a standalone `.exe`

---

## 📦 Installation

**Requirements:** Python 3.10+, [Ollama](https://ollama.com) installed and running

```bash
# Install dependencies
pip install ollama pyyaml

# Pull the model
ollama pull qwen2.5-coder:7b

# Clone the repo and build
git clone https://github.com/yourname/asgu
cd asgu
pyinstaller --onefile --hidden-import=ollama asgu.py
```

The `asgu.exe` will appear in the `dist/` folder.

---

## 🚀 Commands

### `asgu init`

```bash
asgu init
```

```
asgu — setup

Enter project path: C:/Users/user/projects/my-app
Project saved. Now run: asgu run <file.yaml>
```

The project path is saved to `asgu.config.json` next to the executable.

---

### `asgu run <file.yaml>`

```bash
asgu run landing.yaml
```

```
asgu — running landing.yaml

[1/4] Collecting context...
[2/4] Sending request to Ollama...
[3/4] Applying changes...
  [WRITTEN]  src/App.jsx
  [WRITTEN]  src/App.css
[4/4] Finalizing...
  [REPORT]   asgu_report.yaml

  [TIPS]
  > App.css should also be imported in src/main.jsx

asgu — done (2 file(s) changed)
```

---

### `asgu undo`

Rolls back changes to all files that were modified in the last run, using the backup saved in `asgu_report.yaml`.

```bash
asgu undo
```

```
asgu — undo

  [RESTORED]  src/App.jsx
  [RESTORED]  src/App.css

asgu — done (2 file(s) restored)
```

> Requires `backup: true` in the instruction file used for the previous run.

---

### `asgu status`

Shows the current project path and the last instruction that was run.

```bash
asgu status
```

```
asgu — status

  Project:   C:/Users/user/projects/my-app
  Last run:  landing.yaml
  Changed:   src/App.jsx, src/App.css
  Backed up: yes
```

---

## 📋 YAML Instruction Syntax

### Full example

```yaml
task: "Create a landing page for a clothing store"

model: qwen2.5-coder:7b

access:
  read: true
  write:
    - src/App.jsx
    - src/App.css
  forbidden:
    - .env
    - src/main.jsx

reference:
  - references/example.css
  - references/layout.html

error: |
  TypeError: Cannot read properties of undefined at App.jsx:15
  Styles from App.css are not applied to the page.

instructions:
  - Create a hero section with a title, subtitle and a button
  - Create a products section with 3 product cards
  - Add a footer with contact info
  - Import App.css at the top of App.jsx

feedback: true
tips: true
backup: true
```

---

### 🔧 Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task` | string | ✅ yes | Short description of what the agent should do |
| `model` | string | ➖ no | Ollama model to use (default: `qwen2.5-coder:7b`) |
| `access.read` | `true` / `false` / list | ✅ yes | Controls what the agent can read for context |
| `access.write` | list | ✅ yes | Files the agent is allowed to modify or create |
| `access.forbidden` | list | ➖ no | Files the agent must never touch |
| `reference` | list | ➖ no | Paths to example files (HTML, CSS) used as style reference |
| `error` | string | ➖ no | Console error or description of a logical bug to fix |
| `instructions` | list | ✅ yes | Step-by-step instructions for the agent |
| `feedback` | boolean | ➖ no | Save a report to `asgu_report.yaml` after the run |
| `tips` | boolean | ➖ no | Ask the model to report issues outside the write zone |
| `backup` | boolean | ➖ no | Save original file contents to the report before overwriting |

---

### 👁️ `access.read` modes

```yaml
# Read the entire project (excludes forbidden and .yaml files)
read: true

# Read nothing — agent only sees the write files
read: false

# Read specific files only
read:
  - src/App.jsx
  - src/main.jsx
```

---

### 🐛 `error` — console or logical errors

Paste any error directly:

```yaml
error: |
  Module not found: Error: Can't resolve './App.css'
  at ./src/App.jsx
```

Or describe a logical issue:

```yaml
error: |
  The button click does not trigger any action.
  The counter does not increment when clicked.
```

---

### 🎨 `reference` — example files

Point the agent to existing HTML or CSS files to use as a style reference:

```yaml
reference:
  - references/old_design.css
  - references/example_layout.html
```

---

### 💾 `backup` + `asgu undo` — rollback support

When `backup: true`, the original contents of all `write` files are saved to `asgu_report.yaml` before any changes are made. If the result is wrong, run `asgu undo` to restore everything automatically.

---

## 📊 Report format

When `feedback: true`, asgu writes `asgu_report.yaml` to your project folder:

```yaml
task_completed: Create a landing page for a clothing store
changed_files:
  - src/App.jsx
  - src/App.css
tips:
  - App.css import is missing in src/main.jsx
backup:
  src/App.jsx: |
    // original file content before changes
```

---

## 🚫 What the Agent Cannot Do

- ❌ Delete files
- ❌ Run shell commands (`npm install`, `git`, etc.)
- ❌ Access files outside the project path
- ❌ Write files not listed in `access.write`
- ❌ Read files listed in `access.forbidden`

---

## 🗺️ Roadmap

### ✅ v1.6 — current

- [x] `asgu init`, `run`, `undo`, `status`
- [x] `model` parameter — choose the model inside the YAML
- [x] `error` parameter — pass a bug or console error directly
- [x] `reference` parameter — example files for context
- [x] `instructions` as a list instead of a plain string
- [x] `asgu undo` — one-command rollback from backup

### 🔜 v1.7 — planned

- [ ] `asgu run a.yaml b.yaml` — run multiple instructions at once
- [ ] `asgu history` — view past runs
- [ ] `asgu validate <file.yaml>` — check YAML syntax before running
- [ ] `functions:` sub-parameter for `read`, `write`, `forbidden` — function-level access control inside a file

---

## 📄 License

asgu Source Available License
Copyright (c) 2026 Anasteyshen666

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated source code (the "Software"), to use, run,
and study the Software for personal or commercial purposes, subject to the
following conditions:

1. ATTRIBUTION REQUIRED
   Any modified version of the Software that is publicly distributed must
   clearly state that it is based on asgu by Anasteyshen and include a link
   to the original repository. This notice must appear in the documentation,
   README, or any other prominent place in the modified work.

2. NO SALE OF MODIFICATIONS WITHOUT PERMISSION
   You may not sell, sublicense, or otherwise commercially distribute any
   modified version of the Software without prior written permission from
   the author (Anasteyshen). Selling or monetizing the Software in its
   original, unmodified form is also not permitted without permission.

3. WHAT YOU CAN DO (without asking)
   - Use the Software for any personal or commercial project
   - Read and study the source code
   - Share the original, unmodified Software with proper credit
   - Fork and modify the Software for private use

4. WHAT REQUIRES PERMISSION
   - Publishing or distributing a modified version
   - Selling or monetizing any version of the Software
   - Using the name "asgu" or the author's name to promote a derived product

To request permission, contact: fangishanonim@gmail.com

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

MIT
