Chatqna API Smoke Test

ChatQnA API Smoke Test

Run practical API checks for ChatQnA Core using the documented endpoints in docs/user-guide/api-reference.md.

Environment setup (run first)

This skill operates on real ChatQnA source files, so the ChatQnA application must be present and commands must run from the app root. Do this before any API validation workflow, whether or not source is already in your workspace.

Run the bundled bootstrap. It searches for an existing ChatQnA checkout by walking up from the current directory and checking the enclosing git repo, then reuses it without re-cloning. Only when no checkout is found does it do a shallow, single-branch, sparse checkout of just sample-applications/chat-question-and-answer-core from main.

It prints the resolved app root on stdout:

# SKILL_DIR is this skill directory. In-repo it is:
# .github/skills/chatqna-api-smoke-test
SKILL_DIR=".github/skills/chatqna-api-smoke-test"
APP_ROOT="$(bash "$SKILL_DIR/scripts/chatqna-bootstrap.sh")"
cd "$APP_ROOT"

Every command below assumes the working directory is this APP_ROOT.

To use a fork/branch or a specific clone path, override these before running the bootstrap script:

• CHATQNA_REPO_URL
• CHATQNA_REPO_BRANCH
• CHATQNA_CLONE_DIR
• CHATQNA_FORCE_CLONE (set to 1 to force clone)

Codebase root: sample-applications/chat-question-and-answer-core/

What This Skill Produces

• A runtime-aware API validation report for one scope:
  • Core health and metadata endpoints
  • Chat inference endpoint
  • Document ingestion lifecycle endpoints
  • Runtime-specific endpoints (OpenVINO device APIs or Ollama model APIs)
• Raw command evidence (curl output + HTTP status) for each check.
• A concise pass/fail summary with failing endpoint and first actionable next step.

When to Use

• "Smoke test the API"
• "Validate /v1/chatqna endpoints"
• "Check chat endpoint response"
• "Verify Swagger/OpenAPI endpoints"
• "Test runtime-specific endpoints for OpenVINO or Ollama"

Inputs To Confirm

Before running checks, confirm or infer:

1. Base host (HOST_IP, default 127.0.0.1)
2. Port (default 8102)
3. Runtime (openvino or ollama, optional but recommended)
4. Scope (core, chat, documents, runtime, or all; default core)

Base URL:

http://<HOST_IP>:8102/v1/chatqna

Decision Logic

• If scope is omitted, run core checks first (/health, /model, docs/openapi).
• If runtime is openvino, include /devices checks.
• If runtime is ollama, include /ollama-models and optional /ollama-model checks.
• If user asks for full validation, run all checks.
• If user asks for non-destructive tests only, avoid POST /documents and DELETE /documents.

Smoke Test Workflow

Run from sample-applications/chat-question-and-answer-core.

1. Ensure Deployment Is Running

If ChatQnA is not already running, start containers before API checks:

# Select runtime profile (choose one)
source scripts/setup_env.sh            # OpenVINO CPU (default)
# source scripts/setup_env.sh -d gpu   # OpenVINO GPU
# source scripts/setup_env.sh -b ollama # Ollama CPU

# Start services
docker compose -f docker/compose.yaml up -d

# Quick readiness check before API probes
docker compose -f docker/compose.yaml ps

If deployment is already running, continue with API smoke tests.

2. Preflight and URL Setup

HOST_IP=${HOST_IP:-127.0.0.1}
BASE_URL="http://${HOST_IP}:8102/v1/chatqna"

echo "${BASE_URL}"

3. Core Availability

curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/health"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/model"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/docs"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/openapi.json"

4. Chat API Check

curl -sS -X POST "${BASE_URL}/chat" \
  -H "Content-Type: application/json" \
  -d '{"input":"What is Retrieval-Augmented Generation?","stream":false}' \
  -w "\nHTTP_STATUS:%{http_code}\n"

5. Runtime-Specific Checks

OpenVINO:

curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/devices"
# Optional device detail probe
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/devices/CPU"

Ollama:

curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/ollama-models"
# Optional named model probe
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/ollama-model?model_id=<model-id>"

6. Document API Checks (Optional)

Non-destructive listing:

curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/documents"

Upload and cleanup (run only when user explicitly requests ingestion testing):

curl -sS -X POST "${BASE_URL}/documents" \
  -H "Content-Type: multipart/form-data" \
  -F "files=@./doc1.pdf" \
  -w "\nHTTP_STATUS:%{http_code}\n"

curl -sS -X DELETE "${BASE_URL}/documents?delete_all=true" \
  -w "\nHTTP_STATUS:%{http_code}\n"

Failure Handling

• HTTP_STATUS is not 2xx:
  • report endpoint, status code, and response body snippet
• /chat fails:
  • verify request JSON includes non-empty input
• runtime endpoint mismatch (e.g., /devices on Ollama):
  • note runtime-specific availability from API reference
• docs/openapi unavailable:
  • verify gateway URL and service readiness via /health

Completion Criteria

1. Requested scope is executed against the correct base URL.
2. Runtime-specific checks match selected runtime.
3. Response includes raw command evidence with HTTP statuses.
4. Final summary clearly marks pass/fail by endpoint.
5. For failures, provide one actionable next debugging step.