loopllm 0.7.0__tar.gz

loopllm-0.7.0/.cursor/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "loopllm": {
+      "command": "/home/azank/loop-llm/.venv/bin/loopllm",
+      "args": ["mcp-server", "--provider", "agent"],
+      "env": {
+        "LOOPLLM_MODEL": "agent"
+      }
+    }
+  }
+}

loopllm-0.7.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem with loopllm
+title: "bug: "
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what went wrong.
+
+**To reproduce**
+Steps or a minimal snippet (CLI command, MCP tool call, or Python):
+
+```
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- loopllm version: (`pip show loopllm`)
+- Python version:
+- OS:
+- Provider: agent / ollama / openrouter / mock
+- IDE (if MCP): VS Code / Cursor / other
+
+**Logs / output**
+Paste any relevant error output.

loopllm-0.7.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for loopllm
+title: "feat: "
+labels: enhancement
+---
+
+**What problem does this solve?**
+A clear description of the use case or pain point.
+
+**Proposed solution**
+What you'd like to happen (a new tool, config, provider, etc.).
+
+**Alternatives considered**
+Any workarounds or other approaches you've thought about.
+
+**Additional context**
+Links, references, or examples.

loopllm-0.7.0/.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+# PromptLoop — Agent Instructions
+
+PromptLoop is an MCP server for prompt quality, refinement loops, and Conservative
+Dual-Verify agent-loop control. See [README.md](../README.md) for architecture,
+tools, and examples.
+
+---
+
+## Required on every message
+
+Always call `loopllm_intercept` with the user's exact prompt before responding. Do not skip this even for simple requests.
+
+```
+loopllm_intercept(prompt="<user's exact message>")
+```
+
+Act on the returned `route`: `elicit` → clarify first | `decompose` → plan first | `refine` → proceed directly.
+
+For non-trivial tasks use `loopllm_run_pipeline` as the entry point.
+
+For multi-step iterative work, use `loopllm_loop_start` → `loopllm_loop_step(step_output=...)` → `loopllm_loop_end`. Submit step artifacts; do not self-grade.

loopllm-0.7.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Changes
+
+<!-- Bullet the key changes. -->
+
+## Verification
+
+- [ ] `python -m pytest tests/ -q` passes
+- [ ] `ruff check src/ tests/` clean
+- [ ] `mypy --strict src/loopllm/` clean
+- [ ] Added/updated tests for new behavior
+- [ ] Updated README / CHANGELOG if user-facing
+
+## Notes
+
+<!-- Anything reviewers should know (trade-offs, follow-ups). -->

loopllm-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: mypy --strict src/loopllm/
+
+      - name: Run tests
+        run: pytest tests/ -v

loopllm-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+
+      - name: Verify install
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          pip install "loopllm[mcp]==${VERSION}"
+          python -c "import loopllm; print(loopllm.__version__)"

loopllm-0.7.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/*
+!.vscode/mcp.json
+!.vscode/settings.json
+.cursor/rules/
+*.swp
+*.swo
+
+# Generated docs build output (hand-written docs/ are tracked)
+docs/_build/
+
+# mypy
+.mypy_cache/
+
+# pytest
+.pytest_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Priors data
+priors.json
+
+# VS Code extension build artifacts
+vscode-loopllm/out/
+*.vsix
+
+# Scratch / template holder (keep dir, ignore contents)
+_scratch/*
+!_scratch/.gitkeep

loopllm-0.7.0/.vscode/mcp.json

@@ -0,0 +1,12 @@
+{
+  "servers": {
+    "loopllm": {
+      "type": "stdio",
+      "command": "loopllm",
+      "args": ["mcp-server", "--provider", "agent"],
+      "env": {
+        "LOOPLLM_MODEL": "agent"
+      }
+    }
+  }
+}

loopllm-0.7.0/.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  "github.copilot.chat.codeGeneration.instructions": [
+    { "file": ".github/copilot-instructions.md" },
+    { "text": "Always call loopllm_intercept with the user's prompt before responding. This logs the prompt, scores quality, and returns routing guidance. Do not skip this even for simple requests." }
+  ],
+  "github.copilot.chat.reviewSelection.instructions": [
+    { "file": ".github/copilot-instructions.md" },
+    { "text": "Always call loopllm_intercept with the user's prompt before responding." }
+  ],
+  "github.copilot.chat.testGeneration.instructions": [
+    { "file": ".github/copilot-instructions.md" }
+  ],
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    { "text": "Always call loopllm_intercept with the user's prompt before responding." }
+  ]
+}

loopllm-0.7.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.0] — 2026-06-22
+
+### Added
+- **Conservative Dual-Verify (CDV) for agent loops.** Agents submit `step_output`
+  artifacts; the MCP server scores each step through two independent channels:
+  - **Channel A:** deterministic evaluators (regex, JSON, completeness, composite).
+  - **Channel B:** separate critic via MCP sampling (verifier hat).
+  - **Final score:** `min(channel_a, channel_b)` — the stricter channel wins.
+- New modules: `src/loopllm/step_scorer.py`, `src/loopllm/guards.py`,
+  `src/loopllm/evaluator_factory.py`.
+- Composable **guard stack** on verified scores: timeout, token budget, output-repeat,
+  plateau, threshold, Bayesian ROI, max steps, budget exhausted.
+- `loopllm_loop_start` accepts verifier recipe (`evaluator_type`, `quality_criteria`,
+  `required_patterns`, `max_wall_ms`, `max_tokens`).
+- `loopllm_loop_step` is now async and artifact-primary (`step_output`); legacy
+  `score` self-report still works with deprecation warning.
+- Verdict JSON exposes `channel_a_score`, `channel_b_score`, `score_source`,
+  `deficiencies` for demos and debugging.
+- Tests: `tests/test_step_scorer.py`, `tests/test_guards.py` (CDV inflation-block test).
+- Package exports: `DualVerifyScore`, `conservative_dual_verify`, `GuardStack`.
+
+### Changed
+- `AgentLoopController` uses `GuardStack` instead of inline `_decide` logic.
+- `AgentLoopSession` stores verifier config, step artifacts, token accumulators.
+- `CallObservation.prompt_tokens` / `completion_tokens` populated on `loop_end`.
+- README and demo doc reframed around Conservative Dual-Verify.
+
+## [0.6.0] — 2026-06-21
+
+### Added
+- **Adaptive agent loops.** A new `AgentLoopController` (`src/loopllm/agent_loop.py`)
+  brings the Bayesian early-exit machinery to an agent's own plan → act → observe
+  loop. Lifecycle: `start` → `step` → `end`.
+  - Suggests a learned step budget and quality threshold per `task_type` from
+    `AdaptivePriors` — no training data required.
+  - Returns a continue/stop verdict on each step (goal reached, plateau, low
+    expected ROI, or budget exhausted) using the same logic as
+    `BayesianExitCondition`.
+  - Records every completed loop so future budgets sharpen over time.
+- Four new MCP tools (now 28 total): `loopllm_loop_start`, `loopllm_loop_step`,
+  `loopllm_loop_end`, `loopllm_loop_status`.
+- `AgentLoopController` and `AgentLoopSession` exported from the package root.
+- Runnable example `examples/agent_loop.py` and walkthrough
+  `docs/demo/agent_loop_demo.md`.
+- Reproducible benchmark `benchmarks/adaptive_vs_fixed.py` comparing adaptive
+  stopping against fixed/threshold strategies (adaptive: ~41% fewer steps than a
+  fixed 6-step budget at 99.7% goal-reach).
+- Tests: `tests/test_agent_loop.py`, `tests/test_benchmark.py`.
+- Repo hygiene: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, GitHub issue/PR
+  templates, `[project.urls]` + classifiers in `pyproject.toml`, CI badge, and a
+  committed `.cursor/mcp.json` for Cursor auto-detection.
+
+### Changed
+- README deduplicated and corrected (28 tools, 204 tests, schema v4); added
+  "Adaptive agent loops" and "Benchmark" sections.
+
+### Fixed
+- Version drift: `__init__.__version__` now matches `pyproject.toml`.
+
+## [0.5.0]
+
+### Added
+- Online SGD weight learning and Thompson Sampling for question ordering
+  (SQLite schema v4).
+- Prompt Lab sidebar panel in the VS Code extension.
+- Expanded MCP surface to 24 tools, MCP Sampling, and persistent confidence-gated
+  plans.
+
+## [0.4.0]
+
+### Added
+- Prompt quality scoring system (5 deterministic dimensions, grade A–F) and the
+  initial VS Code extension.

loopllm-0.7.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers responsible for enforcement via the repository's
+issue tracker or a private channel where available. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

loopllm-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to PromptLoop (`loopllm`)
+
+Thanks for your interest in improving PromptLoop. This guide covers local setup,
+the branch/commit conventions, and the checks your change must pass.
+
+## Local setup
+
+```bash
+git clone https://github.com/azank1/loop-llm
+cd loop-llm
+pip install -e ".[dev]"
+python -m pytest tests/ -q          # 219 tests (215 pass, 4 integration skipped)
+```
+
+## Branch naming convention
+
+Branches follow a compact `<initials>/<type>/<short>` scheme:
+
+- `<initials>` — the author's initials (e.g. `az`)
+- `<type>` — `ft` (feature), `fix`, `chore`, `docs`, `refactor`, `test`
+- `<short>` — a terse, hyphenated descriptor
+
+Examples: `az/ft/cdv-v07`, `az/fix/store-migration`, `az/docs/readme`.
+
+Do **not** include tool, assistant, or AI names in branch names or commit
+metadata.
+
+## Authorship
+
+All commits on this repository are authored by `azank1 <azanhyder49@gmail.com>`.
+Use squash-merge PRs into `main`; delete feature branches after merge.
+
+## Commits & pull requests
+
+- Use clear, imperative commit subjects (e.g. `feat: adaptive agent loops`).
+- Keep commits focused; add tests for any new tool or behavior under `tests/`.
+- Open PRs against `main`. CI (Python 3.11–3.13) must be green.
+
+## Checks (run before pushing)
+
+```bash
+ruff check src/ tests/
+mypy --strict src/loopllm/
+python -m pytest tests/ -q
+```
+
+## Where things live
+
+| Area | File |
+|---|---|
+| Core refinement loop | `src/loopllm/engine.py` |
+| Bayesian priors / learning | `src/loopllm/priors.py` |
+| Adaptive agent loops | `src/loopllm/agent_loop.py` |
+| Conservative Dual-Verify scoring | `src/loopllm/step_scorer.py` |
+| Agent-loop guard stack | `src/loopllm/guards.py` |
+| Evaluator factory | `src/loopllm/evaluator_factory.py` |
+| Bayesian early stopping | `src/loopllm/adaptive_exit.py` |
+| MCP tools (28) | `src/loopllm/mcp_server.py` |
+| SQLite persistence (schema v4) | `src/loopllm/store.py` |
+| CLI | `src/loopllm/cli.py` |
+| Providers (agent/ollama/openrouter/mock) | `src/loopllm/providers/` |
+
+By contributing, you agree your contributions are licensed under the project's
+[MIT License](LICENSE).

loopllm-0.7.0/LICENSE

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