coding-guardrails 0.1.0__tar.gz

coding_guardrails-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv
+          uv pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: .venv/bin/python -m pytest tests/unit/ -v --tb=short
+
+      - name: Run lint
+        run: |
+          .venv/bin/python -m ruff check src/ tests/ || true
+        continue-on-error: true
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: |
+          uv venv .venv
+          uv pip install dist/*.whl --python .venv/bin/python
+          .venv/bin/coding-guardrails --version
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

coding_guardrails-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Vendored (dev only)
+.vendors/
+
+# Secrets
+.env
+.env.*
+
+# Models (too large for git)
+*.gguf
+models/*.gguf
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml

coding_guardrails-0.1.0/Dockerfile

@@ -0,0 +1,49 @@
+# Multi-stage build for coding-guardrails
+# Stage 1: Build the package
+# Stage 2: Runtime image with llama.cpp
+
+# ── Build stage ──
+FROM python:3.12-slim AS builder
+
+WORKDIR /build
+
+# Install build deps
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ src/
+COPY configs/ configs/
+
+RUN pip install --no-cache-dir --upgrade pip build && \
+    python -m build --wheel
+
+# ── Runtime stage ──
+FROM python:3.12-slim AS runtime
+
+LABEL org.opencontainers.image.source="https://github.com/stawils/coding-guardrails"
+LABEL org.opencontainers.image.description="Safe, reliable local coding agent backend"
+LABEL org.opencontainers.image.licenses="MIT"
+
+# Non-root user
+RUN groupadd -r cg && useradd -r -g cg -d /home/cg -s /sbin/nologin cg
+
+# Install the wheel from builder
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -rf /tmp/*.whl
+
+# Config and working dirs
+COPY --chown=cg:cg configs/guardrail-config.yaml /etc/coding-guardrails/config.yaml
+RUN mkdir -p /home/cg/models && chown cg:cg /home/cg/models
+
+USER cg
+WORKDIR /home/cg
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8081/health')" || exit 1
+
+# Default config
+ENV CODING_GUARDRAILS_CONFIG=/etc/coding-guardrails/config.yaml
+
+EXPOSE 8081
+
+ENTRYPOINT ["coding-guardrails"]
+CMD ["serve", "--backend-url", "http://localhost:8080", "--model", "default", "--port", "8081"]

coding_guardrails-0.1.0/LICENSE

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

coding_guardrails-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: coding-guardrails
+Version: 0.1.0
+Summary: Safe, reliable local coding agent backend. Forge + coding-specific guardrails.
+Author: Stawils
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,coding,guardrails,llm,local-models,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: forge-guardrails>=0.7.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# coding-guardrails
+
+> Safe, reliable local coding agent backend. Open-source, pip-installable.
+
+**coding-guardrails** is a proxy that sits between your coding agent and a local LLM,
+adding two layers of protection:
+
+1. **Forge (Layer 1)** — Rescue parsing, retries, validation. Makes local models
+   actually work for tool calling.
+2. **Coding Guardrails (Layer 2)** — Read-before-edit, path safety, command blocking,
+   secret masking, test-after-change suggestions.
+
+One command to go from "I have a GPU" to "I have a safe local coding agent backend."
+
+## Quick Start
+
+```bash
+# Install
+pip install coding-guardrails
+
+# Start llama-server (your local LLM backend)
+llama-server -m model.gguf --jinja --fit on --flash-attn auto \
+  --port 8080 -c 16384 --spec-type draft-mtp -np 1
+
+# Start the proxy
+coding-guardrails serve \
+  --backend-url http://localhost:8080 \
+  --model Qwen3.6-35B-A3B-UD-Q3_K_M \
+  --port 8081
+
+# Point your agent at http://localhost:8081/v1
+```
+
+That's it. Your agent sees a standard OpenAI-compatible API.
+
+## What It Blocks
+
+| Rule | Blocks | Example |
+|---|---|---|
+| **Path safety** | Reads/writes outside workspace | `read_file("/etc/passwd")` ❌ |
+| **Command safety** | Destructive shell commands | `bash("rm -rf /")` ❌ |
+| **Secret detection** | API keys, tokens, private keys | `bash("export AWS_SECRET_ACCESS_KEY=...")` ❌ |
+| **Prerequisites** | Edit before read (soft nudge) | `edit_file()` without `read_file()` ⚠️ |
+| **Sequencing** | Missing test runs (soft nudge) | Edit without `pytest` ⚠️ |
+| **Tool resolution** | Empty/error results (soft nudge) | Tool returns `""` ⚠️ |
+
+All rules are configurable. See [docs/rules.md](docs/rules.md).
+
+## Supported Models
+
+Optimized for the **Qwen 3.6** family with llama-server:
+
+| Model | VRAM | Context | SWE-bench |
+|---|---|---|---|
+| **Qwen3.6-35B-A3B Q3_K_M** ⭐ | 21.6 GB | 16K | 73.4% |
+| Qwen3.6-27B Q4_K_M | 22.0 GB | 4K | 77.2% |
+
+Works with any OpenAI-compatible backend. See [docs/models.md](docs/models.md).
+
+## Agent Setup
+
+Point any OpenAI-compatible agent at `http://localhost:8081/v1`:
+
+- **Pi** — `api_base: "http://localhost:8081/v1"`
+- **Aider** — `OPENAI_API_BASE=http://localhost:8081/v1`
+- **Continue** — `"apiBase": "http://localhost:8081/v1"`
+- **Cline / Roo** — set API base in settings
+
+See [docs/agents.md](docs/agents.md) for detailed setup guides.
+
+## Configuration
+
+Create a `guardrail-config.yaml` (or use defaults):
+
+```yaml
+path_safety:
+  enabled: true
+  blocked_prefixes: ["/etc/", "/sys/", "/proc/"]
+
+command_safety:
+  enabled: true
+  strength: hard  # hard = block, soft = warn
+
+secrets:
+  enabled: true
+  strength: hard
+  mask_value: "[REDACTED]"
+```
+
+Pass with `--config guardrail-config.yaml`.
+
+## Architecture
+
+```
+Agent → coding-guardrails (:8081) → llama-server (:8080) → GPU
+            │
+            ├─ Layer 1 (Forge): rescue, validate, retry
+            └─ Layer 2 (Guardrails): 6 safety rules
+```
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Docker
+
+```bash
+docker compose up
+```
+
+Or standalone:
+
+```bash
+docker run -p 8081:8081 ghcr.io/stawils/coding-guardrails:latest \
+  serve --backend-url http://host.docker.internal:8080 --model your-model
+```
+
+## Eval
+
+```bash
+coding-guardrails eval --backend-url http://localhost:8081
+```
+
+Runs scenarios from `eval/scenarios/` and reports pass/fail by category.
+
+## Development
+
+```bash
+git clone https://github.com/stawils/coding-guardrails.git
+cd coding-guardrails
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/ -v
+
+# Run against live backend
+pytest tests/integration/ -v -m integration
+```
+
+## License
+
+MIT

coding_guardrails-0.1.0/README.md

@@ -0,0 +1,141 @@
+# coding-guardrails
+
+> Safe, reliable local coding agent backend. Open-source, pip-installable.
+
+**coding-guardrails** is a proxy that sits between your coding agent and a local LLM,
+adding two layers of protection:
+
+1. **Forge (Layer 1)** — Rescue parsing, retries, validation. Makes local models
+   actually work for tool calling.
+2. **Coding Guardrails (Layer 2)** — Read-before-edit, path safety, command blocking,
+   secret masking, test-after-change suggestions.
+
+One command to go from "I have a GPU" to "I have a safe local coding agent backend."
+
+## Quick Start
+
+```bash
+# Install
+pip install coding-guardrails
+
+# Start llama-server (your local LLM backend)
+llama-server -m model.gguf --jinja --fit on --flash-attn auto \
+  --port 8080 -c 16384 --spec-type draft-mtp -np 1
+
+# Start the proxy
+coding-guardrails serve \
+  --backend-url http://localhost:8080 \
+  --model Qwen3.6-35B-A3B-UD-Q3_K_M \
+  --port 8081
+
+# Point your agent at http://localhost:8081/v1
+```
+
+That's it. Your agent sees a standard OpenAI-compatible API.
+
+## What It Blocks
+
+| Rule | Blocks | Example |
+|---|---|---|
+| **Path safety** | Reads/writes outside workspace | `read_file("/etc/passwd")` ❌ |
+| **Command safety** | Destructive shell commands | `bash("rm -rf /")` ❌ |
+| **Secret detection** | API keys, tokens, private keys | `bash("export AWS_SECRET_ACCESS_KEY=...")` ❌ |
+| **Prerequisites** | Edit before read (soft nudge) | `edit_file()` without `read_file()` ⚠️ |
+| **Sequencing** | Missing test runs (soft nudge) | Edit without `pytest` ⚠️ |
+| **Tool resolution** | Empty/error results (soft nudge) | Tool returns `""` ⚠️ |
+
+All rules are configurable. See [docs/rules.md](docs/rules.md).
+
+## Supported Models
+
+Optimized for the **Qwen 3.6** family with llama-server:
+
+| Model | VRAM | Context | SWE-bench |
+|---|---|---|---|
+| **Qwen3.6-35B-A3B Q3_K_M** ⭐ | 21.6 GB | 16K | 73.4% |
+| Qwen3.6-27B Q4_K_M | 22.0 GB | 4K | 77.2% |
+
+Works with any OpenAI-compatible backend. See [docs/models.md](docs/models.md).
+
+## Agent Setup
+
+Point any OpenAI-compatible agent at `http://localhost:8081/v1`:
+
+- **Pi** — `api_base: "http://localhost:8081/v1"`
+- **Aider** — `OPENAI_API_BASE=http://localhost:8081/v1`
+- **Continue** — `"apiBase": "http://localhost:8081/v1"`
+- **Cline / Roo** — set API base in settings
+
+See [docs/agents.md](docs/agents.md) for detailed setup guides.
+
+## Configuration
+
+Create a `guardrail-config.yaml` (or use defaults):
+
+```yaml
+path_safety:
+  enabled: true
+  blocked_prefixes: ["/etc/", "/sys/", "/proc/"]
+
+command_safety:
+  enabled: true
+  strength: hard  # hard = block, soft = warn
+
+secrets:
+  enabled: true
+  strength: hard
+  mask_value: "[REDACTED]"
+```
+
+Pass with `--config guardrail-config.yaml`.
+
+## Architecture
+
+```
+Agent → coding-guardrails (:8081) → llama-server (:8080) → GPU
+            │
+            ├─ Layer 1 (Forge): rescue, validate, retry
+            └─ Layer 2 (Guardrails): 6 safety rules
+```
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Docker
+
+```bash
+docker compose up
+```
+
+Or standalone:
+
+```bash
+docker run -p 8081:8081 ghcr.io/stawils/coding-guardrails:latest \
+  serve --backend-url http://host.docker.internal:8080 --model your-model
+```
+
+## Eval
+
+```bash
+coding-guardrails eval --backend-url http://localhost:8081
+```
+
+Runs scenarios from `eval/scenarios/` and reports pass/fail by category.
+
+## Development
+
+```bash
+git clone https://github.com/stawils/coding-guardrails.git
+cd coding-guardrails
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/ -v
+
+# Run against live backend
+pytest tests/integration/ -v -m integration
+```
+
+## License
+
+MIT

coding_guardrails-0.1.0/configs/aider.yaml

@@ -0,0 +1,11 @@
+# Aider configuration
+# Point Aider at the coding-guardrails proxy.
+#
+# Usage:
+#   1. Start llama-server on :8080
+#   2. Start proxy: coding-guardrails serve --backend-url http://localhost:8080 --model Qwen3.6-35B-A3B-UD-Q3_K_M
+#   3. Run aider:   aider --model openai/Qwen3.6-35B-A3B-UD-Q3_K_M --api-base http://localhost:8081
+
+# In your .aider.conf.yml or environment:
+# OPENAI_API_BASE=http://localhost:8081/v1
+# OPENAI_API_KEY=not-needed

coding_guardrails-0.1.0/configs/guardrail-config.yaml

@@ -0,0 +1,75 @@
+# Default guardrail configuration
+# All rules enabled with sensible defaults.
+
+# Workspace root — path safety restricts file operations to this tree.
+# Set to "." for current directory, or an absolute path.
+workspace: "."
+
+path_safety:
+  enabled: true
+  # Paths that are always blocked (even inside workspace)
+  blocked_prefixes:
+    - "/etc/"
+    - "/sys/"
+    - "/proc/"
+    - "/boot/"
+    - "/dev/"
+    - "/root/"
+    - "/var/log/"
+  # Additional allowed paths outside workspace (e.g. system includes)
+  # allowed_prefixes: []
+
+command_safety:
+  enabled: true
+  strength: hard  # hard = block, soft = nudge only
+  blocked_commands:
+    - "rm -rf /"
+    - "rm -rf /*"
+    - "mkfs"
+    - "dd if="
+    - ":(){ :|:& };:"
+    - "> /dev/sd"
+    - "shutdown"
+    - "reboot"
+    - "init 0"
+    - "init 6"
+    - "systemctl stop"
+
+secrets:
+  enabled: true
+  strength: hard  # hard = block, soft = mask and warn
+  mask_value: "[REDACTED]"
+  # Patterns: AWS keys, GitHub tokens, private keys, generic API keys
+
+prerequisites:
+  enabled: true
+  strength: soft  # soft = nudge first, hard = block until read
+  cooldown: 3     # turns before re-nudging
+  edit_tools:
+    - "write_file"
+    - "edit_file"
+    - "create_file"
+  read_tools:
+    - "read_file"
+    - "cat"
+
+sequencing:
+  enabled: true
+  strength: soft  # soft = suggest, hard = block until test runs
+  cooldown: 3
+  edit_tools:
+    - "write_file"
+    - "edit_file"
+    - "create_file"
+  test_tools:
+    - "bash"
+  test_commands:
+    - "pytest"
+    - "test"
+    - "cargo test"
+    - "go test"
+
+tool_resolution:
+  enabled: true
+  strength: soft  # soft = nudge only
+  # Nudges when tool results are empty, whitespace-only, or permission errors

coding_guardrails-0.1.0/configs/pi.yaml

@@ -0,0 +1,13 @@
+# Pi agent configuration
+# Point Pi at the coding-guardrails proxy instead of directly at llama-server.
+#
+# Usage:
+#   1. Start llama-server: llama-server -m <model>.gguf --jinja --fit on --flash-attn auto --port 8080 -c 16384 --spec-type draft-mtp -np 1
+#   2. Start proxy:        coding-guardrails serve --backend-url http://localhost:8080 --model Qwen3.6-35B-A3B-UD-Q3_K_M --port 8081
+#   3. Set in Pi config:   api_base = "http://localhost:8081/v1"
+
+model: "Qwen3.6-35B-A3B-UD-Q3_K_M"
+api_base: "http://localhost:8081/v1"
+
+# Pi should see the proxy as a regular OpenAI-compatible backend.
+# No special configuration needed — the guardrails are transparent.

coding_guardrails-0.1.0/docker-compose.yaml

@@ -0,0 +1,59 @@
+# coding-guardrails + llama-server stack
+#
+# Usage:
+#   GGUF_PATH=/path/to/model.gguf docker compose up
+#
+# The llama-server container needs GPU access. Adjust CUDA_VISIBLE_DEVICES
+# if you have multiple GPUs.
+
+services:
+  llama-server:
+    image: ghcr.io/ggerganov/llama.cpp:server
+    ports:
+      - "8080:8080"
+    volumes:
+      - ${GGUF_PATH:-./models}:/models:ro
+    command: >
+      --model /models/${GGUF_FILE:-model.gguf}
+      --jinja
+      --fit on
+      --flash-attn auto
+      --port 8080
+      --host 0.0.0.0
+      -c ${CONTEXT_SIZE:-16384}
+      --spec-type draft-mtp
+      -np 1
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+
+  coding-guardrails:
+    build: .
+    ports:
+      - "8081:8081"
+    volumes:
+      - ./configs/guardrail-config.yaml:/etc/coding-guardrails/config.yaml:ro
+    command: >
+      serve
+      --backend-url http://llama-server:8080
+      --model ${MODEL_NAME:-Qwen3.6-35B-A3B-UD-Q3_K_M}
+      --port 8081
+      --host 0.0.0.0
+    depends_on:
+      llama-server:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8081/health')"]
+      interval: 30s
+      timeout: 5s
+      retries: 3