iterare-llm 0.1.2__tar.gz

iterare_llm-0.1.2/.gitignore

@@ -0,0 +1,43 @@
+# Prompts directory - contains local prompt experiments
+prompts/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+.venv/
+ENV/
+env/
+.coverage
+htmlcov
+.python-version
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+
+# iterare workspaces
+workspaces/
+
+# Claude Code
+CLAUDE.md

iterare_llm-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohonet Ltd
+
+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.

iterare_llm-0.1.2/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: iterare-llm
+Version: 0.1.2
+Summary: Automated Claude Code execution in isolated environments
+Project-URL: Homepage, https://github.com/sohonetlabs/iterare-llm
+Project-URL: Repository, https://github.com/sohonetlabs/iterare-llm
+Project-URL: Issues, https://github.com/sohonetlabs/iterare-llm/issues
+Author-email: Andrew Walker <andrew.walker@sohonet.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic,automation,claude,docker,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.13
+Requires-Dist: docker>=7.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: typer>=0.19.2
+Description-Content-Type: text/markdown
+
+# Iterare
+
+Automated Claude Code execution in isolated Docker containers.
+
+`iterare` creates git worktrees, launches containerised Claude Code instances with autonomous permissions, and
+maintains safety through network firewalls and container isolation. This enables "agentic loops" where Claude
+Code can modify codebases without human confirmation while being restricted to whitelisted network access and
+mounted files.
+
+_**Warning – This does not fully protect from malicious code execution or data exfiltration. It simply raises the 
+barriers to these things happening. Use at your own risk.**_
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) for dependency management
+- Docker
+- A Claude Code API key
+
+## Installation
+
+```bash
+# Install via pypi
+pip install iterare-llm
+
+# Create global config directories
+iterare install
+
+# Fetch Claude Code credentials (interactive Docker session)
+iterare credentials
+```
+
+## Quick Start
+
+The easiest way to get started is to use the interactive mode. This launches a Claude Code session in a Docker
+container, mounts your current project directory, and allows you to drive Claude Code yourself.
+
+```bash
+# Initialize a project
+cd /path/to/your/project
+iterare init
+
+# Launch in interactive mode
+iterare interactive
+```
+
+Alternatively, you can create a prompt file and execute it. This (by default) creates a git worktree, and branches
+off of the current branch. It then launches Claude Code in a Docker container, mounts the worktree directory, and
+passes the prompt to Claude Code which will then execute the prompt until it's done. This is fantastic for autonomous
+development.
+
+```bash
+# Initialize a project
+cd /path/to/your/project
+iterare init
+
+# Create a prompt
+cat > .iterare/prompts/refactor.md << 'EOF'
+---
+workspace: refactor-auth
+branch: main
+---
+
+Refactor the authentication module to use JWT tokens.
+Add tests for the new implementation.
+EOF
+
+# Execute the prompt
+iterare execute refactor
+
+# Monitor progress
+iterare log -f
+
+# When done, merge changes back
+iterare merge
+
+# Clean up the worktree
+iterare cleanup -y
+```
+
+## Commands
+
+### `iterare init [PATH]`
+
+Initialise a project for iterare. Creates the `.iterare/` directory with configuration files and
+a `workspaces/` directory for git worktrees.
+
+```bash
+iterare init                    # Initialize current directory
+iterare init /path/to/project   # Initialize specific directory
+iterare init --force            # Overwrite existing configuration
+```
+
+### `iterare install`
+
+Create global configuration directories for credentials and logs.
+
+```bash
+iterare install
+```
+
+### `iterare credentials`
+
+Fetch Claude Code credentials via an interactive Docker session. Launches a container where you can log in, 
+then extracts the credential files.
+
+```bash
+iterare credentials             # First-time setup
+iterare credentials --force     # Re-authenticate
+iterare credentials --image my-image:latest  # Use custom image
+```
+
+### `iterare execute <prompt>`
+
+Execute a prompt in an isolated Docker container. Creates a git worktree, mounts it in a container, and launches 
+Claude Code in autonomous mode.
+
+```bash
+# By prompt name (looks in .iterare/prompts/)
+iterare execute refactor
+
+# By file path
+iterare execute .iterare/prompts/task.md
+
+# Reuse an existing workspace
+iterare execute refactor --reuse refactor-abc12345
+
+# Pass environment variables to the container
+iterare execute refactor --env PIP_INDEX_URL --env GITHUB_TOKEN
+```
+
+### `iterare interactive`
+
+Launch an interactive Claude Code session in a container. By default runs in the project directory without
+creating a worktree.
+
+```bash
+# Default: run in project directory
+iterare interactive
+
+# Create a worktree for isolation
+iterare interactive --worktree
+
+# Name the workspace
+iterare interactive --worktree --workspace my-feature
+
+# Base on a specific branch
+iterare interactive --worktree --branch main
+
+# Reuse an existing workspace
+iterare interactive --worktree --reuse my-feature-abc12345
+
+# Pass environment variables
+iterare interactive --env PIP_INDEX_URL
+```
+
+### `iterare log [RUN_NAME]`
+
+View execution logs for a run.
+
+```bash
+iterare log                     # Most recent run
+iterare log refactor-abc12345   # Specific run
+iterare log -f                  # Follow live output
+iterare log --raw               # Raw JSON output
+iterare log -v 0                # Minimal (text responses only)
+iterare log -v 2                # Verbose (all details)
+```
+
+### `iterare list`
+
+List execution runs for the project.
+
+```bash
+iterare list                    # Active and finished runs
+iterare list --all              # Include cleaned up runs
+```
+
+### `iterare merge [RUN_NAME]`
+
+Merge a worktree branch back into the current branch.
+
+```bash
+iterare merge                   # Merge most recent run
+iterare merge refactor-abc12345 # Merge specific run
+```
+
+### `iterare cleanup [RUN_NAME]`
+
+Remove the git worktree and branch for a run. Log files are preserved.
+
+```bash
+iterare cleanup                 # Clean up most recent run
+iterare cleanup -y              # Skip confirmation
+iterare cleanup refactor-abc12345 -y  # Specific run
+```
+
+## Configuration
+
+### Project Structure
+
+After running `iterare init`, your project will contain:
+
+```
+.iterare/
+├── config.toml               # Main configuration
+├── Dockerfile                # Custom Docker image (optional)
+└── prompts/                  # Prompt files
+    └── example-prompt.md
+
+workspaces/                   # Git worktrees (gitignored)
+```
+
+### Config File (`.iterare/config.toml`)
+
+```toml
+[docker]
+image = "iterare-llm:latest"
+
+[session]
+shell = "/bin/bash"
+
+[claude]
+credentials_path = "~/.config/iterare"
+
+[firewall]
+# Additional domains to allow through the firewall.
+# Default domains (Anthropic API, GitHub, npm) are always included.
+allowed_domains = [
+    "pypi.org",
+    "files.pythonhosted.org",
+]
+```
+
+### Prompt Files
+
+Prompts are markdown files with optional YAML frontmatter:
+
+```markdown
+---
+workspace: my-feature
+branch: main
+---
+
+# Task Description
+
+Implement feature X by doing Y and Z.
+```
+
+Frontmatter fields:
+- **workspace** -- Worktree directory name (defaults to prompt filename)
+- **branch** -- Base branch for the worktree (defaults to current branch)
+
+### Environment Variables
+
+Pass host environment variables to the container with `--env`:
+
+```bash
+export PIP_INDEX_URL="https://pypi.company.internal/simple"
+iterare execute install-deps --env PIP_INDEX_URL
+```
+
+The flag accepts the variable *name* and reads the value from your shell. If a variable is not set,
+execution fails with an error.
+
+### Network Security
+
+The container runs behind a whitelist-based firewall using iptables:
+
+- All outbound traffic is blocked by default
+- Only whitelisted domains are allowed (resolved to IPs via DNS)
+- Default whitelist includes `api.anthropic.com`, GitHub APIs, npm registry
+- Additional domains are configured in `config.toml`
+
+This prevents the autonomous agent from exfiltrating code or downloading malicious packages from unapproved sources.
+
+### Execution Flow
+
+1. Load configuration from `.iterare/config.toml`
+2. Parse prompt file (extract frontmatter metadata)
+3. Create git worktree on a new branch
+4. Write `.claude-auto-config.json` and `.claude-prompt.md` to worktree
+5. Launch Docker container with worktree mounted at `/workspace`
+6. Container initializes firewall, then runs Claude Code autonomously
+7. Monitor via `iterare log -f`
+8. Merge results with `iterare merge`, clean up with `iterare cleanup`
+
+## Development
+
+```bash
+make sync       # Install dependencies
+make test       # Run tests (289 tests)
+make coverage   # Run tests with coverage report (100% coverage)
+make lint       # Check code style
+make format     # Auto-format code
+```
+
+## Troubleshooting
+
+### Docker image not found
+
+Build the images first:
+
+```bash
+make build-base
+make build
+```
+
+### Container already running
+
+```bash
+docker stop it-<run-name>
+docker rm it-<run-name>
+```
+
+### Credentials not found
+
+Run the credentials command to authenticate:
+
+```bash
+iterare credentials
+```
+
+### Network blocked in container
+
+Add the required domain to your `config.toml`:
+
+```toml
+[firewall]
+allowed_domains = ["example.com"]
+```