Skip to content

quick-start.rst

Latest commit

 

History

History
257 lines (169 loc) · 5.53 KB

quick-start.rst

File metadata and controls

257 lines (169 loc) · 5.53 KB
Raw

Quick Start Guide

This guide will help you get started with ai-slop-gate in minutes.

Installation

1. Clone the repository:

git clone https://github.com/SergUdo/ai-slop-gate.git
cd ai-slop-gate

2. Set up Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

3. Initialize configuration:

python -m ai_slop_gate.cli init

This creates .ai-slop-gate.yml with default settings.

Environment Variables

Create a .env file in the project root:

# Required for GitHub PR commenting
GITHUB_TOKEN=your_github_personal_access_token

# Provider Keys (add based on your configuration)
GEMINI_API_KEY=your_google_gemini_api_key
SLOPE_GATE_GROQ=your_groq_api_key
GITLAB_TOKEN=your_gitlab_token  # For GitLab integration

Your First Analysis

Static Analysis (Fast, No API Keys Required)

python -m ai_slop_gate.cli run --provider static --policy policy.yml

This performs:

  • Secret detection (hardcoded API keys, passwords)
  • Dangerous function detection (eval, exec)
  • Dockerfile security checks
  • PII detection
  • TODO/FIXME tracking
  • Supply chain validation

LLM Analysis (Requires API Key)

python -m ai_slop_gate.cli run --provider gemini --llm-local --policy policy.yml

This performs AI-powered analysis:

  • AI slop detection (repetitive, low-quality code)
  • Hallucination detection
  • Code quality assessment
  • Architecture anti-patterns
  • Automatically caches responses (saves ~67% of tokens!)

Compliance Check

python -m ai_slop_gate.cli run --compliance --policy policy.yml

This checks:

  • GDPR/DSGVO data residency
  • License compliance (GPL, AGPL detection)
  • Supply chain security
  • AI hallucination protection

Using Docker

Pull the image:

docker pull ghcr.io/sergudo/ai-slop-gate:latest

Run analysis:

docker run --rm -v $(pwd):/src \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src

See :doc:`DOCKER` for complete Docker documentation.

Test on Demo Repository

Try ai-slop-gate on our demo repository with intentional violations:

git clone https://github.com/SergUdo/slop_test
python -m ai_slop_gate.cli run --provider gemini --llm-local --path slop_test

This repository contains:

  • Hardcoded secrets
  • AI-generated slop
  • License violations
  • Security issues

Live Example: Check this PR where ai-slop-gate automatically analyzed violations.

Supported Providers

Provider Type Cache Description
static Static Analysis ❌ No Fast static analysis (secrets, eval, Dockerfile, PII)
gemini LLM ✅ Yes Google Gemini (local or GitHub PR)
groq LLM ✅ Yes Groq (Llama 3.3)
ollama LLM ✅ Yes Local Ollama models (100% private)
compliance Compliance ❌ No GDPR, EU residency, license checks

Common Use Cases

1. Local Development (Before Commit)

# Quick check
python -m ai_slop_gate.cli run --provider static

# Deep analysis (with cache)
python -m ai_slop_gate.cli run --provider static gemini --llm-local

2. Pull Request Analysis

export GITHUB_TOKEN="ghp-xxxxxxxxxxxx"
export GEMINI_API_KEY="your-key"

python -m ai_slop_gate.cli run \
  --provider gemini \
  --github-repo owner/repo \
  --pr-id 123

3. CI/CD Pipeline

# GitHub Actions example
- name: AI Slop Gate
  run: |
    docker run --rm -v $(pwd):/src \
      -e GEMINI_API_KEY=${{ secrets.GEMINI_API_KEY }} \
      ghcr.io/sergudo/ai-slop-gate:latest \
      run --provider gemini --llm-local --path /src

See :doc:`INTEGRATIONS` for complete CI/CD setup.

4. Local LLM (100% Private)

# Start Ollama
docker-compose up -d

# Run analysis (code never leaves your machine)
python -m ai_slop_gate.cli run --provider ollama --llm-local

Next Steps

  • CLI Reference: See :doc:`CLI_REFERENCE` for all command-line options
  • Cache Guide: Learn how to optimize token usage in :doc:`CACHE`
  • Docker Guide: Full Docker documentation in :doc:`DOCKER`
  • CI/CD Integration: Set up in GitHub/GitLab with :doc:`INTEGRATIONS`
  • Testing: Write tests with :doc:`TESTING`
  • Architecture: Understand the internals in :doc:`ARCHITECTURE`

Troubleshooting

"Provider skipped: insufficient context"

Missing API key. Set environment variable:

export GEMINI_API_KEY="your-key"

"Cache not working"

Check verbose output:

python -m ai_slop_gate.cli run --provider gemini --llm-local --verbose

See cache directory:

ls -la .ai-slop-cache/

"Permission denied"

Fix permissions:

chmod -R u+rw .ai-slop-cache/

For more help, see: