Metadata-Version: 2.4
Name: loop-prompting
Version: 2.1.2
Summary: Universal Loop Engineering System — iterative AI execution for any LLM provider with tool support
Author-email: Shrixtacy <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/shrixtacy/Loop-Engine-Shrixtacy
Project-URL: Repository, https://github.com/shrixtacy/Loop-Engine-Shrixtacy
Project-URL: Issues, https://github.com/shrixtacy/Loop-Engine-Shrixtacy/issues
Keywords: ai,llm,loop-engineering,code-generation,anthropic,openai,claude,gpt-4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: google
Requires-Dist: google-generativeai>=0.3.0; extra == "google"
Provides-Extra: aws
Requires-Dist: boto3>=1.26.0; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-ai-inference>=1.0.0; extra == "azure"
Provides-Extra: all
Requires-Dist: google-generativeai>=0.3.0; extra == "all"
Requires-Dist: boto3>=1.26.0; extra == "all"
Requires-Dist: azure-ai-inference>=1.0.0; extra == "all"
Dynamic: license-file

<div align="center">

# 🔄 LOOP ENGINE

<img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&weight=600&size=28&pause=1000&color=6366F1&center=true&vCenter=true&repeat=false&width=600&lines=Universal+AI+Loop+Engine" alt="Typing SVG" />

