AI Service — API Reference

Overview

The AI service exposes a FastAPI application that wraps an AI provider (OpenAI, Anthropic, or a mock) to perform code analysis and test generation.

Configuration

Environment Variable	Default	Description
`OPENAI_API_KEY`	(unset)	Your OpenAI secret key. When present, the service can call the OpenAI API.
`ANTHROPIC_API_KEY`	(unset)	Your Anthropic secret key. Required when `AI_PROVIDER=anthropic`.
`AI_PROVIDER`	auto	Force a specific provider: `openai`, `anthropic`, or `mock`. When unset the service picks `openai` if `OPENAI_API_KEY` is set, `anthropic` if only `ANTHROPIC_API_KEY` is set, `mock` otherwise.
`OPENAI_MODEL`	`gpt-4o`	OpenAI chat model to use (e.g. `gpt-4o`, `gpt-3.5-turbo`).
`ANTHROPIC_MODEL`	`claude-3-haiku-20240307`	Anthropic model to use (e.g. `claude-3-opus-20240229`, `claude-3-sonnet-20240229`).

Python client wrapper

packages/ai-service/openai_client.py provides a lightweight abstraction:

from openai_client import create_ai_client

# Auto-selects provider from environment
client = create_ai_client()

reply = client.chat("Write a unit test for a sum() function in Python.")
print(reply)

Force a specific provider

# Always use OpenAI (raises ValueError if OPENAI_API_KEY is absent)
client = create_ai_client(provider="openai", api_key="sk-...")

# Always use Anthropic (raises ValueError if ANTHROPIC_API_KEY is absent)
client = create_ai_client(provider="anthropic", api_key="sk-ant-...")

# Always use the mock (no API key required — great for CI)
client = create_ai_client(provider="mock")

Direct instantiation

from openai_client import OpenAIClient, MockAIClient
from anthropic_client import AnthropicClient

# OpenAI
real_openai = OpenAIClient(api_key="sk-...", model="gpt-4o")
reply = real_openai.chat("Hello!")

# Anthropic
real_anthropic = AnthropicClient(api_key="sk-ant-...", model="claude-3-haiku-20240307")
reply = real_anthropic.chat("Hello!")
# Health check (no API call)
status = real_anthropic.health_check()
# → {"status": "ok", "provider": "anthropic", "model": "claude-3-haiku-20240307"}

# Real Anthropic client
claude = AnthropicClient(api_key="sk-ant-...", model="claude-3-haiku-20240307")
reply = claude.chat("Hello!")

# Mock client (zero-dependency, deterministic)
mock = MockAIClient()
reply = mock.chat("Hello!")  # → "[MOCK RESPONSE] ..."

Anthropic provider

packages/ai-service/anthropic_client.py wraps the Anthropic Python SDK.

Quick start

export ANTHROPIC_API_KEY="sk-ant-..."
export AI_PROVIDER="anthropic"
# Optionally override the model
export ANTHROPIC_MODEL="claude-3-opus-20240229"

`AnthropicClient` interface

Method	Signature	Description
`chat`	`(prompt, system?) → str`	Send a user message and return the assistant's reply.
`generate_tests`	`(prompt, system?) → str`	Alias for `chat()` — same signature.
`health_check`	`() → dict`	Return provider/model info without making an API call.

The client reads ANTHROPIC_API_KEY and ANTHROPIC_MODEL from the environment by default, both of which can be overridden via constructor arguments.

REST endpoints

`GET /provider`

Returns the name of the currently active AI provider.

{
  "provider": "openai"
}

Possible values: "openai", "anthropic", "mock".

`GET /health`

Returns service health and the active AI provider.

{
  "status": "healthy",
  "timestamp": "2026-03-08T10:00:00.000Z",
  "ai_provider": "anthropic"
}

`POST /generate-tests`

Generates test cases powered by the configured AI provider (OpenAI or Anthropic when a key is available, mock otherwise).

Request body

{
  "code_analysis": { ... },
  "test_type": "unit",
  "framework": "jest",
  "ai_provider": "anthropic",
  "ai_model": "claude-3-haiku-20240307"
}

Note: ai_provider / ai_model in the request body are informational. The service uses the provider selected via environment variables.

Response

{
  "tests": {
    "unit_tests": [
      {
        "name": "should validate email format",
        "file": "src/utils/validation.test.ts",
        "code": "...",
        "coverage": "src/utils/validation.ts"
      }
    ]
  },
  "coverage_estimate": 85.5,
  "test_count": 2,
  "execution_time": "2m 30s"
}

Running the tests

# From the repository root
python3 -m unittest discover \
  -s packages/ai-service/tests \
  -p "test_*.py" -v

# Or with pytest (if installed)
pytest packages/ai-service/tests/ -v

All tests use unittest.mock — no real API key is required.