gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/knowledge/mobile/swift-patterns.md

@@ -1,190 +0,0 @@
----
-name: Swift and SwiftUI Patterns
-stack: mobile
-version: "1.0"
-focus: [swift]
----
-
-# Swift and SwiftUI Patterns
-
-## Principle
-
-Build iOS interfaces with SwiftUI's declarative syntax, use Combine for reactive data flow, apply protocol-oriented programming for flexible abstractions, and manage memory carefully with ARC (Automatic Reference Counting). Prefer value types (structs, enums) over reference types (classes) unless identity semantics are required.
-
-## Rationale
-
-SwiftUI re-renders views when their state changes, similar to React. Views are lightweight structs, not persistent objects, so the framework creates and discards them freely. Combine provides a native reactive pipeline for transforming and combining async data streams. Protocol-oriented programming (POP) avoids the fragile base class problem of inheritance. ARC requires explicit attention to retain cycles, especially in closures and delegate patterns.
-
-## Pattern Examples
-
-### Pattern 1: SwiftUI Views with State Management
-
-```swift
-import SwiftUI
-
-// View Model — ObservableObject publishes changes
-@MainActor
-class UserListViewModel: ObservableObject {
-    @Published var users: [User] = []
-    @Published var isLoading = false
-    @Published var errorMessage: String?
-
-    private let repository: UserRepository
-
-    init(repository: UserRepository = .shared) {
-        self.repository = repository
-    }
-
-    func loadUsers() async {
-        isLoading = true
-        errorMessage = nil
-        do {
-            users = try await repository.fetchAll()
-        } catch {
-            errorMessage = error.localizedDescription
-        }
-        isLoading = false
-    }
-}
-
-// SwiftUI View — lightweight struct
-struct UserListView: View {
-    @StateObject private var viewModel = UserListViewModel()
-
-    var body: some View {
-        NavigationStack {
-            Group {
-                if viewModel.isLoading {
-                    ProgressView("Loading...")
-                } else if let error = viewModel.errorMessage {
-                    ContentUnavailableView(
-                        "Error", systemImage: "exclamationmark.triangle",
-                        description: Text(error)
-                    )
-                } else {
-                    List(viewModel.users) { user in
-                        NavigationLink(value: user) {
-                            UserRow(user: user)
-                        }
-                    }
-                }
-            }
-            .navigationTitle("Users")
-            .task { await viewModel.loadUsers() }
-            .refreshable { await viewModel.loadUsers() }
-        }
-    }
-}
-
-// Reusable subview
-struct UserRow: View {
-    let user: User
-
-    var body: some View {
-        HStack {
-            AsyncImage(url: user.avatarURL) { image in
-                image.resizable().scaledToFill()
-            } placeholder: {
-                Circle().fill(.gray.opacity(0.3))
-            }
-            .frame(width: 44, height: 44)
-            .clipShape(Circle())
-
-            VStack(alignment: .leading) {
-                Text(user.name).font(.headline)
-                Text(user.email).font(.subheadline).foregroundStyle(.secondary)
-            }
-        }
-    }
-}
-```
-
-### Pattern 2: Combine Pipeline
-
-```swift
-import Combine
-
-class SearchViewModel: ObservableObject {
-    @Published var query = ""
-    @Published var results: [SearchResult] = []
-
-    private var cancellables = Set<AnyCancellable>()
-    private let searchService: SearchService
-
-    init(searchService: SearchService) {
-        self.searchService = searchService
-
-        $query
-            .debounce(for: .milliseconds(300), scheduler: RunLoop.main)
-            .removeDuplicates()
-            .filter { $0.count >= 2 }
-            .flatMap { [weak self] query -> AnyPublisher<[SearchResult], Never> in
-                guard let self else { return Just([]).eraseToAnyPublisher() }
-                return self.searchService.search(query: query)
-                    .catch { _ in Just([]) }
-                    .eraseToAnyPublisher()
-            }
-            .receive(on: RunLoop.main)
-            .assign(to: &$results)
-    }
-}
-```
-
-### Pattern 3: Protocol-Oriented Programming
-
-```swift
-// Protocol defines the contract
-protocol Repository {
-    associatedtype Entity: Identifiable
-    func fetchAll() async throws -> [Entity]
-    func fetchById(_ id: Entity.ID) async throws -> Entity?
-    func save(_ entity: Entity) async throws -> Entity
-    func delete(_ id: Entity.ID) async throws
-}
-
-// Default implementation via protocol extension
-extension Repository {
-    func fetchOrThrow(_ id: Entity.ID) async throws -> Entity {
-        guard let entity = try await fetchById(id) else {
-            throw RepositoryError.notFound(String(describing: id))
-        }
-        return entity
-    }
-}
-
-// Concrete implementation
-struct UserRepository: Repository {
-    typealias Entity = User
-    private let apiClient: APIClient
-
-    func fetchAll() async throws -> [User] {
-        try await apiClient.get("/users")
-    }
-
-    func fetchById(_ id: String) async throws -> User? {
-        try? await apiClient.get("/users/\(id)")
-    }
-
-    func save(_ entity: User) async throws -> User {
-        try await apiClient.post("/users", body: entity)
-    }
-
-    func delete(_ id: String) async throws {
-        try await apiClient.delete("/users/\(id)")
-    }
-}
-```
-
-## Anti-Patterns
-
-- **Retain cycles in closures**: Capturing `self` strongly in escaping closures causes memory leaks. Use `[weak self]` and guard against nil.
-- **Massive view bodies**: SwiftUI views with 100+ lines in `body`. Extract subviews as separate structs.
-- **Using `@ObservedObject` for owned objects**: `@ObservedObject` does not own its object; use `@StateObject` for objects created by the view.
-- **Forcing class inheritance for abstraction**: Use protocols and protocol extensions instead of base classes.
-
-## Integration Points
-
-- **React Native**: Native modules in Swift bridge to React Native; see `react-native-patterns.md`.
-- **Mobile Testing**: XCTest and XCUITest for unit and UI testing; see `mobile-testing.md`.
-- **Kotlin**: Cross-platform considerations with Kotlin Multiplatform; see `kotlin-patterns.md`.
-- **Combine**: Integrates with SwiftUI's `@Published` and async/await via `values` property.

