Metadata-Version: 2.4
Name: iris-dev
Version: 1.8.1
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

# Iris

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

**Version:** v1.8 — May 12, 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 Iris Does Differently

Iris 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 `iris run <file.yaml>` in the terminal
3. Iris 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
  - `windows-curses` — TUI interface

---

## Installation

```bash
pip install iris-dev
```

Or build from source:

```bash
# Requirements: Python 3.10+, Ollama installed and running
git clone https://github.com/Anasteyshen/iris
cd iris
pip install ollama pyyaml windows-curses
```

---

## Commands

### `iris init`

```bash
iris init
```

```
iris — setup

Select a profile:
  [1] unity — Unity game projects
  [2] web — Web projects (HTML/CSS/JS)
  [3] python — Python libraries and scripts
  [4] cli — CLI tools
  [5] custom — Manual configuration

Profile (1-5): 2
Enter project path: C:/Users/user/projects/my-app
Project saved: C:/Users/user/projects/my-app
Profile:       web
```

---

### `iris run <file.yaml> [file2.yaml ...]`

```bash
iris run landing.yaml
```

```
iris — 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]   iris_report.yaml

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

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

You can also run multiple instruction files in sequence:

```bash
iris run layout.yaml styles.yaml logic.yaml
```

---

### `iris undo`

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

```bash
iris undo
```

```
iris — undo

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

iris — undo complete
```

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

---

### `iris validate <file.yaml>`

Checks a YAML instruction file for errors before running it.

```bash
iris validate landing.yaml
```

```
iris — validate landing.yaml

  [OK] landing.yaml is valid
```

Catches missing required fields, files that don't exist, and models not pulled in Ollama.

---

### `iris history`

Shows a log of all past runs.

```bash
iris history
```

```
iris — history

  [1] 2026-05-12 14:32 — landing.yaml
      Model:   qwen2.5-coder:7b
      Changed: src/App.jsx, src/App.css

  [2] 2026-05-12 15:10 — logic.yaml
      Model:   qwen2.5-coder:7b
      Changed: src/main.jsx
```

---

### `iris status`

Shows the current project path, profile, Ollama status, and last run info.

```bash
iris status
```

```
iris — status

  Project:   C:/Users/user/projects/my-app
  Profile:   web
  Model:     qwen2.5-coder:7b
  Ollama:    running ✓
  Last run:  2 file(s) changed
  Backup:    available (iris undo to restore)
```

---

### `iris start`

Opens the TUI (Text User Interface) — navigate with arrow keys, select with Enter.

```bash
iris start
```

```
┌────────────────────────────────────┐
│  ▶ INIT                            │
│    RUN                             │
│    VALIDATE                        │
│    STATUS                          │
│    HISTORY                         │
│    UNDO                            │
│    EXIT                            │
└────────────────────────────────────┘
```

---

## 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 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 `iris_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

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

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

---

### `functions` — function-level access control

Limit the agent to specific functions only. The rest of the file stays untouched.

```yaml
access:
  write:
    - Assets/Scripts/HealthSystem.cs:
        functions:
          - TakeDamage
          - Heal
          - Die

    - Assets/Scripts/PlayerStats.cs:
        functions:
          - AddExperience
          - LevelUp
        forbidden_functions:
          - ResetAllProgress
          - DeleteSave
```

- `functions` — agent can only read and modify these functions
- `forbidden_functions` — agent must never touch these functions

Supported languages: Python, JavaScript, TypeScript, C#, Java, Go, C, C++, Kotlin.

---

### `backup` + `iris undo` — rollback support

When `backup: true`, the original contents of all `write` files are saved to `iris_report.yaml` before any changes are made. Run `iris undo` to restore everything.

---

## Report format

When `feedback: true`, Iris writes `iris_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`
- Modify functions listed in `forbidden_functions`

---

## Roadmap

### v1.6

- [x] `iris init`, `run`, `undo`, `status`
- [x] `model` parameter
- [x] `error` parameter
- [x] `reference` parameter
- [x] `instructions` as a list
- [x] `iris undo` — rollback from backup

### v1.7

- [x] `iris run a.yaml b.yaml` — run multiple instructions at once
- [x] `iris history` — view past runs
- [x] `iris validate <file.yaml>` — check YAML syntax before running
- [x] `functions:` — function-level access control

### v1.8 — current

- [x] TUI interface — `iris start`
- [x] Project profiles in INIT (unity, web, python, cli, custom)
- [x] `pip install iris-dev`

---

## License

Iris 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 Iris by Anasteyshen and include a link
   to the original repository.

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.

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 "Iris" 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.
