affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/query/aggregates.py

@@ -0,0 +1,357 @@
+"""Aggregate functions for query results.
+
+This module provides aggregation functions like sum, avg, count, etc.
+It is CLI-only and NOT part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import statistics
+from collections import defaultdict
+from typing import Any
+
+from .filters import resolve_field_path
+from .models import AggregateFunc, HavingClause
+
+# =============================================================================
+# Aggregate Functions
+# =============================================================================
+
+
+def compute_sum(records: list[dict[str, Any]], field: str) -> float:
+    """Compute sum of a field across records."""
+    total = 0.0
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                total += float(value)
+    return total
+
+
+def compute_avg(records: list[dict[str, Any]], field: str) -> float | None:
+    """Compute average of a field across records."""
+    values: list[float] = []
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                values.append(float(value))
+
+    if not values:
+        return None
+    return sum(values) / len(values)
+
+
+def compute_min(records: list[dict[str, Any]], field: str) -> Any:
+    """Compute minimum value of a field across records."""
+    values: list[Any] = []
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            values.append(value)
+
+    if not values:
+        return None
+    return min(values)
+
+
+def compute_max(records: list[dict[str, Any]], field: str) -> Any:
+    """Compute maximum value of a field across records."""
+    values: list[Any] = []
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            values.append(value)
+
+    if not values:
+        return None
+    return max(values)
+
+
+def compute_count(records: list[dict[str, Any]], field: str | bool | None = None) -> int:
+    """Compute count of records.
+
+    Args:
+        records: List of records
+        field: If True or None, count all records.
+               If a string, count records where field is not null.
+    """
+    if field is None or field is True:
+        return len(records)
+
+    if isinstance(field, str):
+        count = 0
+        for record in records:
+            value = resolve_field_path(record, field)
+            if value is not None:
+                count += 1
+        return count
+
+    return len(records)
+
+
+def compute_percentile(records: list[dict[str, Any]], field: str, p: int | float) -> float | None:
+    """Compute percentile of a field across records.
+
+    Args:
+        records: List of records
+        field: Field to compute percentile for
+        p: Percentile value (0-100)
+
+    Returns:
+        The percentile value, or None if no valid values
+    """
+    values: list[float] = []
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                values.append(float(value))
+
+    if not values:
+        return None
+
+    values.sort()
+    # Convert percentile to quantile (0-1)
+    quantile = p / 100.0
+    return (
+        statistics.quantiles(values, n=100)[int(quantile * 99)] if len(values) >= 2 else values[0]
+    )
+
+
+def compute_first(records: list[dict[str, Any]], field: str) -> Any:
+    """Get first non-null value of a field."""
+    for record in records:
+        value = resolve_field_path(record, field)
+        if value is not None:
+            return value
+    return None
+
+
+def compute_last(records: list[dict[str, Any]], field: str) -> Any:
+    """Get last non-null value of a field."""
+    for record in reversed(records):
+        value = resolve_field_path(record, field)
+        if value is not None:
+            return value
+    return None
+
+
+# =============================================================================
+# Expression Aggregates
+# =============================================================================
+
+
+def compute_expression(
+    values: dict[str, Any],
+    operation: str,
+    operands: list[str | int | float],
+) -> float | None:
+    """Compute an expression aggregate.
+
+    Args:
+        values: Dict of computed aggregate values
+        operation: One of "multiply", "divide", "add", "subtract"
+        operands: List of aggregate names or literal numbers
+
+    Returns:
+        Computed value, or None if any operand is None
+    """
+    resolved: list[float] = []
+    for operand in operands:
+        if isinstance(operand, (int, float)):
+            resolved.append(float(operand))
+        elif isinstance(operand, str):
+            value = values.get(operand)
+            if value is None:
+                return None
+            try:
+                resolved.append(float(value))
+            except (ValueError, TypeError):
+                return None
+
+    if len(resolved) < 2:
+        return None
+
+    result = resolved[0]
+    for val in resolved[1:]:
+        if operation == "multiply":
+            result *= val
+        elif operation == "divide":
+            if val == 0:
+                return None
+            result /= val
+        elif operation == "add":
+            result += val
+        elif operation == "subtract":
+            result -= val
+
+    return result
+
+
+# =============================================================================
+# Main Aggregation Function
+# =============================================================================
+
+
+def compute_aggregates(
+    records: list[dict[str, Any]],
+    aggregates: dict[str, AggregateFunc],
+) -> dict[str, Any]:
+    """Compute all aggregates for a set of records.
+
+    Args:
+        records: List of records to aggregate
+        aggregates: Dict of aggregate name -> AggregateFunc
+
+    Returns:
+        Dict of aggregate name -> computed value
+    """
+    results: dict[str, Any] = {}
+    expression_aggs: list[tuple[str, str, list[str | int | float]]] = []
+
+    # First pass: compute non-expression aggregates
+    for name, agg_func in aggregates.items():
+        if agg_func.sum is not None:
+            results[name] = compute_sum(records, agg_func.sum)
+        elif agg_func.avg is not None:
+            results[name] = compute_avg(records, agg_func.avg)
+        elif agg_func.min is not None:
+            results[name] = compute_min(records, agg_func.min)
+        elif agg_func.max is not None:
+            results[name] = compute_max(records, agg_func.max)
+        elif agg_func.count is not None:
+            results[name] = compute_count(records, agg_func.count)
+        elif agg_func.percentile is not None:
+            field = agg_func.percentile.get("field", "")
+            p = agg_func.percentile.get("p", 50)
+            results[name] = compute_percentile(records, field, p)
+        elif agg_func.first is not None:
+            results[name] = compute_first(records, agg_func.first)
+        elif agg_func.last is not None:
+            results[name] = compute_last(records, agg_func.last)
+        elif agg_func.multiply is not None:
+            expression_aggs.append((name, "multiply", agg_func.multiply))
+        elif agg_func.divide is not None:
+            expression_aggs.append((name, "divide", agg_func.divide))
+        elif agg_func.add is not None:
+            expression_aggs.append((name, "add", agg_func.add))
+        elif agg_func.subtract is not None:
+            expression_aggs.append((name, "subtract", agg_func.subtract))
+
+    # Second pass: compute expression aggregates
+    for name, operation, operands in expression_aggs:
+        results[name] = compute_expression(results, operation, operands)
+
+    return results
+
+
+def group_and_aggregate(
+    records: list[dict[str, Any]],
+    group_by: str,
+    aggregates: dict[str, AggregateFunc],
+) -> list[dict[str, Any]]:
+    """Group records and compute aggregates for each group.
+
+    Args:
+        records: List of records to group
+        group_by: Field to group by
+        aggregates: Dict of aggregate name -> AggregateFunc
+
+    Returns:
+        List of result dicts, one per group, sorted with null values at end
+    """
+    groups: dict[Any, list[dict[str, Any]]] = defaultdict(list)
+
+    def make_hashable(value: Any) -> Any:
+        """Convert unhashable types (lists) to hashable types (tuples).
+
+        For multi-select fields, we sort the values so that different orderings
+        (e.g., ["Team", "Market"] vs ["Market", "Team"]) are treated as the same group.
+        """
+        if isinstance(value, list):
+            try:
+                return tuple(sorted(value))
+            except TypeError:
+                # If values aren't sortable, fall back to original order
+                return tuple(value)
+        return value
+
+    for record in records:
+        key = resolve_field_path(record, group_by)
+        hashable_key = make_hashable(key)
+        groups[hashable_key].append(record)
+
+    results: list[dict[str, Any]] = []
+    null_result: dict[str, Any] | None = None
+
+    for key, group_records in groups.items():
+        agg_values = compute_aggregates(group_records, aggregates)
+
+        # Convert tuple back to list for display, use "(no value)" for null
+        display_key: Any
+        if key is None:
+            display_key = "(no value)"
+        elif isinstance(key, tuple):
+            display_key = list(key)
+        else:
+            display_key = key
+        result = {group_by: display_key, **agg_values}
+
+        # Collect null group separately to append at end
+        if key is None:
+            null_result = result
+        else:
+            results.append(result)
+
+    # Append null group at end if present
+    if null_result is not None:
+        results.append(null_result)
+
+    return results
+
+
+def apply_having(
+    results: list[dict[str, Any]],
+    having: HavingClause,
+) -> list[dict[str, Any]]:
+    """Apply HAVING clause to filter aggregated results.
+
+    Args:
+        results: List of aggregated result dicts
+        having: HAVING clause to apply
+
+    Returns:
+        Filtered list of results
+    """
+    from .filters import matches
+
+    # Convert HavingClause to WhereClause for filtering
+    # (They have the same structure for simple conditions)
+    from .models import WhereClause
+
+    # Build a WhereClause from HavingClause
+    if having.path is not None and having.op is not None:
+        where = WhereClause(path=having.path, op=having.op, value=having.value)
+    elif having.and_ is not None:
+        where = WhereClause(
+            and_=[
+                WhereClause(path=h.path, op=h.op, value=h.value)
+                for h in having.and_
+                if h.path is not None
+            ]
+        )
+    elif having.or_ is not None:
+        where = WhereClause(
+            or_=[
+                WhereClause(path=h.path, op=h.op, value=h.value)
+                for h in having.or_
+                if h.path is not None
+            ]
+        )
+    else:
+        return results
+
+    return [r for r in results if matches(r, where)]

affinity/cli/query/dates.py

@@ -0,0 +1,194 @@
+"""Relative date parsing for query WHERE clauses.
+
+This module provides parsing for relative date strings like "-30d", "today", etc.
+It is CLI-only and NOT part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+# =============================================================================
+# Patterns
+# =============================================================================
+
+# Pattern for relative dates: -30d, +7d, -4w, -3m, -1y
+RELATIVE_DATE_PATTERN = re.compile(r"^([+-]?\d+)([dwmy])$")
+
+# Pattern for ISO dates
+ISO_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?")
+
+
+# =============================================================================
+# Parsing Functions
+# =============================================================================
+
+
+def parse_relative_date(
+    value: str,
+    *,
+    now: datetime | None = None,
+    use_utc: bool = True,
+) -> datetime:
+    """Parse relative date strings.
+
+    Supports:
+    - Relative: "-30d", "+7d", "-4w", "-3m", "-1y"
+    - Keywords: "today", "now", "yesterday", "tomorrow"
+
+    Args:
+        value: The date string to parse
+        now: Reference time (defaults to current UTC time)
+        use_utc: If True and now is None, use UTC; otherwise use local time
+
+    Returns:
+        Resolved datetime
+
+    Raises:
+        ValueError: If the date string is invalid
+    """
+    if now is None:
+        now = datetime.now(timezone.utc) if use_utc else datetime.now()
+
+    value_lower = value.lower().strip()
+
+    # Keywords
+    if value_lower == "now":
+        return now
+    if value_lower == "today":
+        return now.replace(hour=0, minute=0, second=0, microsecond=0)
+    if value_lower == "yesterday":
+        yesterday = now - timedelta(days=1)
+        return yesterday.replace(hour=0, minute=0, second=0, microsecond=0)
+    if value_lower == "tomorrow":
+        tomorrow = now + timedelta(days=1)
+        return tomorrow.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    # Relative date pattern
+    match = RELATIVE_DATE_PATTERN.match(value_lower)
+    if match:
+        amount = int(match.group(1))
+        unit = match.group(2)
+
+        if unit == "d":
+            return now + timedelta(days=amount)
+        elif unit == "w":
+            return now + timedelta(weeks=amount)
+        elif unit == "m":
+            # Approximate month as 30 days
+            return now + timedelta(days=amount * 30)
+        elif unit == "y":
+            # Approximate year as 365 days
+            return now + timedelta(days=amount * 365)
+
+    raise ValueError(f"Invalid relative date: {value}")
+
+
+def parse_date_value(value: str) -> datetime | None:
+    """Try to parse a value as a date.
+
+    Attempts to parse as:
+    1. Relative date (-30d, today, etc.)
+    2. ISO date string
+
+    Args:
+        value: The value to parse
+
+    Returns:
+        datetime if parseable, None otherwise
+    """
+    # Skip if not a string
+    if not isinstance(value, str):
+        return None
+
+    value = value.strip()
+    if not value:
+        return None
+
+    # Try relative date
+    try:
+        return parse_relative_date(value)
+    except ValueError:
+        pass
+
+    # Try ISO date
+    if ISO_DATE_PATTERN.match(value):
+        try:
+            # Handle with and without time component
+            if "T" in value:
+                return datetime.fromisoformat(value.replace("Z", "+00:00"))
+            else:
+                return datetime.fromisoformat(value)
+        except ValueError:
+            pass
+
+    return None
+
+
+def days_since(date: datetime, *, now: datetime | None = None) -> int:
+    """Calculate days since a date.
+
+    Args:
+        date: The date to calculate from
+        now: Reference time (defaults to current UTC)
+
+    Returns:
+        Number of days since the date (positive if in past)
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    # Make both timezone-aware or both naive for comparison
+    if date.tzinfo is None and now.tzinfo is not None:
+        date = date.replace(tzinfo=timezone.utc)
+    elif date.tzinfo is not None and now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    delta = now - date
+    return delta.days
+
+
+def days_until(date: datetime, *, now: datetime | None = None) -> int:
+    """Calculate days until a date.
+
+    Args:
+        date: The target date
+        now: Reference time (defaults to current UTC)
+
+    Returns:
+        Number of days until the date (positive if in future)
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    # Make both timezone-aware or both naive for comparison
+    if date.tzinfo is None and now.tzinfo is not None:
+        date = date.replace(tzinfo=timezone.utc)
+    elif date.tzinfo is not None and now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    delta = date - now
+    return delta.days
+
+
+def is_relative_date(value: str) -> bool:
+    """Check if a value looks like a relative date.
+
+    Args:
+        value: The value to check
+
+    Returns:
+        True if it looks like a relative date string
+    """
+    if not isinstance(value, str):
+        return False
+
+    value_lower = value.lower().strip()
+
+    # Keywords
+    if value_lower in ("now", "today", "yesterday", "tomorrow"):
+        return True
+
+    # Relative pattern
+    return bool(RELATIVE_DATE_PATTERN.match(value_lower))

