fix: Handle null citation fields in Pydantic models and update API key prefix validation.

Author: 0xneobyte

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] - 2025-12-12
+
+### Fixed
+
+- Fixed Pydantic validation errors when `citations.pages` or `citations.metadata` are returned as `null` from the API
+
+## [0.1.4] - 2025-12-12
+
+### Changed
+
+- Updated API key prefix validation from `sk_live_` to `brainus_` to match backend changes
+
 ## [0.1.3] - 2025-12-12
 
 ### Changed
@@ -37,6 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full type hints with Pydantic models
 - Async/await support
 
+[0.1.4]: https://github.com/BrainUsLK/brainus-ai-python/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/BrainUsLK/brainus-ai-python/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/BrainUsLK/brainus-ai-python/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/BrainUsLK/brainus-ai-python/compare/v0.1.0...v0.1.1

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "brainus-ai"
-version = "0.1.3"
+version = "0.1.5"
 description = "Official Python SDK for Brainus AI - RAG-powered educational content API"
 readme = "README.md"
 license = {text = "MIT"}

src/brainus_ai/client.py

@@ -20,7 +20,7 @@ class BrainusAI:
 
     Example:
         >>> from brainus_ai import BrainusAI
-        >>> client = BrainusAI(api_key="sk_live_...")
+        >>> client = BrainusAI(api_key="brainus_...")
         >>> response = await client.query(
         ...     query="What is Python?",
         ...     store_id="abc123"  # Optional - uses default if not provided
@@ -39,13 +39,13 @@ def __init__(
         Initialize the Brainus AI client.
 
         Args:
-            api_key: Your Brainus AI API key (sk_live_...)
+            api_key: Your Brainus AI API key (brainus_...)
             base_url: Base URL for the API (default: production gateway)
             timeout: Request timeout in seconds
             max_retries: Maximum number of retry attempts for failed requests
         """
-        if not api_key or not api_key.startswith("sk_live_"):
-            raise ValueError("Invalid API key format. Expected format: sk_live_...")
+        if not api_key or not api_key.startswith("brainus_"):
+            raise ValueError("Invalid API key format. Expected format: brainus_...")
 
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")

src/brainus_ai/models.py

@@ -1,7 +1,7 @@
 """Data models for the Brainus AI SDK."""
 
 from typing import Any, Optional
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class Citation(BaseModel):
@@ -13,6 +13,20 @@ class Citation(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict, description="Document metadata")
     chunk_text: Optional[str] = Field(None, description="Relevant text chunk")
 
+    @field_validator("pages", mode="before")
+    @classmethod
+    def validate_pages(cls, v: Any) -> Any:
+        if v is None:
+            return []
+        return v
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def validate_metadata(cls, v: Any) -> Any:
+        if v is None:
+            return {}
+        return v
+
 
 class QueryFilters(BaseModel):
     """Metadata filters for query."""