apsimo 1.3.0__py3-none-any.whl

apsimo/util/temporal.py

@@ -0,0 +1,343 @@
+"""Temporal reference frame for Colony (v0.21.0).
+
+The single source of truth for "now" and timezone handling across the sidecar.
+Everything that needs to reason about wall-clock time — context assembly, the
+timeline tool, briefings, autonomy triggers — should go through this module so
+the agent gets a consistent, editable sense of time.
+
+Three independent, editable timezones (per the design):
+  * AGENT timezone   — where the Colony agent "lives" (its home reference frame).
+                       Editable; defaults to COLONY_AGENT_TIMEZONE, then the host
+                       system tz, then UTC.
+  * CONTACT timezone — a per-contact field (contacts.timezone). Editable per
+                       contact. Lets the agent reason "it's 9am my time / 3pm
+                       theirs".
+  * COMMUNICATION tz — resolved per turn: an explicit override on the turn, else
+                       the contact's tz, else the agent tz.
+
+Stdlib only (datetime + zoneinfo). No third-party deps.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import Optional
+
+try:  # py3.9+
+    from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+except Exception:  # pragma: no cover - very old python
+    ZoneInfo = None  # type: ignore
+    class ZoneInfoNotFoundError(Exception):  # type: ignore
+        pass
+
+logger = logging.getLogger(__name__)
+
+UTC = timezone.utc
+
+
+# --------------------------------------------------------------------------- #
+# State (editable agent / default-contact timezone)                           #
+# --------------------------------------------------------------------------- #
+
+def _state_dir() -> Path:
+    return Path(os.environ.get("COLONY_STATE_DIR", os.path.expanduser("~/.colony")))
+
+
+def _state_path() -> Path:
+    return _state_dir() / "temporal.json"
+
+
+def _load_state() -> dict:
+    try:
+        with open(_state_path()) as f:
+            return json.load(f) or {}
+    except Exception:
+        return {}
+
+
+def _save_state(state: dict) -> None:
+    try:
+        p = _state_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".json.tmp")
+        with open(tmp, "w") as f:
+            json.dump(state, f, indent=2)
+        os.replace(tmp, p)
+    except Exception as exc:  # pragma: no cover
+        logger.warning("Failed to persist temporal state: %s", exc)
+
+
+def is_valid_timezone(tz: Optional[str]) -> bool:
+    if not tz:
+        return False
+    if tz.upper() == "UTC":
+        return True
+    if ZoneInfo is None:
+        return False
+    try:
+        ZoneInfo(tz)
+        return True
+    except (ZoneInfoNotFoundError, ValueError, KeyError):
+        return False
+
+
+def _system_timezone() -> Optional[str]:
+    """Best-effort IANA name of the host's local timezone."""
+    # /etc/localtime symlink → .../zoneinfo/<Area>/<City>
+    try:
+        p = Path("/etc/localtime")
+        if p.is_symlink():
+            target = os.readlink(p)
+            if "zoneinfo/" in target:
+                name = target.split("zoneinfo/", 1)[1]
+                if is_valid_timezone(name):
+                    return name
+    except Exception:
+        pass
+    tz = os.environ.get("TZ")
+    if is_valid_timezone(tz):
+        return tz
+    return None
+
+
+def agent_timezone() -> str:
+    """The agent's home timezone (IANA name). Always returns a usable value."""
+    env = os.environ.get("COLONY_AGENT_TIMEZONE")
+    if is_valid_timezone(env):
+        return env  # type: ignore[return-value]
+    stored = _load_state().get("agent_timezone")
+    if is_valid_timezone(stored):
+        return stored
+    sys_tz = _system_timezone()
+    if sys_tz:
+        return sys_tz
+    return "UTC"
+
+
+def set_agent_timezone(tz: str) -> str:
+    """Persist the agent home timezone. Raises ValueError if invalid."""
+    if not is_valid_timezone(tz):
+        raise ValueError(f"Invalid IANA timezone: {tz!r}")
+    state = _load_state()
+    state["agent_timezone"] = tz
+    _save_state(state)
+    return tz
+
+
+def default_contact_timezone() -> Optional[str]:
+    """Fallback tz for contacts that have none set (optional)."""
+    env = os.environ.get("COLONY_DEFAULT_CONTACT_TIMEZONE")
+    if is_valid_timezone(env):
+        return env  # type: ignore[return-value]
+    stored = _load_state().get("default_contact_timezone")
+    return stored if is_valid_timezone(stored) else None
+
+
+def set_default_contact_timezone(tz: Optional[str]) -> Optional[str]:
+    if tz is not None and not is_valid_timezone(tz):
+        raise ValueError(f"Invalid IANA timezone: {tz!r}")
+    state = _load_state()
+    state["default_contact_timezone"] = tz
+    _save_state(state)
+    return tz
+
+
+def resolve_communication_timezone(
+    contact_tz: Optional[str] = None,
+    override_tz: Optional[str] = None,
+) -> str:
+    """Per-communication tz: explicit override → contact → default → agent."""
+    for cand in (override_tz, contact_tz, default_contact_timezone()):
+        if is_valid_timezone(cand):
+            return cand  # type: ignore[return-value]
+    return agent_timezone()
+
+
+# --------------------------------------------------------------------------- #
+# Now / conversion                                                            #
+# --------------------------------------------------------------------------- #
+
+def _zone(tz: str):
+    if tz.upper() == "UTC" or ZoneInfo is None:
+        return UTC
+    try:
+        return ZoneInfo(tz)
+    except Exception:
+        return UTC
+
+
+def now_utc() -> datetime:
+    return datetime.now(UTC)
+
+
+def now_in(tz: str) -> datetime:
+    return now_utc().astimezone(_zone(tz))
+
+
+def to_zone(dt: datetime, tz: str) -> datetime:
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(_zone(tz))
+
+
+def parse_iso(value) -> Optional[datetime]:
+    """Parse an ISO-8601 string (or pass through a datetime) → aware UTC dt."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    try:
+        s = str(value).strip().replace("Z", "+00:00")
+        dt = datetime.fromisoformat(s)
+        return dt if dt.tzinfo else dt.replace(tzinfo=UTC)
+    except Exception:
+        return None
+
+
+# --------------------------------------------------------------------------- #
+# Human-friendly formatting                                                   #
+# --------------------------------------------------------------------------- #
+
+def part_of_day(dt: datetime) -> str:
+    h = dt.hour
+    if h < 5:
+        return "the middle of the night"
+    if h < 9:
+        return "early morning"
+    if h < 12:
+        return "morning"
+    if h < 14:
+        return "midday"
+    if h < 18:
+        return "afternoon"
+    if h < 22:
+        return "evening"
+    return "night"
+
+
+def format_clock(dt: datetime, tz: Optional[str] = None) -> str:
+    """e.g. 'Thu, Jun 12, 12:37 AM EDT'."""
+    if tz:
+        dt = to_zone(dt, tz)
+    elif dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    label = dt.strftime("%Z") or "UTC"
+    # %-I is platform-specific; strip a leading zero portably.
+    hm = dt.strftime("%I:%M %p").lstrip("0")
+    return f"{dt.strftime('%a, %b %d')}, {hm} {label}"
+
+
+def humanize_delta(ts, ref: Optional[datetime] = None) -> str:
+    """'6h ago', 'in 2d', 'just now'. Accepts datetime or ISO string."""
+    dt = parse_iso(ts)
+    if dt is None:
+        return "unknown"
+    ref = ref or now_utc()
+    if ref.tzinfo is None:
+        ref = ref.replace(tzinfo=UTC)
+    delta = ref - dt
+    secs = delta.total_seconds()
+    future = secs < 0
+    secs = abs(secs)
+
+    if secs < 45:
+        return "just now"
+    if secs < 90 * 60:
+        val, unit = round(secs / 60), "m"
+    elif secs < 36 * 3600:
+        val, unit = round(secs / 3600), "h"
+    elif secs < 14 * 86400:
+        val, unit = round(secs / 86400), "d"
+    elif secs < 8 * 7 * 86400:
+        val, unit = round(secs / (7 * 86400)), "w"
+    elif secs < 365 * 86400:
+        val, unit = round(secs / (30 * 86400)), "mo"
+    else:
+        val, unit = round(secs / (365 * 86400)), "y"
+    return f"in {val}{unit}" if future else f"{val}{unit} ago"
+
+
+def bucket(ts, tz: Optional[str] = None) -> str:
+    """Coarse calendar bucket in the given tz: today / yesterday / this week..."""
+    dt = parse_iso(ts)
+    if dt is None:
+        return "unknown"
+    tz = tz or agent_timezone()
+    local = to_zone(dt, tz)
+    today = now_in(tz).date()
+    d = (today - local.date()).days
+    if d < 0:
+        return "upcoming"
+    if d == 0:
+        return "today"
+    if d == 1:
+        return "yesterday"
+    if d < 7:
+        return "earlier this week"
+    if d < 14:
+        return "last week"
+    if d < 31:
+        return f"{d // 7}w ago"
+    if d < 365:
+        return f"{d // 30}mo ago"
+    return f"{d // 365}y ago"
+
+
+_REL_RE = re.compile(r"^\s*(\d+)\s*([smhdw])\s*$", re.IGNORECASE)
+
+
+def parse_relative_since(value, default_hours: float = 24.0) -> str:
+    """Turn a window spec into an ISO 'since' timestamp (UTC).
+
+    Accepts relative durations ('30m', '24h', '7d', '2w'), the words
+    'today'/'yesterday', or an absolute ISO date/time. Falls back to
+    ``default_hours`` ago when empty/unparseable.
+    """
+    if not value:
+        return (now_utc() - timedelta(hours=default_hours)).isoformat()
+    s = str(value).strip()
+    m = _REL_RE.match(s)
+    if m:
+        n = int(m.group(1))
+        mult = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}[m.group(2).lower()]
+        return (now_utc() - timedelta(seconds=n * mult)).isoformat()
+    low = s.lower()
+    if low in ("today", "yesterday"):
+        local = now_in(agent_timezone())
+        if low == "yesterday":
+            local = local - timedelta(days=1)
+        start = local.replace(hour=0, minute=0, second=0, microsecond=0)
+        return start.astimezone(UTC).isoformat()
+    dt = parse_iso(s)
+    if dt is not None:
+        return dt.isoformat()
+    return (now_utc() - timedelta(hours=default_hours)).isoformat()
+
+
+def hours_since(ts, ref: Optional[datetime] = None) -> Optional[float]:
+    dt = parse_iso(ts)
+    if dt is None:
+        return None
+    ref = ref or now_utc()
+    if ref.tzinfo is None:
+        ref = ref.replace(tzinfo=UTC)
+    return (ref - dt).total_seconds() / 3600.0
+
+
+def describe_now(agent_tz: Optional[str] = None,
+                 contact_tz: Optional[str] = None,
+                 contact_label: str = "their") -> str:
+    """One-line 'now' anchor, optionally with the contact's local time too."""
+    atz = agent_tz or agent_timezone()
+    a_local = now_in(atz)
+    line = f"{format_clock(a_local)} — {part_of_day(a_local)} (your local time, {atz})"
+    if contact_tz and is_valid_timezone(contact_tz) and contact_tz != atz:
+        c_local = now_in(contact_tz)
+        poss = contact_label if contact_label.endswith("s") else f"{contact_label}'s"
+        line += f"\nFor {poss} side it is {format_clock(c_local)} — {part_of_day(c_local)} ({contact_tz})."
+    return line