affinity/cli/query/exceptions.py

@@ -0,0 +1,147 @@
+"""Query engine exceptions.
+
+These exceptions are specific to the query engine and are CLI-only.
+They are NOT part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .models import PlanStep
+
+
+class QueryError(Exception):
+    """Base class for query engine errors."""
+
+    pass
+
+
+class QueryParseError(QueryError):
+    """Raised when query parsing or validation fails.
+
+    Examples:
+        - Invalid JSON syntax
+        - Unknown operator
+        - Invalid field path
+        - Type mismatch in value
+        - Unsupported query version
+    """
+
+    def __init__(self, message: str, *, field: str | None = None) -> None:
+        self.field = field
+        if field:
+            message = f"{field}: {message}"
+        super().__init__(message)
+
+
+class QueryValidationError(QueryError):
+    """Raised when query passes parsing but fails semantic validation.
+
+    Examples:
+        - Aggregate with include (not allowed)
+        - Unknown entity type
+        - Invalid relationship path
+        - groupBy with incompatible aggregate
+    """
+
+    def __init__(self, message: str, *, field: str | None = None) -> None:
+        self.field = field
+        if field:
+            message = f"{field}: {message}"
+        super().__init__(message)
+
+
+class QueryPlanError(QueryError):
+    """Raised when execution plan cannot be generated.
+
+    Examples:
+        - Circular dependency in plan steps
+        - Unknown entity in schema registry
+    """
+
+    pass
+
+
+class QueryExecutionError(QueryError):
+    """Raised during query execution.
+
+    Examples:
+        - API call failed
+        - Authentication error
+        - Rate limiting exhausted
+        - Timeout exceeded
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        step: PlanStep | None = None,
+        cause: Exception | None = None,
+        partial_results: list[Any] | None = None,
+    ) -> None:
+        self.step = step
+        self.cause = cause
+        self.partial_results = partial_results
+        super().__init__(message)
+
+
+class QueryInterruptedError(QueryError):
+    """Raised when query execution is interrupted (e.g., Ctrl+C).
+
+    Carries partial results that were collected before interruption.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        step_id: int | None = None,
+        records_fetched: int = 0,
+        partial_results: list[Any] | None = None,
+    ) -> None:
+        self.step_id = step_id
+        self.records_fetched = records_fetched
+        self.partial_results = partial_results
+        super().__init__(message)
+
+
+class QueryTimeoutError(QueryExecutionError):
+    """Raised when query execution exceeds the timeout."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        timeout_seconds: float,
+        elapsed_seconds: float,
+        step: PlanStep | None = None,
+        partial_results: list[Any] | None = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.elapsed_seconds = elapsed_seconds
+        super().__init__(message, step=step, partial_results=partial_results)
+
+
+class QuerySafetyLimitError(QueryError):
+    """Raised when query would exceed safety limits.
+
+    Examples:
+        - Estimated records > max_records
+        - Estimated API calls > threshold
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        limit_name: str,
+        limit_value: int,
+        estimated_value: int,
+    ) -> None:
+        self.limit_name = limit_name
+        self.limit_value = limit_value
+        self.estimated_value = estimated_value
+        super().__init__(message)