package/_gaia/dev/knowledge/python/data-pipelines.md

@@ -1,169 +0,0 @@
----
-name: Data Pipeline Patterns
-stack: python
-version: "1.0"
-focus: [data-pipelines]
----
-
-# Data Pipeline Patterns
-
-## Principle
-
-Design pipelines as composable, idempotent stages: extract, transform, load. Use pandas for batch tabular processing, async I/O for concurrent data fetching, and chunked processing for large datasets that do not fit in memory. Choose batch vs. stream based on latency requirements, not data volume.
-
-## Rationale
-
-ETL pipelines are the backbone of data-driven applications. Composable stages make pipelines testable in isolation and rerunnable without side effects (idempotency). Pandas provides powerful vectorized operations but can consume excessive memory on large datasets; chunked reading and processing prevent OOM errors. Async I/O dramatically speeds up the extract phase when pulling from multiple sources concurrently.
-
-## Pattern Examples
-
-### Pattern 1: Chunked Pandas Processing
-
-```python
-import pandas as pd
-from pathlib import Path
-from typing import Iterator
-
-
-def read_in_chunks(
-    filepath: Path, chunk_size: int = 10_000
-) -> Iterator[pd.DataFrame]:
-    """Read large CSV in chunks to avoid memory exhaustion."""
-    return pd.read_csv(
-        filepath,
-        chunksize=chunk_size,
-        dtype={"user_id": str, "amount": float},
-        parse_dates=["created_at"],
-    )
-
-
-def transform_chunk(df: pd.DataFrame) -> pd.DataFrame:
-    """Apply transformations to a single chunk."""
-    return (
-        df
-        .dropna(subset=["user_id", "amount"])
-        .assign(
-            amount_usd=lambda x: x["amount"] * x["exchange_rate"],
-            month=lambda x: x["created_at"].dt.to_period("M"),
-        )
-        .query("amount_usd > 0")
-    )
-
-
-def run_pipeline(input_path: Path, output_path: Path) -> int:
-    """Process file in chunks and write aggregated results."""
-    results = []
-    total_rows = 0
-
-    for chunk in read_in_chunks(input_path):
-        transformed = transform_chunk(chunk)
-        aggregated = (
-            transformed
-            .groupby("month")
-            .agg(total=("amount_usd", "sum"), count=("amount_usd", "size"))
-            .reset_index()
-        )
-        results.append(aggregated)
-        total_rows += len(transformed)
-
-    final = pd.concat(results).groupby("month").sum().reset_index()
-    final.to_parquet(output_path, index=False)
-    return total_rows
-```
-
-### Pattern 2: Async Extract from Multiple APIs
-
-```python
-import asyncio
-import httpx
-from dataclasses import dataclass
-
-
-@dataclass
-class ExtractResult:
-    source: str
-    data: list[dict]
-    record_count: int
-
-
-async def fetch_source(
-    client: httpx.AsyncClient, name: str, url: str
-) -> ExtractResult:
-    """Fetch data from a single API source."""
-    response = await client.get(url, timeout=30.0)
-    response.raise_for_status()
-    data = response.json()["results"]
-    return ExtractResult(source=name, data=data, record_count=len(data))
-
-
-async def extract_all(sources: dict[str, str]) -> list[ExtractResult]:
-    """Fetch from all sources concurrently."""
-    async with httpx.AsyncClient() as client:
-        tasks = [
-            fetch_source(client, name, url)
-            for name, url in sources.items()
-        ]
-        return await asyncio.gather(*tasks, return_exceptions=True)
-
-
-# Usage
-sources = {
-    "users": "https://api.example.com/users",
-    "orders": "https://api.example.com/orders",
-    "products": "https://api.example.com/products",
-}
-results = asyncio.run(extract_all(sources))
-```
-
-### Pattern 3: Idempotent Load with Upsert
-
-```python
-from sqlalchemy import text
-from sqlalchemy.ext.asyncio import AsyncSession
-
-
-async def upsert_records(
-    session: AsyncSession,
-    records: list[dict],
-    table: str,
-    conflict_key: str,
-) -> int:
-    """Idempotent upsert — safe to rerun without duplicates."""
-    if not records:
-        return 0
-
-    columns = list(records[0].keys())
-    col_list = ", ".join(columns)
-    val_placeholders = ", ".join(f":{col}" for col in columns)
-    update_set = ", ".join(
-        f"{col} = EXCLUDED.{col}"
-        for col in columns
-        if col != conflict_key
-    )
-
-    query = text(f"""
-        INSERT INTO {table} ({col_list})
-        VALUES ({val_placeholders})
-        ON CONFLICT ({conflict_key})
-        DO UPDATE SET {update_set}
-    """)
-
-    await session.execute(query, records)
-    await session.commit()
-    return len(records)
-```
-
-## Anti-Patterns
-
-- **Loading entire dataset into memory**: `pd.read_csv("huge.csv")` on a 10GB file. Use `chunksize` parameter or Dask for out-of-core processing.
-- **Non-idempotent loads**: INSERT without conflict handling causes duplicate records on rerun. Always use upsert or delete-then-insert.
-- **Sequential API calls**: Fetching 20 API sources one at a time when they are independent. Use `asyncio.gather` for concurrent extraction.
-- **String concatenation for SQL**: Building queries with f-strings opens SQL injection risks. Use parameterized queries.
-- **No error handling per stage**: A failure in transform should not require re-extracting. Checkpoint intermediate results.
-
-## Integration Points
-
-- **Django**: Management commands (`manage.py run_pipeline`) invoke pipeline stages; see `django-patterns.md`.
-- **FastAPI**: API endpoints trigger pipeline runs or report status; see `fastapi-patterns.md`.
-- **Python Conventions**: Type hints and project structure apply to pipeline code; see `python-conventions.md`.
-- **Testing**: Test each stage independently with fixture data; verify idempotency by running load twice.