apsimo/vector/__init__.py

@@ -0,0 +1,75 @@
+"""Colony Vector Store — local LanceDB-backed vector search.
+
+Public API:
+  - VectorStore         — LanceDB wrapper, CRUD + ANN search
+  - EmbeddingPipeline   — provider + caching + latency monitoring
+  - Collection          — enum of named vector collections
+  - get_store()         — retrieve the singleton VectorStore instance
+  - get_pipeline()      — retrieve the singleton EmbeddingPipeline instance
+"""
+
+from apsimo.vector.collections import Collection
+from apsimo.vector.config import EmbeddingConfig, HardwareProfile, VectorStoreConfig
+from apsimo.vector.embedder import (
+    CPUEmbeddingProvider,
+    CUDAEmbeddingProvider,
+    EmbeddingPipeline,
+    EmbeddingProvider,
+    MLXEmbeddingProvider,
+    make_provider,
+)
+from apsimo.vector.query import HybridQuery, VectorItem, VectorQuery, VectorResult
+
+# Lazy import — VectorStore depends on pyarrow/lancedb which may not be installed
+from typing import Any, Optional
+_store: Any = None
+_pipeline: Optional[EmbeddingPipeline] = None
+
+
+def _VectorStore():
+    """Lazy import for VectorStore."""
+    from apsimo.vector.store import VectorStore
+    return VectorStore
+
+
+def set_store(store: Any) -> None:
+    global _store
+    _store = store
+
+
+def set_pipeline(pipeline: EmbeddingPipeline) -> None:
+    global _pipeline
+    _pipeline = pipeline
+
+
+def get_store() -> Any:
+    """Retrieve the singleton VectorStore, or None if not configured."""
+    return _store
+
+
+def get_pipeline() -> Optional[EmbeddingPipeline]:
+    """Retrieve the singleton EmbeddingPipeline, or None if not configured."""
+    return _pipeline
+
+
+__all__ = [
+    "Collection",
+    "EmbeddingConfig",
+    "EmbeddingPipeline",
+    "EmbeddingProvider",
+    "CUDAEmbeddingProvider",
+    "CPUEmbeddingProvider",
+    "MLXEmbeddingProvider",
+    "HardwareProfile",
+    "HybridQuery",
+    "VectorItem",
+    "VectorQuery",
+    "VectorResult",
+    "VectorStore",
+    "VectorStoreConfig",
+    "get_pipeline",
+    "get_store",
+    "make_provider",
+    "set_pipeline",
+    "set_store",
+]

