🔁 FingguLoopForge

One prompt. AI writes, tests, fixes, improves and ships — all by itself.
You don't write prompts. The AI writes its own prompts. Forever. Until it's done.

The Idea · How It Works · Quick Start · 8 Loop Types · Composer Presets · CLI

💡 The Idea

Traditional AI coding workflow:

You → write prompt → AI gives output → you review → you write next prompt → repeat 50 times

Loop Engineering with FingguLoopForge:

You → give ONE goal → AI loops forever → ships production-ready code → Done ✅

The AI writes its own next prompt based on what it just produced. It checks its own work. It finds its own bugs. It adds features by itself. You just watch the progress bar.

This is Loop Engineering — the new way to work with AI.

🔁 How It Works

┌─────────────────────────────────────────────────────────┐
│                    FingguLoopForge                       │
│                                                          │
│  Your ONE Goal                                           │
│       │                                                  │
│       ▼                                                  │
│  ┌─────────┐    ┌─────────┐    ┌──────────┐             │
│  │  Write  │───▶│  Check  │───▶│  Verify  │             │
│  │  Code   │    │  Output │    │  Quality │             │
│  └─────────┘    └─────────┘    └──────────┘             │
│       ▲                              │                   │
│       │         ┌─────────┐          │                   │
│       └─────────│  Self-  │◀─────────┘                   │
│                 │ Prompt  │  "Fix these issues,           │
│                 │  (AI)   │   add these features,         │
│                 └─────────┘   improve this section"       │
│                                                          │
│         Loops until: quality ≥ threshold                 │
│         OR: AI declares "I'm done"                       │
│         OR: max iterations reached                       │
└─────────────────────────────────────────────────────────┘

Key concepts from Loop Engineering:

Concept	What it does
Goal	Your single prompt — the only thing you write
Memory	Accumulates everything across all iterations
State	Current best version of the code
Verifier	Scores quality, finds issues, parses AI self-assessment
Self-Prompt	AI generates its own next task — no human needed
Stop Condition	Quality threshold, cost limit, stagnation detection, or AI declares done
Iterate	Loop back and do it again, better

🚀 Quick Start

pip install finggu-loopforge

Set a free API key (Gemini or Groq — both free):

export FINGGU_GEMINI_KEY=your_key_here   # free at aistudio.google.com
# OR
export FINGGU_GROQ_KEY=your_key_here    # free at console.groq.com

Run your first loop — one command:

finggu-loopforge run build "Build a FastAPI REST API with JWT auth and SQLite" --output api.py

Watch the AI loop:

✅ Providers ready: gemini
🎯 Goal: Build a FastAPI REST API with JWT auth and SQLite
🔁 Loop: BUILD | Max iterations: 15

  [01] [████████░░░░░░░░░░░░] 40% 8.2s
       ✓ Created basic FastAPI structure
  [02] [████████████░░░░░░░░] 62% 9.1s
       ✓ Added JWT authentication
       ✓ Created user model and endpoints
  [03] [████████████████░░░░] 79% 10.3s
       ✓ Added SQLite with SQLAlchemy
       ✓ Fixed token expiry handling
  [04] [██████████████████░░] 88% 7.8s
       ✓ Added input validation
       ✓ Added error handling middleware
  [05] [████████████████████] 93% 6.4s  ← DONE

✅ Loop build | Goal: Build a FastAPI REST API...
Iterations: 5 | Quality: 93% | Tokens: 18,432 | Cost: $0.0000 | Time: 41.8s
Exit: quality_threshold_met (93% >= 85%)

💾 Output saved to: api.py

Python API:

from finggu_loopforge.loops import FingguBuildLoop
from finggu_loopforge.providers import FingguAIProvider

provider = FingguAIProvider()
ai_fn = lambda system, prompt: provider.finggu_call(system, prompt).text

loop = FingguBuildLoop(ai_fn=ai_fn)
result = loop.finggu_run("Build a FastAPI REST API with JWT auth and SQLite")

print(result.final_output)     # Production-ready code
print(result.total_iterations) # How many loops it took
print(result.final_quality_score)  # 0.93

🔁 8 Loop Types

1. 🏗️ BuildLoop — Build from scratch

finggu-loopforge run build "Build a Telegram bot that sends daily crypto prices"
finggu-loopforge run build "Build a Django blog with auth, tags, and search"
finggu-loopforge run build "Build a CLI tool that compresses images in bulk"

FingguBuildLoop(ai_fn=ai_fn).finggu_run("Build a URL shortener in Flask")

AI writes code → reviews it → improves it → adds missing pieces → repeats until production-ready.

2. 🐛 DebugLoop — Fix all bugs autonomously

finggu-loopforge run debug "Fix all bugs in this code" --file broken_app.py

FingguDebugLoop(ai_fn=ai_fn).finggu_run("Fix all bugs", context=broken_code)

