Federated from workspace · PL-003 · zaixos-ai-platform/docs/CONTRACTS_INVENTORY.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

CONTRACTS_INVENTORY — M-18 Wave 1

Package: zaixos/ai-contracts @ 0.2.0
Namespace root: Zaixos\Ai\Contracts\

Wave 1 public contract surface extracted from PRD-001 AI module. Framework-agnostic; tenant-scoped via tenantId.

---

Contracts (Contracts/)

Contract	Purpose
AiPlatformContract	Submit and retrieve AI jobs; returns AiJobSnapshot
AiProviderContract	Provider identity and completion execution
AiStreamingProviderContract	Streaming completion via AiStreamEvent generator
AiEmbeddingProviderContract	Embedding generation
AiProviderConnectivityContract	Provider health verification
AiProviderFactory	Resolve provider by key
AiAgentContract	Agent run orchestration
AiToolHandlerContract	Tenant-scoped tool execution (no provider/vector access)
VectorStoreContract	Vector upsert, search, tenant-scoped delete
MemoryStoreContract	Session memory remember/recall/delete
KnowledgeRetrievalContract	RAG retrieval from vector knowledge
ConversationStoreContract	Conversation and message persistence (string IDs)
AiUsageQuotaContract	Pre-execution quota assertion and usage recording
AiEvaluationRunnerContract	Evaluation suite runner stub

---

DTOs (DTOs/)

DTO	Purpose
SubmitAiJobData	Job submission command
AiJobSnapshot	Job read model (replaces Eloquent)
AiCompletionRequest	Provider completion request
AiCompletionResponse	Normalized provider completion response
AiCompletionResult	Gateway-facing completion result
AiStreamEvent	Streaming event payload
AiEmbeddingRequest	Embedding request
AiEmbeddingResponse	Embedding response
AiAgentRunRequest	Agent run command (agentKey)
AiAgentRunResult	Agent run result (agentKey)
AiAgentStreamRequest	Agent streaming command (agentKey)
AiToolCall	Function-call invocation
AiToolHandlerResult	Tool handler output
AiToolExecutionRequest	Batch tool execution request
AiToolExecutionResult	Batch tool execution result
AiFunctionDefinition	Discoverable tool schema
VectorSearchQuery	Vector similarity search query
VectorSearchResult	Vector search matches
VectorUpsertData	Vector upsert payload
VectorMatch	Single vector match
AiRetrievalRequest	Knowledge retrieval request
AiRetrievalResult	Knowledge retrieval result
AiSessionMemoryData	Session memory entry
CreateAiConversationData	Conversation creation command
AppendAiMessageData	Message append command
CreateAiPromptTemplateData	Prompt template creation
AiCostEstimate	Cost estimation snapshot
AiAssistantDefinition	Assistant configuration
AiAssistantMemoryConfig	Assistant memory settings
AiAssistantRetrievalConfig	Assistant retrieval settings

---

Enums (Enums/)

Enum	Values (summary)
AiJobOperation	completion, chat, embedding
AiStreamEventType	started, content_delta, tool_call_delta, completed, error
AiContentBlockType	text, image, audio
AiFinishReason	stop, length, content_filter, tool_calls, error, unknown
AiProviderHealthStatus	healthy, degraded, unhealthy, stub, not_configured, not_implemented
AiProviderErrorCode	authentication, rate_limit, invalid_request, not_found, server_error, timeout, connectivity, capability_denied, not_implemented, unknown
AiModelCapability	chat, completion, vision, audio, image_generation, embeddings, function_calling, streaming
AiProviderCapability	chat_completions, embeddings, image_generation, audio_transcription, audio_generation, function_calling, streaming, batch_processing
AiConversationRole	system, user, assistant, tool
AiConversationStatus	active, archived
AiJobStatus	pending, processing, completed, failed
AiProviderType	stub, openai, anthropic, google_gemini, azure_openai

All enums expose a static values(): array method.

---

Value Objects (ValueObjects/)

Value Object	Purpose
AiUsage	Token usage counts
AiContentBlock	Normalized content block
AiProviderHealthSnapshot	Connectivity check result (DateTimeImmutable)
AiProviderCapabilities	Provider capability matrix
AiModelCapabilities	Model capability matrix
AiProviderError	Structured provider error

---

Exceptions (Exceptions/)

Exception	Purpose
AiProviderException	Provider failure with structured error
AiCapabilityNotSupported	Capability denial
AiAgentNotFound	Unregistered agent
AiToolNotPermitted	Tool not allowed for assistant
AiToolHandlerNotFound	Missing tool handler
AiAssistantNotFound	Unregistered assistant

---

Extraction notes

• Source: PRD-001 app/Modules/AI/ (reference only — not modified)
• Renames: clinicId → tenantId, assistantKey → agentKey on agent run DTOs
• AiAssistantDefinition::fromConfig() defaults defaultProviderKey to 'stub' (no config())
• AiPlatformContract uses AiJobSnapshot instead of Eloquent AiJob