codeguardian-offline 0.1.0

Offline AI QA Assistant

CodeGuardian

An Offline AI QA Assistant that tests applications automatically and explains failures.

No internet. No API keys. No cloud services.

Architecture & Features

• CLI Automation: Built with Typer and Rich for a premium terminal experience.
• API Testing: Uses HTTPX to validate JSON endpoints.
• UI Testing: Uses Playwright for headless browser automation and UI validation.
• Static Analysis: Hooks into Semgrep and Ruff.
• RAG & Knowledge Base: Parses source code with Tree-sitter, embeds it using SentenceTransformers, and stores it in ChromaDB.
• Local AI Explanations: Queries your local Ollama (qwen2.5-coder recommended) to explain test failures by correlating test errors with the relevant source code.

Installation

Ensure you have Python 3.10+ installed.

CodeGuardian uses optional dependencies so you only install what you need.

git clone <repository>
cd CodeGuardian
python -m venv venv

# On Windows:
.\venv\Scripts\activate
# On Mac/Linux:
source venv/bin/activate

Install CodeGuardian with the features you need:

Use case	Command	Approx size
API testing only	pip install -e .	~50MB
+ UI testing	pip install -e .[ui]	~200MB
+ AI explanations	pip install -e .[ai]	~3GB
+ Code scanning	pip install -e .[scan]	~100MB
Everything	pip install -e .[full]	~3.5GB

(Note: AI explanations require PyTorch which is ~2GB. Playwright requires an extra step: playwright install chromium).

Install Ollama

Install Ollama on your local machine if you plan to use AI features. CodeGuardian will automatically pull the recommended model (qwen2.5-coder) when you first use the ask command.

Usage

1. Initialize

Initialize the CodeGuardian database and pre-compile any language grammars:

cd /path/to/your/project
codeguardian init

2. Configure Tests

Create a codeguardian-api.json or codeguardian-ui.json in your project root. CodeGuardian will validate your config using Pydantic before running.

codeguardian-api.json

{
  "base_url": "https://httpbin.org",
  "tests": [
    {"name": "Get Request", "url": "/get", "method": "GET", "expected_status": 200},
    {"name": "Not Found", "url": "/status/404", "method": "GET", "expected_status": 404}
  ]
}

codeguardian-ui.json

{
  "browser": "chromium",
  "headless": true,
  "tests": [
    {
      "name": "Check Example Domain",
      "steps": [
        {"action": "navigate", "url": "http://example.com"},
        {"action": "assert_visible", "selector": "h1"}
      ]
    }
  ]
}

3. Run Tests

Run both API and UI tests (results will be logged to SQLite):

codeguardian test
# Or target specific suites:
# codeguardian test --api-only
# codeguardian test --ui-only

4. Build Knowledge Base

Scan the project to run static analysis and build the ChromaDB vector index:

codeguardian scan .

5. Ask the AI

If tests fail, query the AI. CodeGuardian will fetch the latest failures, pull relevant source code from ChromaDB, and ask Ollama to explain what went wrong:

codeguardian ask "Why did the API tests fail?"

6. Generate Reports

Export beautiful HTML reports or JUnit XML for CI/CD integrations:

codeguardian report --format html
codeguardian report --format junit
codeguardian report --format both