### **Generate → Evaluate → Refine → Converge**

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
[![Providers](https://img.shields.io/badge/Providers-9-purple?style=for-the-badge)](README.md)
[![Free](https://img.shields.io/badge/Free_Tier-Available-success?style=for-the-badge)](README.md)

[![Anthropic](https://img.shields.io/badge/Anthropic-Claude-orange?style=flat-square)](https://www.anthropic.com/)
[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--4-green?style=flat-square)](https://openai.com/)
[![Google](https://img.shields.io/badge/Google-Gemini-blue?style=flat-square)](https://deepmind.google/technologies/gemini/)
[![Groq](https://img.shields.io/badge/Groq-Lightning_Fast-red?style=flat-square)](https://groq.com/)
[![OpenRouter](https://img.shields.io/badge/OpenRouter-200%2B_Models-purple?style=flat-square)](https://openrouter.ai/)
[![Ollama](https://img.shields.io/badge/Ollama-Local_Free-black?style=flat-square)](https://ollama.ai/)

---

### **Perfect for** • Claude • Kiro • Cursor • Codex • LangChain • n8n • Any AI Workflow

</div>

---

## 🎬 See It In Action

```python
from loop_engine import run_loop

result = run_loop(
    task="Create a FastAPI user auth endpoint",
    success_criteria="JWT tokens, password hashing, type hints",
    failure_criteria="Hardcoded secrets, no validation",
    max_iterations=5
)
# ✨ Automatically iterates until perfect!
```

---

## 🔥 How It Works

<div align="center">

<img src="assets/loop-flow.svg" alt="Loop Engine Flow Animation" width="800"/>

</div>

### ⚡ Why Loop Engine Beats Single-Shot AI

<div align="center">

| 🤖 Traditional AI | 🔄 Loop Engine |
|:-----------------|:--------------|
| One attempt only | ✅ Iterates until perfect |
| Manual re-prompting | ✅ Automatic refinement |
| No quality control | ✅ Built-in scoring (1-10) |
| Often misses requirements | ✅ Checks YOUR criteria |
| Generic output | ✅ Converges to YOUR standards |
| Unsafe code changes | ✅ Git isolation (optional sandbox) |
| No validation | ✅ Test execution integration |

</div>

---

## Install

```bash
pip install loop-engine[all]  # All providers
# or
pip install loop-engine       # Just core
```

Set API key (any provider):
```bash
export ANTHROPIC_API_KEY="your_key"
# or OPENAI_API_KEY, GOOGLE_API_KEY, etc.
```

---

## Quick Start

### CLI
```bash
loop-engine run  # Interactive mode
```

### Python
```python
from loop_engine import run_loop

result = run_loop(
    task="Create a FastAPI user auth endpoint",
    success_criteria="JWT tokens, password hashing, type hints, error handling",
    failure_criteria="Hardcoded secrets, no validation, missing docstrings",
    max_iterations=5,
    provider="anthropic"  # auto-detects if not specified
)

print(result.final.output)
print(f"Quality: {result.final.quality_score}/10")
```

---

## Supported Providers

| Provider | Models | Setup |
|----------|--------|-------|
| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus | `ANTHROPIC_API_KEY` |
| **OpenAI** | GPT-4, GPT-4o | `OPENAI_API_KEY` |
| **Google** | Gemini 2.0 Flash, Gemini 1.5 Pro | `GOOGLE_API_KEY` |
| **OpenRouter** | 200+ models | `OPENROUTER_API_KEY` |
| **Groq** | Llama 3.3, Mixtral (ultra-fast) | `GROQ_API_KEY` |
| **DeepSeek** | DeepSeek Chat, DeepSeek Coder | `DEEPSEEK_API_KEY` |
| **AWS Bedrock** | Claude, Llama on AWS | AWS credentials |
| **Azure OpenAI** | GPT-4 on Azure | `AZURE_OPENAI_API_KEY` |
| **Ollama** | Local models (free) | Ollama running locally |

---

## Built-in Tools

Enable with `--tools` or `enable_tools=True`:

- `read_file` - Read file contents
- `write_file` - Write to files
- `list_directory` - List directory contents
- `execute_command` - Run shell commands
- `search_files` - Find files by pattern
- `create_directory` - Create directories

### Test Execution (NEW!)

Run tests automatically during iterations:

```python
result = run_loop(
    task="Write a function to validate emails",
    success_criteria="Regex validation, type hints, passes tests",
    failure_criteria="No validation, tests fail",
    test_command="pytest tests/test_email.py",  # ✨ NEW!
    max_iterations=5
)
# Tests run each iteration - quality score boosted if they pass!
```

### Git Isolation (NEW!)

Safe code modifications in isolated environment:

```python
result = run_loop(
    task="Refactor auth module to use async/await",
    success_criteria="All async, passes tests",
    failure_criteria="Breaking changes",
    enable_tools=True,
    test_command="pytest tests/",
    use_isolation=True,  # 🔒 Safe isolation!
    isolation_path=".",  # Your git repo
    max_iterations=8
)
# Creates temporary worktree → AI edits → Tests → Merges if good!
```

**How Git Isolation Works:**
1. Creates temporary copy (worktree) of your code
2. AI modifies the COPY, not your real files
3. Runs tests in isolation
4. If successful → merges back to main
5. If fails → deletes copy, your code untouched

**When to use:**
- ✅ Automated refactoring of production code
- ✅ Large multi-file changes
- ✅ When you want safety guarantees
- ❌ Simple code generation (overkill)

### Custom Tools

```python
from loop_engine import register_custom_tool

def my_tool(arg: str) -> dict:
    return {"result": f"Processed: {arg}"}

register_custom_tool(
    name="my_tool",
    func=my_tool,
    definition={
        "name": "my_tool",
        "description": "My custom tool",
        "parameters": {
            "type": "object",
            "properties": {
                "arg": {"type": "string", "description": "Argument"}
            },
            "required": ["arg"]
        }
    }
)
```

---

## Examples

Check `/examples` directory:
- `basic_example.py` - Simple usage (2 seconds)
- `tools_example.py` - File operations with tools
- `complete_system_test.py` - Full system validation

---

## Best Practices

### For Simple Tasks (Fast)
```python
# Just basic loop - 2-5 seconds per iteration
run_loop(task, success, failure, max_iterations=3)
```

### For Code with Tests
```python
# Add test execution for validation
run_loop(
    task, success, failure,
    test_command="pytest tests/",
    max_iterations=5
)
```

### For Production Code (Maximum Safety)
```python
# Full safety: isolation + tests
run_loop(
    task, success, failure,
    enable_tools=True,
    test_command="pytest tests/",
    use_isolation=True,  # Safe sandbox
    isolation_path=".",
    max_iterations=10
)
```

---

## Tips for Best Results

1. **Be specific**: "TypeScript, uses async/await, <200 lines" > "good code"
2. **Set hard failures**: "No eval(), no hardcoded secrets"
3. **Start with 3-5 iterations**: Most tasks converge quickly
4. **Use tools for file ops**: Enable tools when working with existing code
5. **Add context**: Provide project structure, patterns, requirements

---

## Configuration

Create `~/.loop-engine/config.yaml`:

```yaml
max_iterations: 5
convergence_threshold: 8
provider: auto

tools:
  enabled: false
  allowed_tools: [all]

providers:
  anthropic:
    model: claude-sonnet-4-20250514
    max_tokens: 4000
```

Or use `loop-engine init` to generate automatically.

---

## License

MIT License - see LICENSE file

---

## Support

- **Examples**: `/examples` directory
- **Issues**: GitHub Issues
- **Config**: `loop-engine status` to see current setup
