ai-contract-platform/yuqei-ai-platform/services/ai-platform-api/README.md

AI Platform API

FastAPI service for V2 shared AI capabilities.

Local Run

cd yuqei-ai-platform/services/ai-platform-api
python -m uvicorn yuqei_ai_platform_api.main:app --app-dir src --reload --port 8101

Default local runs use the in-memory repository. To run against a real database-backed repository:

$env:AI_PLATFORM_REPOSITORY_BACKEND="sqlalchemy"
$env:AI_PLATFORM_DATABASE_URL="postgresql+psycopg://ai:ai@localhost:5432/yuqei_ai"
python -m uvicorn yuqei_ai_platform_api.main:app --app-dir src --reload --port 8101

Run database migrations from this service directory:

$env:AI_PLATFORM_DATABASE_URL="postgresql+psycopg://ai:ai@localhost:5432/yuqei_ai"
python -m alembic upgrade head

Provider calls are disabled by default. To enable an OpenAI-compatible provider:

$env:AI_PLATFORM_PROVIDER_CALL_MODE="enabled"
$env:AI_PLATFORM_PROVIDER_API_KEY="your-api-key"
$env:AI_PLATFORM_PROVIDER_BASE_URL="https://api.deepseek.com/v1"
$env:AI_PLATFORM_PROVIDER_FALLBACK_ENABLED="true"
$env:AI_PLATFORM_PROVIDER_PROMPT_TOKEN_COST_PER_1K="0"
$env:AI_PLATFORM_PROVIDER_COMPLETION_TOKEN_COST_PER_1K="0"

Embedding defaults to deterministic local-hash-v1 so tests and offline development remain reproducible. For production-grade RAG, enable an OpenAI-compatible embedding provider and PostgreSQL pgvector retrieval:

$env:AI_PLATFORM_REPOSITORY_BACKEND="sqlalchemy"
$env:AI_PLATFORM_DATABASE_URL="postgresql+psycopg://ai:ai@localhost:5432/yuqei_ai"
$env:AI_PLATFORM_EMBEDDING_PROVIDER="openai-compatible"
$env:AI_PLATFORM_EMBEDDING_MODEL="text-embedding-3-small"
$env:AI_PLATFORM_EMBEDDING_API_KEY="your-embedding-api-key"
$env:AI_PLATFORM_EMBEDDING_BASE_URL="https://api.openai.com/v1"
$env:AI_PLATFORM_EMBEDDING_FALLBACK_ENABLED="true"
$env:AI_PLATFORM_VECTOR_SEARCH_BACKEND="pgvector"
python -m alembic upgrade head

The pgvector migration creates the vector extension and adds an embedding column for new knowledge chunks. The JSON embedding payload remains as a portable fallback, so SQLite tests and non-pgvector environments continue to work. Re-import or re-index existing knowledge documents after enabling a real embedding model so old chunks receive production vectors.

Health endpoints:

• GET /health
• GET /api/v1/health

Core MVP endpoints:

• GET|POST /api/v1/model-configs
• GET|POST /api/v1/prompt-templates
• GET|POST /api/v1/knowledge-import-batches
• POST /api/v1/knowledge-documents
• POST /api/v1/knowledge-documents/reindex
• GET /api/v1/knowledge-documents/{document_id}/chunks
• GET /api/v1/knowledge-documents/search
• GET /api/v1/knowledge-chunks/search?strategy=keyword|vector|hybrid
• GET /api/v1/knowledge-chunks/search/explain?strategy=keyword|vector|hybrid
• POST /api/v1/legal/qa
• GET /api/v1/audit/ai-runs

Knowledge chunk search returns keyword, vector, and hybrid scores. Legal QA uses hybrid retrieval by default and records retrieved chunk ids plus structured source metadata in AI run audits. AI run audits also record provider/model, provider status/error, token usage, estimated cost, and latency for operational traceability.

Use GET /api/v1/knowledge-chunks/search/explain to inspect normalized query terms, keyword/vector/hybrid scores, inclusion rank, and filter reasons for the candidate chunks considered by retrieval.

After switching from local-hash-v1 to a real embedding model, call POST /api/v1/knowledge-documents/reindex with a document_id, knowledge_base_id, or import_batch_id filter to rebuild historical chunks with the current embedding provider and refresh pgvector values.

Test

From repository root:

python -m pytest yuqei-ai-platform/services/ai-platform-api/tests