In-app AI suggestions

BASIL can use an OpenAI-compatible API to suggest content for work items directly in the app. The backend module api/ai.py provides an AIPrompter that calls the configured AI service to generate:

• Software requirement metadata — title, description, completeness, and reasoning from a specification excerpt

• Test case metadata — title, description, completeness, and reasoning for a test case from a specification

• Test specification metadata — title, preconditions, test description, expected behavior, completeness, and reasoning

• Test case implementation — a single-file implementation proposal (saved under api/user-files/<user_id>/)

The app uses these suggestions when creating or editing Software Requirements, Test Specifications, and Test Cases, so users can get AI-drafted fields from the selected specification text.

Configuration

AI is configured via:

1. The admin settings (recommended for host, port, model, etc.)

2. Environment variables (override or supply values when the settings file does not) of API deployment

Admin Settings

Option	Description	Required
host	Base URL of the AI API (e.g. https://api.openai.com or http://localhost:1234). Do not include path or trailing slash.	Yes
port	Port number (e.g. 443 for HTTPS, or the port of your local server).	Yes
model	Model name (e.g. gpt-4o, phi3.5, or the identifier of your local model).	Yes
api_version	API version path segment (default: v1). Prepended to the path used for chat completions.	No (default: v1)
temperature	Sampling temperature (0–1). Lower values give more deterministic output. Default: 0.	No (default: 0)
token	API key or token for authentication. Use for services that require it (e.g. OpenAI). Can be left empty for local servers without auth.	No
max_tokens	Maximum tokens for each AI response. If the model truncates output (e.g. “Invalid JSON: EOF while parsing”), increase this. Default: 4096.	No (default: 4096)

Example:

ai:
  host: "https://api.openai.com"
  port: 443
  model: "gpt-4o"
  api_version: "v1"
  temperature: 0
  token: "sk-..."

Environment variables

You can override or supply AI configuration via environment variables. These are used when the corresponding key is missing (or not set) in the settings file.

Variable	Purpose
BASIL_AI_HOST	Same as ai.host
BASIL_AI_PORT	Same as ai.port
BASIL_AI_MODEL	Same as ai.model
BASIL_AI_API_VERSION	Same as ai.api_version
BASIL_AI_TEMPERATURE	Same as ai.temperature
BASIL_AI_TOKEN	Same as ai.token
BASIL_AI_MAX_TOKENS	Same as ai.max_tokens

Example:

export BASIL_AI_HOST="https://api.openai.com"
export BASIL_AI_PORT=443
export BASIL_AI_MODEL="gpt-4o"
export BASIL_AI_TOKEN="sk-..."

Validation and health check

• On each AI request, the backend checks that host, port, and model are set (via settings or environment). If any is missing, the API returns a precondition failed response and the in-app suggestion feature will not call the AI.

• A health check endpoint (used by the app to verify AI availability) calls GET {base_url}/models. The AI service must respond with HTTP 200 for the app to consider the AI feature available.

API endpoints (reference)

The following REST resources are used by the app for AI suggestions:

• AI health check — GET endpoint to verify the configured AI service is reachable.

• Suggest software requirement metadata — POST with spec; returns title, description, completeness, reasoning.

• Suggest test case metadata — POST with spec; returns title, description, completeness, reasoning.

• Suggest test specification metadata — POST with spec; returns title, preconditions, test description, expected behavior, completeness, reasoning.

• Suggest test case implementation — POST with spec and title; returns implementation text and a file path under api/user-files/<user_id>/.

All suggestion endpoints require a valid API user with write permission.

See the main API documentation or api/api.py for the exact routes and request/response formats.