Run AI Service

Skill: run-ai-service

Start, test, and verify the Python FastAPI AI service (services/ai-service/).

Steps

1. Activate virtual environment

cd services/ai-service
# Windows (Git Bash):
source .venv/Scripts/activate
# Unix/macOS:
# source .venv/bin/activate

2. Verify environment variables

# Check that ANTHROPIC_API_KEY is set
pip show anthropic
# Confirm .env exists with ANTHROPIC_API_KEY (never commit real keys)

3. Start the service

uvicorn app.main:app --reload --port 8000

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Application startup complete.

4. Verify health check

curl http://localhost:8000/health

Expected response:

{"status": "ok", "service": "ai-service"}

5. Run the test suite

# From services/ai-service/ with venv active:
pytest
# Or with verbose output:
pytest -v

All tests must pass before any commit. Tests must not call the real Anthropic API (see .claude/rules/ai-service.md).

6. Test extraction endpoint (manual smoke test)

# Test PDF extraction (replace with a real statement file for manual testing)
curl -X POST http://localhost:8000/extract/pdf \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/statement.pdf" \
  -F "bank_id=superbank"

7. Via Docker (after PF-011 docker-compose integration)

# From repo root:
docker compose up --build ai-service
docker compose logs -f ai-service

Troubleshooting

Related

• Rules: .claude/rules/ai-service.md
• Add a new bank extractor: /add-llm-extractor
• Run all CI gates: /ci-check

Source: rikky-hermanto/personal-finance — distributed by TomeVault.