package/_gaia/dev/knowledge/python/django-patterns.md

@@ -1,145 +0,0 @@
----
-name: Django Application Patterns
-stack: python
-version: "1.0"
-focus: [django]
----
-
-# Django Application Patterns
-
-## Principle
-
-Leverage Django's "batteries included" philosophy: use the ORM for data access, class-based views (CBVs) for reusable view logic, DRF serializers for API contracts, middleware for cross-cutting concerns, and signals sparingly for decoupled event handling. Keep business logic in model methods or dedicated service modules, not in views.
-
-## Rationale
-
-Django's ORM, admin, and middleware system are deeply integrated. Fighting the framework (e.g., using raw SQL everywhere, avoiding CBVs) increases maintenance burden. CBVs with mixins enable code reuse across views. DRF serializers validate input, serialize output, and document the API shape in one place. Signals enable loose coupling but overuse makes control flow invisible.
-
-## Pattern Examples
-
-### Pattern 1: Model with Business Logic
-
-```python
-from django.db import models
-from django.utils import timezone
-
-
-class Order(models.Model):
-    class Status(models.TextChoices):
-        DRAFT = "draft", "Draft"
-        CONFIRMED = "confirmed", "Confirmed"
-        SHIPPED = "shipped", "Shipped"
-        CANCELLED = "cancelled", "Cancelled"
-
-    customer = models.ForeignKey(
-        "customers.Customer",
-        on_delete=models.PROTECT,
-        related_name="orders",
-    )
-    status = models.CharField(
-        max_length=20, choices=Status.choices, default=Status.DRAFT
-    )
-    created_at = models.DateTimeField(auto_now_add=True)
-    confirmed_at = models.DateTimeField(null=True, blank=True)
-
-    class Meta:
-        ordering = ["-created_at"]
-        indexes = [
-            models.Index(fields=["status", "created_at"]),
-        ]
-
-    def confirm(self) -> None:
-        if self.status != self.Status.DRAFT:
-            raise ValueError(f"Cannot confirm order in {self.status} status")
-        self.status = self.Status.CONFIRMED
-        self.confirmed_at = timezone.now()
-        self.save(update_fields=["status", "confirmed_at"])
-
-    @property
-    def total(self) -> Decimal:
-        return sum(item.subtotal for item in self.items.all())
-```
-
-### Pattern 2: DRF Serializer and ViewSet
-
-```python
-from rest_framework import serializers, viewsets, permissions, status
-from rest_framework.decorators import action
-from rest_framework.response import Response
-
-
-class OrderSerializer(serializers.ModelSerializer):
-    total = serializers.DecimalField(read_only=True, max_digits=10, decimal_places=2)
-    items = OrderItemSerializer(many=True, read_only=True)
-
-    class Meta:
-        model = Order
-        fields = ["id", "customer", "status", "total", "items", "created_at"]
-        read_only_fields = ["status", "created_at"]
-
-
-class OrderViewSet(viewsets.ModelViewSet):
-    queryset = Order.objects.select_related("customer").prefetch_related("items")
-    serializer_class = OrderSerializer
-    permission_classes = [permissions.IsAuthenticated]
-
-    def get_queryset(self):
-        return super().get_queryset().filter(customer__user=self.request.user)
-
-    @action(detail=True, methods=["post"])
-    def confirm(self, request, pk=None):
-        order = self.get_object()
-        try:
-            order.confirm()
-            return Response(self.get_serializer(order).data)
-        except ValueError as e:
-            return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
-```
-
-### Pattern 3: Custom Middleware
-
-```python
-import time
-import logging
-
-logger = logging.getLogger(__name__)
-
-
-class RequestTimingMiddleware:
-    """Logs request duration for performance monitoring."""
-
-    def __init__(self, get_response):
-        self.get_response = get_response
-
-    def __call__(self, request):
-        start = time.monotonic()
-        response = self.get_response(request)
-        duration_ms = (time.monotonic() - start) * 1000
-
-        logger.info(
-            "request_completed",
-            extra={
-                "method": request.method,
-                "path": request.path,
-                "status": response.status_code,
-                "duration_ms": round(duration_ms, 2),
-            },
-        )
-        response["X-Request-Duration-Ms"] = str(round(duration_ms, 2))
-        return response
-```
-
-## Anti-Patterns
-
-- **Business logic in views**: Views should validate input and delegate to model methods or service functions. Keep views thin.
-- **Signal spaghetti**: Overusing signals makes control flow untraceable. Prefer explicit method calls; reserve signals for truly decoupled concerns (e.g., audit logging).
-- **Missing `select_related`/`prefetch_related`**: Accessing related objects in loops without prefetching causes N+1 queries.
-- **Raw SQL in views**: Use the ORM or at minimum `RawSQL` within the queryset API. Raw SQL bypasses Django's protections and is harder to maintain.
-- **Fat serializers with nested writes**: Deeply nested writable serializers are fragile. Use separate endpoints for nested resources.
-
-## Integration Points
-
-- **FastAPI**: Django ORM can be used alongside FastAPI for async needs; see `fastapi-patterns.md`.
-- **Data Pipelines**: Django management commands often serve as ETL entry points; see `data-pipelines.md`.
-- **Python Conventions**: Follow PEP 8 and type hints throughout Django code; see `python-conventions.md`.
-- **Testing**: Use `pytest-django` with fixtures and factory_boy for test data generation.

