Agentic Quality Intelligence System

AQIS is a local project for quality-intelligence workflows. The repository currently contains the development foundation plus deterministic RCA, local Hybrid RAG over quality documents, optional Neo4j GraphRAG, a tool-calling agent mode, a CLI, and a thin FastAPI/OpenAI-compatible service.

For the intended product direction, see the AQIS Product Vision. For current HTTP, CLI, workflow, and schema contracts, see the AQIS API Documentation.

Start here after a fresh clone or a longer pause: AQIS Getting Started. For the v0.1-alpha demo and release checklist, see AQIS Release Notes.

Project Structure

• docs: product, architecture, and API documentation.
• src/aqis: core contracts, local knowledge search, retrieval, GraphRAG, RCA synthesis, and workflows.
• app: packaged FastAPI/API entrypoints.
• tests: environment, documentation, Docker, model-helper, CLI, API, and workflow checks.
• docker: local Redis, Neo4j, and OpenWebUI compose files.
• models: local model helper plus ignored model artifacts. See models/README.md.
• runtime: ignored local service state.

Environment

Create or update the Conda environment from the unlocked file:

conda env update --file environment.yml --prune
conda activate aqis

Confirm that commands resolve to the activated environment:

python --version
python -c "import sys; print(sys.executable)"

make install installs the editable project with development tools and all current runtime capabilities. Smaller pip installations are also supported:

python -m pip install -e .
python -m pip install -e ".[retrieval]"
python -m pip install -e ".[graph]"
python -m pip install -e ".[openrouter]"
python -m pip install -e ".[all,dev]"

The base installation provides deterministic RCA, CLI, and API behavior. Retrieval, GraphRAG, and OpenRouter remain explicit optional profiles. The Conda environment is the all-in-one development profile used by the complete local check suite.

Common Commands

make help
make install
make ci
make test
make lint
make typecheck
make typecheck-pyright
make markdownlint
make validate-knowledge
make eval-agent
make smoke-local
make index-quality-documents
make build-quality-graph
make smoke-graphrag
make smoke-openrouter

Run the first deterministic RCA slice against local fixture knowledge:

python -m aqis.cli rca \
  --knowledge examples/data/quality_knowledge \
  --defect-type silk_spot \
  --machine Walze-01 \
  --question "We see recurring silk spots after startup. What should we check first?" \
  --format json

Run the local RCA API:

uvicorn app.api:app --reload

Example API request:

curl -X POST http://127.0.0.1:8000/rca/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "case": {
      "case_id": "api-case",
      "description": "We see recurring silk spots after startup.",
      "defect_type": "silk_spot",
      "machine": "Walze-01"
    }
  }'

The same local API also exposes a minimal OpenAI-compatible chat adapter for OpenWebUI experiments:

curl http://127.0.0.1:8000/v1/models

Run the first tool-calling agent mode through the same OpenAI-compatible route:

curl -X POST http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aqis-deterministic-rca",
    "messages": [
      {
        "role": "user",
        "content": "We see recurring silk spots after startup on Walze-01. What should we check first?"
      }
    ],
    "metadata": {
      "mode": "agent",
      "agent": {
        "provider": "deterministic"
      }
    }
  }'

Run an opt-in live OpenRouter smoke against the local AQIS tools. This requires OPENROUTER_API_KEY in the environment or .env:

make smoke-openrouter OPENROUTER_MODEL=qwen/qwen3-32b

Build the optional local Chroma index for Hybrid RAG over quality document chunks:

make index-quality-documents

Build the optional local Neo4j graph for GraphRAG:

make neo4j-up
make build-quality-graph

Run a local GraphRAG smoke after Neo4j has started:

make smoke-graphrag

Install and run Git hooks:

make precommit-install
make precommit

Refresh the Conda lock export after environment changes:

make lock

environment.yml is the editable environment definition; environment.lock.yml records the resolved workstation environment. Refresh the lock only from a validated aqis environment.

Local Services

Start and stop Redis:

make redis-up
make redis-ping
make redis-down

Redis binds to localhost ports 6379 and 8081 by default. Override them with AQIS_REDIS_PORT and AQIS_REDIS_COMMANDER_PORT.

Start and stop Neo4j:

make neo4j-up
make neo4j-ping
make neo4j-down

Neo4j binds to localhost ports 7474 and 7687. Keep the service password supplied as make neo4j-up NEO4J_PASSWORD=... aligned with AQIS_NEO4J_PASSWORD used by the API and CLI graph clients.

An Open WebUI compose file is prepared for the later chat workspace:

uvicorn app.api:app --reload
docker compose -f docker/compose.openwebui.yml up -d
docker compose -f docker/compose.openwebui.yml down

The compose file points OpenWebUI at the AQIS OpenAI-compatible endpoint by default: http://host.docker.internal:8000/v1.

Local service state is stored under runtime/, which is intentionally ignored by Git.

Local Models

Model snapshots are intentionally ignored. To inspect the configured downloads:

python models/snapshot_download.py --dry-run

To download the default local RAG snapshots:

python models/snapshot_download.py

Git

The repository uses main as its primary branch. Review git status and the local check output before staging larger feature slices.