apsimo/vector/backfill.py

@@ -0,0 +1,171 @@
+"""Colony Vector Store — backfill and re-embedding.
+
+Re-embeds all vectors in one or more collections using the current
+embedding pipeline.  Skips rows already tagged with the current model
+(idempotent).  Marks every re-embedded vector with model_id and
+embedded_at metadata.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BackfillResult:
+    """Result of a backfill run."""
+
+    total: int = 0
+    processed: int = 0
+    failed: int = 0
+    skipped: int = 0  # already had current model_id
+    duration_s: float = 0.0
+    errors: list[str] = field(default_factory=list)
+
+
+async def backfill(
+    store,
+    pipeline,
+    collection: Optional[str] = None,
+    batch_size: int = 64,
+    current_model_id: Optional[str] = None,
+) -> BackfillResult:
+    """Re-embed vectors in the store using the current pipeline.
+
+    Parameters
+    ----------
+    store : VectorStore
+        The LanceDB vector store.
+    pipeline : EmbeddingPipeline
+        The current embedding pipeline.
+    collection : str, optional
+        Specific collection to backfill.  If None, backfill all.
+    batch_size : int
+        Number of rows to embed per batch.
+    current_model_id : str, optional
+        The model_id of the current embedder.  Rows with this model_id
+        in their metadata are skipped (idempotent).
+
+    Returns
+    -------
+    BackfillResult
+    """
+    from apsimo.vector.collections import Collection
+
+    start = time.monotonic()
+    result = BackfillResult()
+
+    # Resolve current model_id from pipeline if not provided
+    if current_model_id is None:
+        if hasattr(pipeline, "_provider") and hasattr(pipeline._provider, "_config"):
+            current_model_id = pipeline._provider._config.model_id
+        else:
+            current_model_id = ""
+
+    # Determine collections to process
+    if collection is not None:
+        try:
+            collections = [Collection(collection)]
+        except ValueError:
+            result.errors.append(f"Unknown collection: {collection}")
+            result.duration_s = time.monotonic() - start
+            return result
+    else:
+        collections = list(Collection)
+
+    for col in collections:
+        try:
+            col_result = await _backfill_collection(
+                store, pipeline, col, batch_size, current_model_id
+            )
+            result.total += col_result.total
+            result.processed += col_result.processed
+            result.failed += col_result.failed
+            result.skipped += col_result.skipped
+            result.errors.extend(col_result.errors)
+        except Exception as exc:
+            msg = f"Collection {col.value} backfill failed: {exc}"
+            logger.error(msg)
+            result.errors.append(msg)
+
+    result.duration_s = time.monotonic() - start
+    return result
+
+
+async def _backfill_collection(
+    store,
+    pipeline,
+    collection,
+    batch_size: int,
+    current_model_id: str,
+) -> BackfillResult:
+    """Backfill a single collection."""
+    result = BackfillResult()
+
+    # Scan all rows
+    try:
+        rows = await store.scan_all(collection)
+    except Exception as exc:
+        result.errors.append(f"scan failed: {exc}")
+        return result
+
+    result.total = len(rows)
+
+    # Separate into skip vs re-embed
+    to_embed: list[dict] = []
+    for row in rows:
+        meta_str = row.get("metadata", "{}")
+        try:
+            meta = json.loads(meta_str) if isinstance(meta_str, str) else (meta_str or {})
+        except (json.JSONDecodeError, TypeError):
+            meta = {}
+
+        if current_model_id and meta.get("model_id") == current_model_id:
+            result.skipped += 1
+            continue
+        to_embed.append(row)
+
+    # Batch re-embed
+    now = time.time()
+    for i in range(0, len(to_embed), batch_size):
+        batch = to_embed[i : i + batch_size]
+        texts = [row.get("text", "") for row in batch]
+
+        try:
+            vectors = await pipeline.embed_batch(texts)
+        except Exception as exc:
+            result.failed += len(batch)
+            result.errors.append(f"embed batch failed: {exc}")
+            continue
+
+        # Upsert each row with new vector + metadata
+        for row, vector in zip(batch, vectors):
+            try:
+                meta_str = row.get("metadata", "{}")
+                try:
+                    meta = json.loads(meta_str) if isinstance(meta_str, str) else (meta_str or {})
+                except (json.JSONDecodeError, TypeError):
+                    meta = {}
+                meta["model_id"] = current_model_id
+                meta["embedded_at"] = now
+
+                await store.update(
+                    collection,
+                    id=row["id"],
+                    text=row.get("text", ""),
+                    vector=vector,
+                    metadata=meta,
+                )
+                result.processed += 1
+            except Exception as exc:
+                result.failed += 1
+                result.errors.append(f"update {row.get('id', '?')} failed: {exc}")
+
+    return result

apsimo/vector/caption.py

@@ -0,0 +1,114 @@
+"""Colony Vector — auto-captioning for images.
+
+Generates text captions for images using the host's LLM (if configured)
+or falls back to EXIF/filename-based descriptions.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from apsimo.vector.multimodal_types import ImageInput
+
+logger = logging.getLogger(__name__)
+
+
+async def caption_image(
+    image: ImageInput,
+    llm_config: Optional[dict[str, Any]] = None,
+    max_tokens: int = 50,
+) -> str:
+    """Generate a caption for an image.
+
+    Tries LLM-based captioning first (if credentials available),
+    falls back to EXIF/metadata-based caption.
+    """
+    # Try LLM captioning
+    if llm_config and llm_config.get("api_key"):
+        try:
+            caption = await _llm_caption(image, llm_config, max_tokens)
+            if caption:
+                return caption
+        except Exception as exc:
+            logger.warning("LLM captioning failed: %s — falling back to metadata", exc)
+
+    # Fallback: metadata-based caption
+    return _metadata_caption(image)
+
+
+async def _llm_caption(
+    image: ImageInput,
+    llm_config: dict[str, Any],
+    max_tokens: int,
+) -> str:
+    """Use a vision LLM to generate a caption."""
+    import base64
+    import httpx
+
+    api_key = llm_config.get("api_key", "")
+    base_url = llm_config.get("base_url", "https://open.bigmodel.cn/api/paas/v4")
+    model = llm_config.get("vision_model", llm_config.get("model", "glm-4v-flash"))
+
+    b64 = base64.b64encode(image.data).decode()
+
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.post(
+            f"{base_url}/chat/completions",
+            headers={"Authorization": f"Bearer {api_key}"},
+            json={
+                "model": model,
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": f"Describe this image in {max_tokens} characters or less. Be concise and factual."},
+                            {"type": "image_url", "image_url": {"url": f"data:{image.mime_type};base64,{b64}"}},
+                        ],
+                    }
+                ],
+                "max_tokens": max_tokens,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data["choices"][0]["message"]["content"].strip()
+
+
+def _metadata_caption(image: ImageInput) -> str:
+    """Generate a basic caption from image metadata."""
+    parts: list[str] = []
+
+    # Use user-provided caption if available
+    if image.caption:
+        return image.caption
+
+    # Dimensions
+    if image.width and image.height:
+        parts.append(f"{image.width}x{image.height}")
+
+    # MIME type
+    fmt = image.mime_type.split("/")[-1].upper() if image.mime_type else "Image"
+    parts.insert(0, fmt)
+
+    # EXIF data
+    exif = image.exif
+    if exif.get("captured_at"):
+        parts.append(f"taken {exif['captured_at']}")
+    if exif.get("camera_make") or exif.get("camera_model"):
+        camera = f"{exif.get('camera_make', '')} {exif.get('camera_model', '')}".strip()
+        parts.append(f"camera: {camera}")
+
+    # GPS
+    if exif.get("gps_lat") and exif.get("gps_lon"):
+        parts.append(f"location: {exif['gps_lat']},{exif['gps_lon']}")
+
+    # File path hint
+    if image.original_path:
+        from pathlib import Path
+        name = Path(image.original_path).stem
+        if name and not name.startswith("data:"):
+            parts.insert(0, name.replace("-", " ").replace("_", " "))
+
+    caption = " — ".join(parts) if parts else "Image"
+    return caption[:200]  # Cap length