package/_gaia/dev/knowledge/python/fastapi-patterns.md

@@ -1,164 +0,0 @@
----
-name: FastAPI Application Patterns
-stack: python
-version: "1.0"
-focus: [fastapi]
----
-
-# FastAPI Application Patterns
-
-## Principle
-
-Use Pydantic models for request/response validation and serialization, FastAPI's dependency injection for shared resources (database sessions, auth), async endpoints for I/O-bound work, and background tasks for fire-and-forget operations. Structure the application with routers for modular organization.
-
-## Rationale
-
-FastAPI combines ASGI async performance with automatic OpenAPI documentation generated from Pydantic models and type hints. Dependency injection provides a clean, testable way to manage shared resources like database connections, without global state. Async endpoints allow handling thousands of concurrent connections efficiently, critical for APIs with external service calls or database queries.
-
-## Pattern Examples
-
-### Pattern 1: Pydantic Models and Validation
-
-```python
-from pydantic import BaseModel, Field, EmailStr, field_validator
-from datetime import datetime
-from enum import Enum
-
-
-class UserRole(str, Enum):
-    ADMIN = "admin"
-    MEMBER = "member"
-    VIEWER = "viewer"
-
-
-class CreateUserRequest(BaseModel):
-    email: EmailStr
-    name: str = Field(min_length=1, max_length=100)
-    role: UserRole = UserRole.MEMBER
-    tags: list[str] = Field(default_factory=list, max_length=10)
-
-    @field_validator("name")
-    @classmethod
-    def name_must_not_be_blank(cls, v: str) -> str:
-        if not v.strip():
-            raise ValueError("Name must not be blank")
-        return v.strip()
-
-
-class UserResponse(BaseModel):
-    id: int
-    email: str
-    name: str
-    role: UserRole
-    created_at: datetime
-
-    model_config = {"from_attributes": True}  # enables ORM mode
-```
-
-### Pattern 2: Dependency Injection for DB Sessions
-
-```python
-from fastapi import Depends, FastAPI, HTTPException, status
-from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
-from typing import AsyncGenerator
-
-engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
-SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
-
-
-async def get_db() -> AsyncGenerator[AsyncSession, None]:
-    async with SessionLocal() as session:
-        try:
-            yield session
-            await session.commit()
-        except Exception:
-            await session.rollback()
-            raise
-
-
-async def get_current_user(
-    token: str = Depends(oauth2_scheme),
-    db: AsyncSession = Depends(get_db),
-) -> User:
-    user = await user_repo.get_by_token(db, token)
-    if not user:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid credentials",
-        )
-    return user
-
-
-# Router with dependencies
-router = APIRouter(prefix="/api/v1/users", tags=["users"])
-
-@router.get("/", response_model=list[UserResponse])
-async def list_users(
-    skip: int = 0,
-    limit: int = 20,
-    db: AsyncSession = Depends(get_db),
-    current_user: User = Depends(get_current_user),
-):
-    return await user_repo.get_all(db, skip=skip, limit=limit)
-
-
-@router.post("/", response_model=UserResponse, status_code=201)
-async def create_user(
-    payload: CreateUserRequest,
-    db: AsyncSession = Depends(get_db),
-    current_user: User = Depends(get_current_user),
-):
-    if current_user.role != UserRole.ADMIN:
-        raise HTTPException(status_code=403, detail="Admin required")
-    return await user_repo.create(db, payload)
-```
-
-### Pattern 3: Background Tasks and Error Handling
-
-```python
-from fastapi import BackgroundTasks
-
-
-async def send_welcome_email(email: str, name: str) -> None:
-    """Fire-and-forget background task."""
-    await email_service.send(
-        to=email,
-        subject="Welcome!",
-        body=f"Hello {name}, welcome aboard.",
-    )
-
-
-@router.post("/register", response_model=UserResponse, status_code=201)
-async def register(
-    payload: CreateUserRequest,
-    background_tasks: BackgroundTasks,
-    db: AsyncSession = Depends(get_db),
-):
-    user = await user_repo.create(db, payload)
-    background_tasks.add_task(send_welcome_email, user.email, user.name)
-    return user
-
-
-# Centralized exception handler
-@app.exception_handler(ValueError)
-async def value_error_handler(request, exc):
-    return JSONResponse(
-        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-        content={"detail": str(exc)},
-    )
-```
-
-## Anti-Patterns
-
-- **Sync endpoints for I/O**: Using `def` instead of `async def` for endpoints that call databases or external APIs blocks the event loop.
-- **Business logic in route handlers**: Route functions should validate and delegate. Put logic in service modules or repository classes.
-- **Missing response_model**: Without `response_model`, FastAPI cannot filter sensitive fields or generate accurate OpenAPI docs.
-- **Global database sessions**: Creating a single global session instead of per-request sessions via dependency injection causes concurrency issues.
-- **Catching broad exceptions silently**: `except Exception: pass` hides bugs. Catch specific exceptions and return meaningful errors.
-
-## Integration Points
-
-- **Django**: FastAPI can complement Django for async-heavy workloads; see `django-patterns.md`.
-- **Data Pipelines**: FastAPI endpoints can trigger async pipeline runs; see `data-pipelines.md`.
-- **Python Conventions**: Type hints are mandatory in FastAPI; see `python-conventions.md`.
-- **Testing**: Use `httpx.AsyncClient` with `app` for async test cases.