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

# Iris

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

**Version:** v1.9.0

---

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

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.

---

## Installation

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

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

---

## Quick Start

### 1. Launch Iris

```bash
iris start
```

This opens the TUI — a terminal interface where you can do everything without remembering commands.

```
    ██╗██████╗ ██╗███████╗
    ██║██╔══██╗██║██╔════╝
    ██║██████╔╝██║███████╗
    ██║██╔══██╗██║╚════██║
    ██║██║  ██║██║███████║
    ╚═╝╚═╝  ╚═╝╚═╝╚══════╝

  Copyright by Anasteyshen666   Version: 1.9.0

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

  ↑↓ navigate   Enter select   Ctrl+C exit
```

### 2. Initialize your project

Select **INIT** in the TUI, choose a profile and enter your project path.

Or use the CLI:

```bash
iris init
```

```
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. Profile: web
```

### 3. Write a YAML instruction

Create a file `task.yaml` in your project folder:

```yaml
model: qwen2.5-coder:14b

access:
  write:
    - src/App.jsx
    - src/styles.css
  ban:
    - .env
    - src/auth.js

prompt: Add a dark mode toggle with CSS variables and localStorage

backup: true
feed: true
```

### 4. Run it

In the TUI select **RUN**, pick your yaml file and press Enter. Or via CLI:

```bash
iris run task.yaml
```

```
iris — running task.yaml

  [SYNTAX]   1.9
[1/4] Collecting context...
[2/4] Sending request to Ollama...
  [MODEL]    qwen2.5-coder:14b
  [TEMP]     0.1
[3/4] Applying changes...
  [WRITTEN]  src/App.jsx
  [WRITTEN]  src/styles.css
[4/4] Finalizing...
  [REPORT]   iris_report.yaml

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

### 5. Something went wrong? Undo it.

```bash
iris undo
```

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

---

## TUI Guide

Launch with `iris start`. Navigate with arrow keys, select with Enter.

| Screen | Description |
|--------|-------------|
| INIT | Set up project path and profile |
| RUN | Select one or multiple YAML files to run (Space to select, Enter to run) |
| VALIDATE | Check a YAML file for errors before running |
| STATUS | View current project, Ollama status, last run info |
| HISTORY | View past runs |
| MODELS | List installed Ollama models, add or delete models |
| UNDO | Roll back the last run |

**During a run** — press Enter to stop execution immediately. No changes are saved.

---

## YAML Syntax

### New syntax (v1.9) — recommended

```yaml
model: qwen2.5-coder:14b

access:
  read:
    - src/main.jsx
  write:
    - src/App.jsx
    - src/styles.css
  ban:
    - .env

prompt: Add a dark mode toggle

backup: true
feed: true
```

Minimum required:

```yaml
access:
  write:
    - src/App.jsx

prompt: Add a dark mode toggle
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | yes | What the agent should do |
| `model` | string | no | Ollama model (default: `qwen2.5-coder:7b`) |
| `access.write` | list | yes | Files the agent can modify or create |
| `access.read` | `true` / `false` / list | no | Files the agent can read for context |
| `access.ban` | list | no | Files the agent must never touch |
| `ref` | list | no | Example files for style reference |
| `err` | string | no | Console error to fix. Use `console.msg` to read from last captured output |
| `feed` | boolean | no | Save report with changes and tips |
| `backup` | boolean | no | Save original files before overwriting |
| `temperature` | float | no | Model temperature (default: 0.1) |

### Legacy syntax (pre v1.9) — still supported

```yaml
task: "Add a dark mode toggle"
model: qwen2.5-coder:14b
access:
  read: true
  write:
    - src/App.jsx
  forbidden:
    - .env
instructions:
  - Add CSS variables for dark mode
  - Add toggle button to header
feedback: true
tips: true
backup: true
```

---

## Function-level Access Control

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

New syntax:

```yaml
access:
  write:
    - src/player.py:
        func:
          - take_damage
          - heal
        ban:
          - reset_all
          - delete_save
```

Legacy syntax:

```yaml
access:
  write:
    - src/player.py:
        functions:
          - take_damage
          - heal
        forbidden_functions:
          - reset_all
```

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

---

## Capturing Console Errors

Run your program through Iris to capture its output:

```bash
iris console python main.py
```

```
  [RUN] python main.py

  Traceback (most recent call last):
    File "main.py", line 12, in <module>
  NameError: name 'Workbook' is not defined

  [SAVED] Console output saved to iris_console.log
  [HINT]  Now use err: console.msg in your yaml
```

Then in your yaml:

```yaml
access:
  write:
    - main.py

err: console.msg
prompt: Fix the error
```

---

## Managing Models

In the TUI select **MODELS** to see all installed Ollama models, add new ones or delete unused ones.

Or via CLI:

```bash
ollama pull qwen2.5-coder:14b
ollama pull deepseek-coder-v2:16b
```

---

## Commands

| Command | Description |
|---------|-------------|
| `iris start` | Open TUI |
| `iris init` | Initialize project |
| `iris run <file.yaml>` | Run instruction file |
| `iris run a.yaml b.yaml` | Run multiple files in sequence |
| `iris undo` | Roll back last run |
| `iris validate <file.yaml>` | Check YAML for errors |
| `iris history` | View past runs |
| `iris status` | View project status |
| `iris console <command>` | Run command and capture output |

---

## What the Agent Cannot Do

- Delete files
- Run shell commands
- Access files outside the project path
- Write files not listed in `access.write`
- Read files listed in `access.ban`
- Modify functions listed in `ban` inside write entries

---

## Roadmap

### v1.6 — v1.8.4

- [x] Core CLI — init, run, undo, validate, history, status
- [x] model, error, reference, instructions parameters
- [x] backup + undo rollback
- [x] TUI interface
- [x] Project profiles
- [x] Function-level access control
- [x] pip install iris-dev
- [x] System prompt + temperature control
- [x] Fuzzy file name matching

### v1.9 — current

- [x] Redesigned TUI with ASCII logo and copyright
- [x] MODELS screen — list, add, delete Ollama models
- [x] Multi-select YAML in RUN (Space to select, Enter to run)
- [x] Stop running agent with Enter
- [x] New short syntax — `prompt`, `feed`, `ref`, `err`, `func`, `ban`
- [x] Legacy syntax compatibility
- [x] `err: console.msg` — read last console output automatically
- [x] `iris console <command>` — capture program output
- [x] `yaml/` folder support for instructions
- [x] History clears on new project
- [x] Undo clears on new run

---
