{"id":51339659,"url":"https://github.com/semcod/iterun","last_synced_at":"2026-07-02T06:04:47.454Z","repository":{"id":330568580,"uuid":"1123193612","full_name":"semcod/iterun","owner":"semcod","description":"DSL-based intent execution system with iterative refinement, featuring AI-powered suggestions via Ollama, safe simulation, and automatic health validation.","archived":false,"fork":false,"pushed_at":"2026-06-18T12:39:47.000Z","size":11729,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T14:25:53.080Z","etag":null,"topics":["automation","devops","docker","dsl","intent","python","semcod","wronai"],"latest_commit_sha":null,"homepage":"https://semcod.github.io/iterun/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semcod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-26T11:16:28.000Z","updated_at":"2026-06-18T12:39:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/iterun","commit_stats":null,"previous_names":["wronai/amen","semcod/iterun"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/iterun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fiterun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fiterun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fiterun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fiterun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/iterun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fiterun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35035005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","devops","docker","dsl","intent","python","semcod","wronai"],"created_at":"2026-07-02T06:04:46.468Z","updated_at":"2026-07-02T06:04:47.422Z","avatar_url":"https://github.com/semcod.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ITERUN\n\n\u003e DSL-based intent execution system with iterative refinement, ITERUN boundary, and AI-powered assistance\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n## AI Cost Tracking\n\n![AI Cost](https://img.shields.io/badge/AI%20Cost-$19.31-orange) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fdeep%2Fdeep-v4-pro-lightgrey)\n\nThis project uses AI-generated code. Total cost: **$19.3058** with **19** AI commits.\n\nGenerated on 2026-06-29 using [openrouter/deep/deep-v4-pro](https://openrouter.ai/models/openrouter/deep/deep-v4-pro)\n\n---\n\n## Overview\n\nITERUN is a system that allows you to:\n\n1. **Generate intents from prompts** (LiteLLM / OpenRouter / Ollama) → **`iterun.yaml`**\n2. **Define intents** manually in YAML DSL (sekcja `INTENT:`)\n3. **Simulate execution** with dry-run planning\n4. **Deploy services** via Docker (default) or **pactown** sandboxes (`--runtime pactown`)\n5. **Pack stacks** to a single **markpact** file (`stack.markpact.md`)\n6. **Orchestrate repair** with **contract verify** (TestQL + LLM retry via `--verify`)\n7. **Monitor artifacts** with service registry (`iterun.registry.json`)\n8. **Integrate** via REST, SDK, MCP (`iterun-mcp`)\n9. **Get AI suggestions** in the interactive shell (Ollama / LiteLLM)\n10. **Execute safely** with the ITERUN boundary (explicit approval when enabled)\n\n**One-liner (prompt → running service):**\n\n```bash\niterun generate \"Create a REST API for user management\" \\\n  -o generated/ --execute --verify\n```\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│  CLI · REST · SDK · MCP (iterun-mcp)                     │\n│  interfaces/IterunService — wspólna warstwa API            │\n└─────────────────────────┬────────────────────────────────┘\n                          ↓\n┌──────────────────────────────────────────────────────────┐\n│  Generator (LLM) → iterun.yaml + intract + testql        │\n│  Parser → IR · Planner → app.py / compose / STACK        │\n│  markpact pack → stack.markpact.md                       │\n└─────────────────────────┬────────────────────────────────┘\n                          ↓\n┌────────────────────┐    ┌─────────────────────────────┐\n│ Runtime: docker    │ or │ Runtime: pactown            │\n│ (Executor)         │    │ (integrations/pactown_*)    │\n└─────────┬──────────┘    └──────────────┬──────────────┘\n          └──────────────┬───────────────┘\n                         ↓\n┌──────────────────────────────────────────────────────────┐\n│  Contract verify (--verify) → LLM repair loop            │\n│  Registry → iterun.registry.json (Backstage / OTel)      │\n│  session.json — pełny log sesji                          │\n└──────────────────────────────────────────────────────────┘\n```\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/softreck/iterun.git\ncd iterun\n\n# Full setup (recommended)\nmake setup\n\n# Editable install (recommended)\npython3 -m venv venv \u0026\u0026 source venv/bin/activate\npip install -e \".[ai]\"\npip install -e \".[runtime]\"   # opcjonalnie: markpact + pactown\n# lub lokalnie: pip install -e ../markpact -e ../pactown\ncp .env.example .env\n```\n\n### Configuration (.env)\n\nCopy `.env.example` to `.env` and adjust:\n\n```bash\n# LLM for `iterun generate` (priority: --model \u003e LLM_MODEL \u003e DEFAULT_MODEL)\nOPENROUTER_API_KEY=sk-or-...\nLLM_MODEL=openrouter/deepseek/deepseek-v4-pro\n\n# Local Ollama (shell suggest/chat fallback)\nOLLAMA_BASE_URL=http://localhost:11434\nDEFAULT_MODEL=llama3.2\n\n# Server / execution\nHOST=0.0.0.0\nPORT=8080\nSKIP_ITERUN_CONFIRMATION=true\nCONTAINER_PORT=8000\nITERUN_RUNTIME=docker          # lub pactown (bez docker w iterun)\n```\n\n### Generate from prompt\n\n```bash\nsource venv/bin/activate\n\n# YAML only\niterun generate \"Create a ping API\" -o generated/\n\n# Plan + artifacts\niterun generate \"...\" -o generated/ --run\n\n# Docker + contract verify + LLM repair loop (--verify wymagane!)\niterun generate \"...\" -o generated/ --execute --verify --max-verify-iterations 5\n\n# Pactown runtime (markpact sandboxes zamiast docker compose)\niterun generate \"...\" -o generated/ --execute --runtime pactown --verify\n\n# Rejestr usług i artefaktów\niterun registry -o generated/\n\n# Full JSON session log\niterun generate \"...\" -o generated/ --execute --verify --json\n```\n\nOutput directory (`generated/` by default) — see [Session artifacts](#session-artifacts).\n\n### AI Gateway Setup (Ollama)\n\n```bash\n# Install Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# Start and pull model\nmake ollama-start\nmake ollama-pull\n\n# Or manually\nollama serve\nollama pull llama3.2\n```\n\n### Using Makefile\n\n```bash\nmake help          # Show all commands\nmake setup         # Full setup\nmake web           # Start web server\nmake shell         # Interactive shell\nmake execute       # Execute example intent\nmake test          # Run all tests\nmake ollama-models # List available models\nmake clean         # Clean temp files\n```\n\n### Shell Interface\n\n```bash\n# Start interactive shell\nmake shell\n# Or: python -m cli.main\n\n# Generate + execute from prompt\nmake execute\n# Or: iterun generate \"$(cat examples/01-user-api/prompt.txt)\" -o examples/01-user-api/generated/ --execute --verify\n```\n\n**Interactive Shell Commands:**\n\n```\nintent\u003e new my-api          # Create new intent\nintent\u003e load iterun.yaml    # Load package (generated/iterun.yaml)\nintent\u003e plan                # Run dry-run\nintent\u003e suggest             # Get AI suggestions\nintent\u003e apply               # Auto-apply AI suggestions\nintent\u003e chat                # Chat with AI\nintent\u003e iterate             # Apply manual changes\nintent\u003e iterun                # Approve execution\nintent\u003e execute             # Execute approved intent\nintent\u003e show [json]         # Show current state\nintent\u003e models              # List AI models\nintent\u003e ai-health           # Check AI Gateway status\nintent\u003e help                # Show help\nintent\u003e exit                # Exit shell\n\n# Poza shell — registry i runtime\niterun registry -o generated/\niterun registry list examples/*/generated\n```\n\n### MCP (agents)\n\n```bash\npip install -e \".[mcp]\"\niterun-mcp   # z katalogu root iterun; nie z examples/*\n```\n\n### Web Interface\n\n```bash\n# Start web server\npython -m web.app\n\n# Open browser at http://localhost:8080\n```\n\n## AI Gateway\n\nThe AI Gateway uses **LiteLLM** for:\n\n- **`iterun generate`** — cloud models via **OpenRouter** (`OPENROUTER_API_KEY`, `LLM_MODEL`)\n- **Shell `suggest` / `chat`** — local **Ollama** (`OLLAMA_BASE_URL`, `DEFAULT_MODEL`)\n\n### Supported Models (≤12B parameters)\n\n| Model | Size | Description |\n|-------|------|-------------|\n| `llama3.2` | 3B | Default - Fast and efficient |\n| `llama3.2:1b` | 1B | Ultra lightweight |\n| `llama3.1:8b` | 8B | Balanced performance |\n| `mistral` | 7B | Fast inference |\n| `mistral-nemo` | 12B | Best quality under 12B |\n| `gemma2` | 9B | Google Gemma 2 |\n| `gemma2:2b` | 2B | Lightweight |\n| `phi3` | 3.8B | Microsoft Phi-3 |\n| `qwen2.5` | 7B | Alibaba Qwen 2.5 |\n| `codellama` | 7B | Code generation |\n| `codegemma` | 7B | Google CodeGemma |\n| `deepseek-coder` | 6.7B | DeepSeek Coder |\n\n### Configuration\n\nEnvironment variables:\n\n```bash\nexport OLLAMA_BASE_URL=\"http://localhost:11434\"\nexport DEFAULT_MODEL=\"llama3.2\"\nexport MAX_MODEL_PARAMS=\"12.0\"\n```\n\n### Package file: `iterun.yaml`\n\nThe canonical workspace filename is **`iterun.yaml`** (not `intent.yaml`). Full spec: [docs/INTENT_DSL_SPEC.md](docs/INTENT_DSL_SPEC.md).\n\n```yaml\nINTENT:\n  name: user-api\n  goal: Create a REST API for user management\n\nENVIRONMENT:\n  runtime: docker\n  base_image: python:3.12-slim\n  ports:\n    - 8000\n\nIMPLEMENTATION:\n  language: python\n  framework: fastapi\n  actions:\n    - api.expose GET /ping\n    - api.expose GET /users\n    - api.expose POST /users\n    - api.expose DELETE /users/{id}\n\nEXECUTION:\n  mode: dry-run\n```\n\n### Supported Actions\n\n| Action | Format | Description |\n|--------|--------|-------------|\n| `api.expose` | `api.expose METHOD /path` | Expose HTTP endpoint |\n| `db.create` | `db.create table_name` | Create database table |\n| `db.add_column` | `db.add_column table column type` | Add column to table |\n| `shell.exec` | `shell.exec command` | Execute shell command |\n| `rest.call` | `rest.call METHOD url` | Call external REST API |\n| `file.create` | `file.create path` | Create file |\n\n## API Reference\n\nPełna dokumentacja: **[docs/API.md](docs/API.md)** — REST, SDK, MCP, STACK.  \nRejestr usług/artefaktów: **[docs/REGISTRY.md](docs/REGISTRY.md)** — Backstage, OCI, OTel.  \nRuntime markpact+pactown: **[docs/RUNTIME.md](docs/RUNTIME.md)** — odchudzone uruchamianie.\n\n### Integration surfaces\n\n| Surface | Entry |\n|---------|-------|\n| REST | `uvicorn web.app:app` → `/api/*`, OpenAPI `/docs` |\n| CLI | `iterun generate`, `iterun plan`, … |\n| SDK | `IterunClient()` — local lub `base_url=\"http://…\"` |\n| MCP | `iterun-mcp` / `python -m iterun_mcp.server` — narzędzia dla agentów LLM |\n\n### REST Endpoints (skrót)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/health` | Liveness |\n| `GET` | `/api/interfaces` | Lista powierzchni API |\n| `GET` | `/api/schema` | JSON Schema for DSL |\n| `POST` | `/api/intents/validate-yaml` | Validate YAML (`is_stack`) |\n| `POST` | `/api/intents/plan-yaml` | Plan z YAML (STACK → compose) |\n| `POST` | `/api/pipeline/run` | generate → plan → execute? → verify? |\n| `POST` | `/api/intents/generate` | LLM → YAML |\n| `POST` | `/api/intents/generate-and-run` | Alias `/api/pipeline/run` |\n| `GET` | `/api/registry` | Service/artifact registry |\n| `POST` | `/api/registry/refresh` | Refresh registry + exports |\n| `GET` | `/api/intents` | List all intents |\n| `POST` | `/api/intents/parse` | Parse DSL and create intent |\n| `GET` | `/api/intents/{id}` | Get intent by ID |\n| `POST` | `/api/intents/{id}/plan` | Dry-run (`compose_yaml` dla STACK) |\n| `POST` | `/api/intents/{id}/execute` | Execute approved intent |\n\n### AI Gateway Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/ai/status` | Check AI Gateway status |\n| `GET` | `/api/ai/models` | List available models |\n| `POST` | `/api/ai/complete` | Generate AI completion |\n| `POST` | `/api/ai/chat` | Chat with AI |\n| `POST` | `/api/intents/{id}/ai/suggest` | Get AI suggestions |\n| `POST` | `/api/intents/{id}/ai/apply` | Auto-apply suggestions |\n\n### Python API\n\n```python\nfrom generator.pipeline import run_pipeline\nfrom parser import parse_dsl\nfrom planner import plan_intent\nfrom sdk import IterunClient\n\n# Prompt → full pipeline\nresult = run_pipeline(\n    \"Create a REST API for user management\",\n    output_dir=\"generated\",\n    execute=True,\n    verify=True,\n)\nprint(result.yaml_path)       # generated/iterun.yaml\nprint(result.verification)    # testql + HTTP result\n\n# Or SDK (local or remote REST)\nclient = IterunClient()\nout = client.run_pipeline(\"Create a ping API\", output_dir=\"generated\", execute=True, verify=True)\n# remote = IterunClient(base_url=\"http://localhost:8000\")\n\n# Manual DSL\nir = parse_dsl(open(\"generated/iterun.yaml\").read())\nplan = plan_intent(ir)\nprint(plan.generated_code)\n```\n\n## Examples\n\n| Script | Opis |\n|--------|------|\n| `./examples/run-all.sh` | 01–08: prompt → `iterun.yaml` → plan |\n| `./examples/run-e2e.sh` | 09–12: execute + TestQL + Intract |\n| `./examples/run-resilience.sh` | 13–16: skrajne prompty, pętla naprawcza |\n| `./examples/run-stacks.sh` | 17–19: multi-service STACK (compose / pactown) |\n\nSzczegóły: [examples/README.md](examples/README.md) · operacje: [examples/OPERATIONS.md](examples/OPERATIONS.md).\n\n## Session artifacts\n\nEverything from one `iterun generate` run lands in `--output-dir` (default `generated/`):\n\n| File | Content |\n|------|---------|\n| `iterun.yaml` | DSL package from LLM |\n| `session.json` | **Full session** — prompt, generate attempts, plan, execute, verify |\n| `intract.yaml` | Intract contract manifest |\n| `service.testql.toon.yaml` | Auto-generated TestQL scenario |\n| `plan.result.json` | Plan logs + IR |\n| `execution.json` | Execute logs, endpoints, container id |\n| `container.log` | Docker logs (tail) |\n| `verify.result.json` | Contract verify result |\n| `verify.rounds.json` | Repair loop history (`--verify`) |\n| `app.py` / `Dockerfile` | Generated service |\n| `stack.markpact.md` | Cały workspace w jednym pliku markpact |\n| `pactown.yaml` | Konfiguracja ekosystemu pactown |\n| `pactown.urls.json` | URL po `--runtime pactown` |\n| `stack.urls.json` | URL gatewayów (STACK, docker) |\n| `iterun.registry.json` | Rejestr usług i artefaktów |\n| `catalog/` | Eksport Backstage (po `iterun registry`) |\n\n## Testing\n\n```bash\npytest\npytest tests/e2e/test_intent_generator.py -v\npytest tests/e2e/test_shell.py -v\npytest tests/e2e/test_web.py -v\npytest tests/e2e/test_ai_gateway.py -v\n```\n\n## Project Structure\n\n```\niterun/\n├── generator/          # LLM generate, pipeline, testql, intract, verify loop\n│   ├── intent_generator.py\n│   ├── pipeline.py\n│   ├── contract_verify.py\n│   └── session.py\n├── dsl/                # Pydantic schema for LLM validation\n├── ir/                 # Intermediate Representation\n├── parser/             # DSL parser\n├── planner/            # Dry-run simulator\n├── executor/           # Docker execution + HTTP validation\n├── ai_gateway/         # LiteLLM (Ollama + OpenRouter)\n├── cli/                # `iterun` CLI\n├── web/                # FastAPI web UI\n├── sdk/                # Python SDK client\n├── interfaces/         # IterunService — REST/SDK/MCP\n├── integrations/       # markpact pack, pactown runtime, registry bridges\n├── registry/           # iterun.registry.json catalog\n├── iterun_mcp/         # MCP server (`iterun-mcp`; nie `mcp/` — konflikt PyPI)\n├── examples/           # 01–19: prompt.txt + run.sh → generated/\n├── docs/               # API, REGISTRY, RUNTIME, DSL spec\n├── tests/e2e/\n├── config.py           # PACKAGE_FILENAME = \"iterun.yaml\"\n└── README.md\n```\n\n## Workflow\n\n### Prompt-first (recommended)\n\n1. **Prompt** → `iterun generate \"...\" -o generated/`\n2. **Contracts** → auto `intract.yaml` + `service.testql.toon.yaml`\n3. **Plan** → `app.py`, `Dockerfile`, `plan.result.json`\n4. **Pack** → `stack.markpact.md` (+ per-service README dla pactown)\n5. **Execute** → Docker (default) lub pactown (`--runtime pactown`)\n6. **Verify** → TestQL + HTTP (`--verify`); **LLM repair** przy błędzie (bez `--verify` brak regeneracji YAML)\n7. **Registry** → `iterun.registry.json`\n8. **Session** → `session.json` aggregates all steps\n\n### Manual / interactive\n\n1. **Edit** `iterun.yaml` or use shell `new` / `load`\n2. **Plan** → dry-run\n3. **Suggest / iterate** → AI or manual refinement\n4. **ITERUN** → approve (unless `SKIP_ITERUN_CONFIRMATION`)\n5. **Execute** → deploy + endpoint validation\n\nDocumentation:\n\n| Dokument | Temat |\n|----------|-------|\n| [docs/README.md](docs/README.md) | Indeks dokumentacji |\n| [docs/INTENT_DSL_SPEC.md](docs/INTENT_DSL_SPEC.md) | DSL, pipeline, STACK |\n| [docs/API.md](docs/API.md) | REST, SDK, MCP |\n| [docs/REGISTRY.md](docs/REGISTRY.md) | Rejestr usług/artefaktów |\n| [docs/RUNTIME.md](docs/RUNTIME.md) | markpact + pactown |\n\n## Validation \u0026 Auto-Fix\n\nAfter container deployment, the system automatically:\n\n1. **Waits** for container startup (configurable `STARTUP_WAIT`)\n2. **Validates** all exposed endpoints with HTTP requests\n3. **Detects issues** like connection refused, timeouts, HTTP errors\n4. **Auto-fixes** common problems:\n   - Missing `__main__` block\n   - Wrong port configuration\n   - Missing dependencies\n5. **Restarts** container with fixes\n6. **Re-validates** until success or max iterations reached\n\n### Configuration\n\n```bash\n# In .env\nVALIDATE_AFTER_EXECUTE=true\nAUTO_FIX_ENABLED=true\nMAX_FIX_ITERATIONS=3\nSTARTUP_WAIT=2\nVALIDATION_TIMEOUT=10\n```\n\n### Example Output\n\n```\nExecution Logs:\n  [12:38:55] Container started: 8f35e0a2fb27\n  [12:38:55] Waiting 2s for container startup...\n  [12:38:57] ✓ http://localhost:8002 → 200\n  [12:38:57] ✓ http://localhost:8002/ping → 200\n  [12:38:57] ✓ http://localhost:8002/health → 200\n  [12:38:57] ✓ All endpoints validated successfully\n✓ Execution completed in 2.56s\n\nValidation:\n  ✓ All endpoints validated\n```\n\n### API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/intents/{id}/validate` | Validate running container |\n| `GET` | `/api/containers/{id}/logs` | Get container logs |\n\n## License\n\nLicensed under Apache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fiterun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Fiterun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fiterun/lists"}