AI finds every bug → fixes them → checks the fix didn't introduce new bugs → loops until clean.

3. ✨ FeatureLoop — Auto-add missing features

finggu-loopforge run feature "Make this production-ready" --file basic_app.py

FingguFeatureLoop(ai_fn=ai_fn).finggu_run("Improve this app", context=existing_code)

You don't specify what to add. The AI scans your code, decides what's missing, and adds it.

4. 🔍 ReviewLoop — Deep quality audit

finggu-loopforge run review "Security and performance review" --file app.py

FingguReviewLoop(ai_fn=ai_fn).finggu_run("Review and fix", context=code)

Rates 0–100, categorizes issues by severity, fixes critical ones, explains every finding.

5. 🧪 TestLoop — Write and fix tests

finggu-loopforge run test "Write full test coverage" --file app.py --output tests.py

FingguTestLoop(ai_fn=ai_fn).finggu_run("100% test coverage", context=code)

Writes tests → simulates running them → fixes failures → adds edge cases → loops.

6. 📚 DocLoop — Generate full documentation

finggu-loopforge run doc "Document this entire project" --file app.py --output README.md

FingguDocLoop(ai_fn=ai_fn).finggu_run("Complete documentation", context=code)

Writes README, API reference, inline comments, usage examples — iterates until complete.

7. 🔧 RefactorLoop — Clean code structure

finggu-loopforge run refactor "Refactor to clean architecture" --file legacy.py

FingguRefactorLoop(ai_fn=ai_fn).finggu_run("Clean architecture", context=code)

Improves structure, naming, patterns — never breaks functionality. Shows before/after.

8. 🚢 DeployLoop — Production readiness

finggu-loopforge run deploy "Make this production-ready" --file app.py

FingguDeployLoop(ai_fn=ai_fn).finggu_run("Production ready", context=project)

Checks Dockerfile, env vars, CI/CD, health checks, security headers — fixes everything.

🔗 Composer Presets

Chain multiple loops into a single workflow. One goal → complete product.

# Full product from scratch
finggu-loopforge compose full_product "Build a SaaS dashboard with auth and billing"

# Ship fast (build + debug + deploy only)
finggu-loopforge compose ship_fast "Build a REST API for my mobile app"

# Improve existing project
finggu-loopforge compose existing_project "Improve my app" --file app.py

# Quality overhaul
finggu-loopforge compose quality_check "Fix everything wrong with this" --file legacy.py

Preset	Loop Chain
`full_product`	Build → Debug → Feature → Test → Doc → Deploy
`ship_fast`	Build → Debug → Deploy
`existing_project`	Review → Feature → Refactor → Test → Doc
`quality_check`	Review → Debug → Refactor → Test

Python API:

from finggu_loopforge.providers import FingguLoopComposer

composer = FingguLoopComposer(ai_fn=ai_fn)
result = composer.finggu_run_preset(
    preset="full_product",
    goal="Build a Razorpay payment integration for my PHP site",
)
print(result.finggu_summary())
print(result.final_output)

💰 Cost Estimator

Know your cost before spending a single token:

finggu-loopforge estimate build "Build a complete e-commerce platform" --max-iter 20

## 💰 FingguLoopForge Cost Estimate
Loop type: BUILD
Estimated iterations: ~10
Tokens per iteration: ~3,520
Total tokens: ~35,200

✅ Can run completely FREE using: gemini-flash (1M tokens/day), groq-llama3-70b (14.4K tokens/min)

Recommendation: Use gemini-flash — this loop will cost $0.00 on the free tier.

── Provider Comparison ──
  gemini-flash           $0.000000 (FREE)
  groq-llama3-70b        $0.000000 (FREE)
  openrouter-free        $0.000000 (FREE)
  mistral-small          $0.010560
  gpt-4o-mini            $0.021120
  claude-haiku           $0.044000

🎥 Loop Recorder

Record successful loops. Replay on new inputs instantly.

finggu-loopforge record list
finggu-loopforge record list --type build
finggu-loopforge record delete <id>

After any successful loop (quality ≥ 80%), it auto-saves the full prompt chain so you can replay that exact strategy on a new project — skipping warm-up iterations.

🖥️ CLI Reference

# Run a single loop
finggu-loopforge run build "Build a FastAPI app" --output app.py
finggu-loopforge run debug "Fix all bugs" --file broken.py --output fixed.py
finggu-loopforge run feature "Add missing features" --file app.py --max-iter 10
finggu-loopforge run test "Write tests" --file app.py --output tests.py --quality 0.90

# Compose multi-loop workflows
finggu-loopforge compose full_product "Build a todo SaaS"
finggu-loopforge compose ship_fast "Build an API" --max-iter 8 --output result.py

# Estimate cost before running
finggu-loopforge estimate build "Build a blog platform" --max-iter 15

# Recordings
finggu-loopforge record list
finggu-loopforge record list --type debug
finggu-loopforge record delete abc123def456

# Info
finggu-loopforge loops          # list all loop types and presets
finggu-loopforge version

⚙️ Configuration

# .env file — all optional, free tiers used first
FINGGU_GEMINI_KEY=...       # Free: aistudio.google.com
FINGGU_GROQ_KEY=...         # Free: console.groq.com
FINGGU_OPENROUTER_KEY=...   # Free tier: openrouter.ai
FINGGU_MISTRAL_KEY=...      # Paid
FINGGU_ANTHROPIC_KEY=...    # Paid (Claude Haiku)

Provider fallback order: Gemini → Groq → OpenRouter → Mistral → Anthropic

Free providers tried first. Paid providers only if all free ones fail or are unconfigured.

🏗️ Architecture

finggu_loopforge/
├── core/
│   └── engine.py          ← FingguLoopEngine: the state machine
│                             FingguLoopMemory: cross-iteration memory
│                             FingguLoopIteration: one loop step
│                             finggu_generate_next_prompt(): self-prompting
├── loops/
│   └── __init__.py        ← FingguBuildLoop, FingguDebugLoop, ...8 types
├── providers/
│   ├── finggu_ai_provider.py    ← Multi-provider fallback chain
│   ├── finggu_composer.py       ← FingguLoopComposer + presets
│   ├── finggu_recorder.py       ← Record + replay successful loops
│   └── finggu_cost_estimator.py ← Estimate before running
└── cli.py                 ← finggu-loopforge CLI

🛠️ Development

git clone https://github.com/sudarshanpjadhav/finggu-loopforge
cd finggu-loopforge
pip install -e ".[dev]"
pytest tests/

Writing a Custom Loop

from finggu_loopforge.core import FingguLoopEngine, FingguLoopType

def fingguFn_myVerifier(output: str, goal: str) -> dict:
    """Custom verifier — your own quality logic."""
    fingguVar_score = 0.9 if "async" in output else 0.5
    return {
        "score": fingguVar_score,
        "issues": [] if fingguVar_score > 0.8 else ["Missing async/await patterns"],
        "improvements": ["Added async support"] if fingguVar_score > 0.8 else [],
    }

engine = FingguLoopEngine(
    ai_fn=my_ai_fn,
    verify_fn=fingguFn_myVerifier,
    on_iteration=lambda it: print(f"Iter {it.iteration_number}: {it.quality_score:.0%}"),
    max_iterations=10,
    quality_threshold=0.88,
)
result = engine.finggu_run(
    goal="Build an async FastAPI service",
    loop_type=FingguLoopType.BUILD,
)

🤝 Contributing

All code must follow Finggu naming conventions:

Classes → FingguXxx · Functions → finggu_xxx / fingguFn_xxx
Constants → FINGGU_XXX · Variables → fingguVar_xxx

See CONTRIBUTING.md for full guide.

📬 Contact

Sudarshan Jadhav — Founder, Finggu

🌐 finggu.com · 💼 @sudarshanpjadhav · 📧 hello@finggu.com

License

_{Built with ❤️ in Pimpri, Maharashtra, India 🇮🇳}
_{⭐ Star this repo if it changed how you think about AI prompting!}

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
examples		examples
finggu_loopforge		finggu_loopforge
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🔁 FingguLoopForge

💡 The Idea

🔁 How It Works

🚀 Quick Start

🔁 8 Loop Types

1. 🏗️ BuildLoop — Build from scratch

2. 🐛 DebugLoop — Fix all bugs autonomously

3. ✨ FeatureLoop — Auto-add missing features

4. 🔍 ReviewLoop — Deep quality audit

5. 🧪 TestLoop — Write and fix tests

6. 📚 DocLoop — Generate full documentation

7. 🔧 RefactorLoop — Clean code structure

8. 🚢 DeployLoop — Production readiness

🔗 Composer Presets

💰 Cost Estimator

🎥 Loop Recorder

🖥️ CLI Reference

⚙️ Configuration

🏗️ Architecture

🛠️ Development

Writing a Custom Loop

🤝 Contributing

📬 Contact

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🔁 FingguLoopForge

💡 The Idea

🔁 How It Works

🚀 Quick Start

🔁 8 Loop Types

1. 🏗️ BuildLoop — Build from scratch

2. 🐛 DebugLoop — Fix all bugs autonomously

3. ✨ FeatureLoop — Auto-add missing features

4. 🔍 ReviewLoop — Deep quality audit

5. 🧪 TestLoop — Write and fix tests

6. 📚 DocLoop — Generate full documentation

7. 🔧 RefactorLoop — Clean code structure

8. 🚢 DeployLoop — Production readiness

🔗 Composer Presets

💰 Cost Estimator

🎥 Loop Recorder

🖥️ CLI Reference

⚙️ Configuration

🏗️ Architecture

🛠️ Development

Writing a Custom Loop

🤝 Contributing

📬 Contact

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages