apsimo 1.3.0__py3-none-any.whl

apsimo/contacts/transport_ingress.py

@@ -0,0 +1,252 @@
+"""Metadata receipts for a transport-owned durable inbox, in the communications DB.
+
+No message bodies or attachment bytes belong here. A claimed handoff is deliberately
+not retried: only an actual canonical turn receipt can settle its processing.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+
+
+def ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript('''
+        CREATE TABLE IF NOT EXISTS transport_ingress (
+            receipt_id TEXT PRIMARY KEY, producer TEXT NOT NULL,
+            account_id TEXT NOT NULL, epoch TEXT NOT NULL, sequence INTEGER NOT NULL,
+            event_id TEXT NOT NULL, contact_id TEXT, occurred_at REAL NOT NULL,
+            journal_ref TEXT NOT NULL, payload_digest TEXT NOT NULL,
+            media_available INTEGER NOT NULL, metadata_json TEXT NOT NULL,
+            state TEXT NOT NULL DEFAULT 'admitted', batch_id TEXT,
+            native_turn_json TEXT, source_versions_json TEXT,
+            outcome TEXT, created_at REAL NOT NULL, completed_at REAL,
+            UNIQUE(producer,account_id,epoch,sequence));
+        CREATE INDEX IF NOT EXISTS transport_ingress_native
+            ON transport_ingress(native_turn_json,state);
+        CREATE TABLE IF NOT EXISTS transport_ingress_coverage (
+            producer TEXT NOT NULL, account_id TEXT NOT NULL, epoch TEXT NOT NULL,
+            connected_since REAL, observed_at REAL NOT NULL, watermark INTEGER NOT NULL,
+            connected INTEGER NOT NULL, unavailable INTEGER NOT NULL,
+            sequence_floor INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY(producer,account_id));
+    ''')
+    columns = {row[1] for row in conn.execute('PRAGMA table_info(transport_ingress_coverage)')}
+    if 'sequence_floor' not in columns:
+        conn.execute('ALTER TABLE transport_ingress_coverage ADD COLUMN sequence_floor INTEGER NOT NULL DEFAULT 0')
+    conn.commit()
+
+
+def _json(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), allow_nan=False)
+
+
+def _text(value, name, limit=512):
+    if not isinstance(value, str) or not value or len(value) > limit:
+        raise ValueError('invalid_ingress_' + name)
+    return value
+
+
+class TransportIngress:
+    """Use the caller's existing CommsLog connection and transaction lifetime."""
+
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+
+    def get(self, receipt_id):
+        row = self.conn.execute('SELECT * FROM transport_ingress WHERE receipt_id=?',
+                                (receipt_id,)).fetchone()
+        return dict(row) if row else None
+
+    def admit(self, *, producer, account_id, epoch, sequence, event_id, contact_id,
+              occurred_at, journal_ref, payload_digest, media_available, metadata=None,
+              now=None):
+        now = time.time() if now is None else float(now)
+        for name, value in [('producer', producer), ('account_id', account_id),
+                            ('epoch', epoch), ('event_id', event_id), ('journal_ref', journal_ref)]:
+            _text(value, name)
+        if (type(sequence) is not int or sequence < 1 or type(media_available) is not bool
+                or not 0 < float(occurred_at) <= now + 1
+                or len(payload_digest) != 64 or any(c not in '0123456789abcdef' for c in payload_digest)):
+            raise ValueError('invalid_ingress_envelope')
+        if contact_id is not None:
+            _text(contact_id, 'contact_id', 128)
+        metadata = dict(metadata or {})
+        if set(metadata) - {'channel', 'sender_ref', 'reply_to_ref', 'from_owner', 'is_group'}:
+            raise ValueError('ingress_metadata_only')
+        if len(_json(metadata)) > 2048:
+            raise ValueError('ingress_metadata_too_large')
+        receipt_id = 'ingress:' + hashlib.sha256(_json([producer, account_id, epoch, sequence]).encode()).hexdigest()
+        fields = dict(producer=producer, account_id=account_id, epoch=epoch, sequence=sequence,
+                      event_id=event_id, contact_id=contact_id, occurred_at=float(occurred_at),
+                      journal_ref=journal_ref, payload_digest=payload_digest,
+                      media_available=int(media_available), metadata_json=_json(metadata))
+        with self.conn:
+            old = self.get(receipt_id)
+            if old:
+                if old['state'] == 'erased':
+                    if any(old[key] != fields[key] for key in ('event_id', 'journal_ref', 'payload_digest')):
+                        raise ValueError('ingress_event_conflict')
+                    return self.view(old)
+                # A retained provider event can acquire its missing attachment later.
+                # No claimed turn or identity/timestamp may be rewritten by repair.
+                repair = (old['state'] == 'admitted' and not old['media_available']
+                          and fields['media_available'] == 1
+                          and all(old[key] == val for key, val in fields.items()
+                                  if key not in {'payload_digest', 'media_available'}))
+                if repair:
+                    self.conn.execute('UPDATE transport_ingress SET payload_digest=?,media_available=1 '
+                                      'WHERE receipt_id=?', (payload_digest, receipt_id))
+                    return self.view(self.get(receipt_id))
+                if any(old[key] != val for key, val in fields.items()):
+                    raise ValueError('ingress_event_conflict')
+                return self.view(old)
+            columns = ','.join(fields)
+            self.conn.execute(f'INSERT INTO transport_ingress (receipt_id,{columns},created_at) '
+                              f'VALUES ({",".join("?" for _ in range(len(fields)+2))})',
+                              (receipt_id, *fields.values(), now))
+        return self.view(self.get(receipt_id))
+
+    @staticmethod
+    def view(row):
+        return {key: row[key] for key in ('receipt_id', 'state', 'batch_id', 'journal_ref',
+                                         'media_available', 'source_versions_json', 'outcome')}
+
+    def handoff(self, *, producer, receipt_ids, batch_id, native_turn=None):
+        _text(batch_id, 'batch_id', 128)
+        ids = sorted(set(receipt_ids))
+        if not ids or len(ids) > 100:
+            raise ValueError('invalid_ingress_batch')
+        native = None
+        if native_turn is not None:
+            if set(native_turn) != {'session_id', 'task_id', 'turn_id'}:
+                raise ValueError('invalid_ingress_native_turn')
+            native = _json({key: _text(value, key, 256) for key, value in native_turn.items()})
+        with self.conn:
+            self.conn.execute('BEGIN IMMEDIATE')
+            rows = [self.get(receipt) for receipt in ids]
+            if any(not row or row['producer'] != producer for row in rows):
+                raise ValueError('ingress_receipt_scope_mismatch')
+            if any(row['state'] not in {'admitted', 'handed_off'} or not row['media_available'] for row in rows):
+                raise ValueError('ingress_not_ready')
+            if any(row['batch_id'] not in (None, batch_id) for row in rows):
+                raise ValueError('ingress_handoff_conflict')
+            if native and any(row['native_turn_json'] not in (None, native) for row in rows):
+                raise ValueError('ingress_native_turn_conflict')
+            may_dispatch = all(row['state'] == 'admitted' for row in rows)
+            if native and may_dispatch:
+                raise ValueError('ingress_handoff_required_before_native_binding')
+            for row in rows:
+                self.conn.execute('UPDATE transport_ingress SET state=?,batch_id=?, '
+                                  'native_turn_json=COALESCE(native_turn_json,?) WHERE receipt_id=?',
+                                  ('handed_off', batch_id, native, row['receipt_id']))
+        return {'receipt_ids': ids, 'batch_id': batch_id, 'may_dispatch': may_dispatch,
+                'native_bound': native is not None, 'processing_complete': False}
+
+    def complete(self, *, native_turn, source_versions, outcome, now=None):
+        """Call only after canonical source admission; not exposed to a model tool."""
+        if not source_versions or outcome not in {'captured', 'interrupted', 'failed'}:
+            raise ValueError('canonical_ingress_completion_required')
+        for key, value in source_versions.items():
+            _text(key, 'source_id'); _text(value, 'source_version')
+        stamp = time.time() if now is None else now
+        rows = self.conn.execute('SELECT * FROM transport_ingress WHERE native_turn_json=?',
+                                 (_json(native_turn),)).fetchall()
+        with self.conn:
+            for row in rows:
+                if row['state'] == 'erased':
+                    continue
+                if row['state'] == 'completed':
+                    if row['source_versions_json'] != _json(source_versions) or row['outcome'] != outcome:
+                        raise ValueError('ingress_completion_conflict')
+                    continue
+                self.conn.execute('UPDATE transport_ingress SET state=?,source_versions_json=?, '
+                                  'outcome=?,completed_at=? WHERE receipt_id=?',
+                                  ('completed', _json(source_versions), outcome, stamp, row['receipt_id']))
+        return [self.view(self.get(row['receipt_id'])) for row in rows]
+
+    def for_canonical_turn(self, *, turn_id, contact_id):
+        """Unique native tuple bound by the transport producer, never a text match."""
+        rows = self.conn.execute("SELECT * FROM transport_ingress WHERE contact_id=? "
+                                 "AND native_turn_json IS NOT NULL AND state!='erased'", (contact_id,)).fetchall()
+        rows = [row for row in rows if json.loads(row['native_turn_json']).get('turn_id') == turn_id]
+        tuples = {row['native_turn_json'] for row in rows}
+        return ([dict(row) for row in rows] if len(tuples) == 1 else [])
+
+    def receipts(self, *, producer, receipt_ids):
+        if len(receipt_ids) > 100:
+            raise ValueError('invalid_ingress_batch')
+        rows = [self.get(receipt) for receipt in receipt_ids]
+        if any(not row or row['producer'] != producer for row in rows):
+            raise ValueError('ingress_receipt_scope_mismatch')
+        return [self.view(row) for row in rows]
+
+    def erase_sources(self, source_ids):
+        """Return locators root must erase at the sole payload owner, idempotently."""
+        wanted = set(source_ids)
+        rows = self.conn.execute('SELECT * FROM transport_ingress WHERE source_versions_json IS NOT NULL '
+                                 'OR native_turn_json IS NOT NULL').fetchall()
+        selected = [row for row in rows if wanted.intersection(json.loads(row['source_versions_json'] or '{}'))
+                    or json.loads(row['native_turn_json'] or '{}').get('turn_id') in wanted]
+        with self.conn:
+            for row in selected:
+                self.conn.execute("UPDATE transport_ingress SET state='erased',metadata_json='{}',"
+                                  "contact_id=NULL WHERE receipt_id=?", (row['receipt_id'],))
+        return [{'receipt_id': row['receipt_id'], 'journal_ref': row['journal_ref']} for row in selected]
+
+    def observe_coverage(self, *, producer, account_id, epoch, connected_since, observed_at,
+                         watermark, connected, unavailable, sequence_floor=0, now=None):
+        stamp = time.time() if now is None else float(now)
+        if (type(watermark) is not int or watermark < 0 or type(connected) is not bool
+                or type(sequence_floor) is not int or not 0 <= sequence_floor <= watermark
+                or type(unavailable) is not int or unavailable < 0
+                or not 0 < float(observed_at) <= stamp + 1
+                or (connected and (connected_since is None or not 0 < connected_since <= observed_at))):
+            raise ValueError('invalid_ingress_coverage')
+        old = self.conn.execute('SELECT * FROM transport_ingress_coverage WHERE producer=? AND account_id=?',
+                                (producer, account_id)).fetchone()
+        if old and (observed_at < old['observed_at'] or (epoch == old['epoch'] and watermark < old['watermark'])):
+            raise ValueError('ingress_coverage_regression')
+        with self.conn:
+            self.conn.execute('INSERT OR REPLACE INTO transport_ingress_coverage VALUES (?,?,?,?,?,?,?,?,?)',
+                              (producer, account_id, epoch, connected_since, observed_at,
+                               watermark, int(connected), unavailable, sequence_floor))
+
+    def coverage(self, *, producer, account_id, contact_id, since, now=None, max_age=5,
+                 until=None, observation=None):
+        """Read current coverage or recheck a retained internal observation.
+
+        A fixed horizon excludes later activity from that earlier interval.
+        Rechecking a stored observation still queries current intake/erasure
+        records; it never treats a retained coverage hash as timeless proof.
+        """
+        now = time.time() if now is None else now
+        row = observation if observation is not None else self.conn.execute(
+            'SELECT * FROM transport_ingress_coverage WHERE producer=? AND account_id=?',
+            (producer, account_id)).fetchone()
+        if observation is not None and (row['producer'] != producer or row['account_id'] != account_id):
+            raise ValueError('coverage_observation_scope_mismatch')
+        if until is not None and not since <= until <= now:
+            raise ValueError('invalid_coverage_interval')
+        reasons = []
+        if not row or not row['connected'] or row['connected_since'] is None or row['connected_since'] > since:
+            reasons.append('connection_interval_unknown')
+        if not row or now - row['observed_at'] > max_age:
+            reasons.append('intake_observation_stale')
+        if row:
+            admitted = self.conn.execute('SELECT COUNT(*) FROM transport_ingress WHERE producer=? '
+                'AND account_id=? AND epoch=? AND sequence>? AND sequence<=?',
+                (producer, account_id, row['epoch'], row['sequence_floor'], row['watermark'])).fetchone()[0]
+            if admitted != row['watermark'] - row['sequence_floor'] or row['unavailable']:
+                reasons.append('intake_gap')
+        activity = self.conn.execute('SELECT receipt_id,state,metadata_json FROM transport_ingress '
+            'WHERE producer=? AND account_id=? AND occurred_at>=? AND '
+            '(contact_id=? OR contact_id IS NULL)'+(' AND occurred_at<=?' if until is not None else ''),
+            (producer, account_id, since, contact_id, *([until] if until is not None else []))).fetchall()
+        activity = [item for item in activity if not json.loads(item['metadata_json']).get('from_owner')]
+        if activity:
+            reasons.append('recipient_activity_requires_review')
+        return {'observed': not reasons, 'reasons': reasons, 'observed_through': row['observed_at'] if row else None,
+                'watermark': row['watermark'] if row else None, 'activity_receipts': [r['receipt_id'] for r in activity],
+                'effect_authorized': False}

apsimo/contacts/world_bridge.py

@@ -0,0 +1,314 @@
+"""Colony Contacts — World Model Bridge.
+
+Synchronises Neo4j :Person nodes with the SQLite ContactStore so that
+discovered people become visible to the contacts API while preserving
+the architectural separation between curated and discovered contacts.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .models import Contact
+from .store import SQLiteContactStore, _name_similarity, _normalize_email, _normalize_phone
+
+logger = logging.getLogger("colony.contacts.world_bridge")
+
+
+def _person_handle_gaps(person: Dict[str, Any]) -> List[tuple[str, str]]:
+    """Extract (gateway, address) pairs from a Person node's properties."""
+    handles: List[tuple[str, str]] = []
+    phone = person.get("phone")
+    if phone:
+        norm = _normalize_phone(str(phone))
+        if norm:
+            handles.append(("imessage", norm))
+    email = person.get("email")
+    if email:
+        norm = _normalize_email(str(email))
+        if norm:
+            handles.append(("email", norm))
+    return handles
+
+
+class WorldModelContactBridge:
+    """Creates and maintains shadow contacts from Neo4j Person nodes.
+
+    Shadow contacts:
+    - trust_tier = "acquaintance"
+    - interaction_allowed = False
+    - import_source = "world_model"
+    - person_node_id = Person.id
+
+    The bridge deduplicates against existing curated contacts by
+    person_node_id, overlapping handles, or high name similarity.
+    """
+
+    def __init__(
+        self,
+        graph,  # ColonyGraph instance
+        store: SQLiteContactStore,
+        min_signals: int = 2,
+        min_memories: int = 2,
+        name_match_threshold: float = 0.85,
+    ) -> None:
+        self._graph = graph
+        self._store = store
+        self._min_signals = min_signals
+        self._min_memories = min_memories
+        self._name_match_threshold = name_match_threshold
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    async def sync_person_to_contact(self, person_id: str) -> Optional[Contact]:
+        """Ensure a single Person node is reflected as a contact.
+
+        Returns the existing or newly-created contact, or None if the
+        person does not meet the substance threshold.
+        """
+        person = await self._graph.get_person(person_id)
+        if not person:
+            logger.debug("sync_person_to_contact: Person %s not found in graph", person_id)
+            return None
+
+        if not person.get("name"):
+            logger.debug("sync_person_to_contact: Person %s has no name, skipping", person_id)
+            return None
+
+        # Check substance threshold
+        handles = _person_handle_gaps(person)
+        has_handle = bool(handles)
+
+        # We also accept persons with signals/memories — graph query already
+        # filters, but for single-person sync we do a lightweight check.
+        if not has_handle:
+            # Need to verify signals/memories via graph
+            people = await self._graph.get_people_with_substance(
+                min_signals=self._min_signals,
+                min_memories=self._min_memories,
+            )
+            if not any(p["id"] == person_id for p in people):
+                logger.debug(
+                    "sync_person_to_contact: Person %s lacks substance (no handle, < %d signals/memories)",
+                    person_id, self._min_signals,
+                )
+                return None
+
+        # Deduplication: check for existing contact
+        existing = await self._find_existing_contact(person_id, person.get("name"), handles)
+        if existing:
+            # Ensure person_node_id is linked
+            if not existing.person_node_id:
+                await self._store.update(existing.contact_id, person_node_id=person_id)
+                existing.person_node_id = person_id
+            logger.debug(
+                "sync_person_to_contact: Person %s matched existing contact %s",
+                person_id, existing.contact_id,
+            )
+            return existing
+
+        # Create shadow contact
+        contact = await self._store.create(
+            display_name=person.get("name"),
+            trust_tier="acquaintance",
+            interaction_allowed=False,
+            import_source="world_model",
+            notes=person.get("notes") or None,
+        )
+        await self._store.update(contact.contact_id, person_node_id=person_id)
+        contact.person_node_id = person_id
+
+        # Attach handles from Person properties
+        for gateway, address in handles:
+            try:
+                await self._store.add_handle(
+                    contact.contact_id,
+                    gateway,
+                    address,
+                    is_primary=True,
+                    source="world_model",
+                    confidence=0.7,
+                )
+            except ValueError:
+                # Handle already owned by another contact (possible race or
+                # overlap with curated contact created since dedup check)
+                logger.debug(
+                    "sync_person_to_contact: handle conflict for %s %s on person %s",
+                    gateway, address, person_id,
+                )
+
+        logger.info(
+            "Created shadow contact %s for Person %s (%s)",
+            contact.contact_id, person_id, person.get("name"),
+        )
+        return contact
+
+    async def backfill_all_people(self) -> Dict[str, int]:
+        """One-shot backfill of all substantive Person nodes into contacts.
+
+        Returns counters: {"created": int, "linked": int, "skipped": int}
+        """
+        people = await self._graph.get_people_with_substance(
+            min_signals=self._min_signals,
+            min_memories=self._min_memories,
+        )
+        stats = {"created": 0, "linked": 0, "skipped": 0}
+        for person in people:
+            person_id = person["id"]
+            name = person.get("name")
+            handles = _person_handle_gaps(person)
+
+            existing = await self._find_existing_contact(person_id, name, handles)
+            if existing:
+                if not existing.person_node_id:
+                    await self._store.update(existing.contact_id, person_node_id=person_id)
+                    stats["linked"] += 1
+                else:
+                    stats["skipped"] += 1
+                continue
+
+            contact = await self._store.create(
+                display_name=name,
+                trust_tier="acquaintance",
+                interaction_allowed=False,
+                import_source="world_model",
+                notes=person.get("notes") or None,
+            )
+            await self._store.update(contact.contact_id, person_node_id=person_id)
+
+            for gateway, address in handles:
+                try:
+                    await self._store.add_handle(
+                        contact.contact_id, gateway, address,
+                        is_primary=True, source="world_model", confidence=0.7,
+                    )
+                except ValueError:
+                    pass
+
+            stats["created"] += 1
+            logger.info(
+                "Backfill: created shadow contact %s for Person %s (%s)",
+                contact.contact_id, person_id, name,
+            )
+
+        logger.info(
+            "Backfill complete: created=%d linked=%d skipped=%d total_people=%d",
+            stats["created"], stats["linked"], stats["skipped"], len(people),
+        )
+        return stats
+
+    async def absorb_discovered_contact(
+        self,
+        curated_contact_id: str,
+        discovered_contact: Contact,
+    ) -> bool:
+        """Absorb a discovered contact into a curated one.
+
+        Copies person_node_id and handles, then soft-deletes the discovered
+        contact. Returns True if anything was absorbed.
+        """
+        if discovered_contact.import_source != "world_model":
+            return False
+
+        updates: Dict[str, Any] = {}
+        if discovered_contact.person_node_id and not (
+            await self._store.find_by_person_node_id(discovered_contact.person_node_id)
+        ):
+            updates["person_node_id"] = discovered_contact.person_node_id
+
+        if updates:
+            await self._store.update(curated_contact_id, **updates)
+
+        # Migrate handles
+        handles = await self._store.get_handles(discovered_contact.contact_id)
+        for h in handles:
+            try:
+                await self._store.add_handle(
+                    curated_contact_id,
+                    h.gateway,
+                    h.address,
+                    is_primary=h.is_primary,
+                    source=f"absorbed:{h.source}",
+                    confidence=h.confidence,
+                )
+            except ValueError:
+                # Handle already on curated contact — fine
+                pass
+
+        await self._store.soft_delete(
+            discovered_contact.contact_id,
+            reason=f"absorbed_into:{curated_contact_id}",
+            performed_by="system",
+        )
+        await self._store.record_audit(
+            curated_contact_id,
+            "absorbed_discovered",
+            {
+                "absorbed_contact_id": discovered_contact.contact_id,
+                "person_node_id": discovered_contact.person_node_id,
+            },
+        )
+        logger.info(
+            "Absorbed discovered contact %s into curated %s",
+            discovered_contact.contact_id, curated_contact_id,
+        )
+        return True
+
+    async def prune_orphaned_shadows(self) -> int:
+        """Soft-delete shadow contacts whose Person node no longer exists.
+
+        Returns the number of contacts pruned.
+        """
+        # Fetch all shadow contacts with person_node_id
+        shadow_contacts = await self._store.list(
+            trust_tier="acquaintance", limit=10000,
+        )
+        if not shadow_contacts:
+            return 0
+
+        alive_ids = set(await self._graph.list_person_ids())
+        pruned = 0
+        for contact in shadow_contacts:
+            if not contact.person_node_id:
+                continue
+            if contact.person_node_id not in alive_ids:
+                await self._store.soft_delete(
+                    contact.contact_id,
+                    reason="orphaned_person_node",
+                    performed_by="system",
+                )
+                pruned += 1
+                logger.info(
+                    "Pruned orphaned shadow contact %s (Person %s deleted from graph)",
+                    contact.contact_id, contact.person_node_id,
+                )
+        return pruned
+
+    # ── Internal helpers ─────────────────────────────────────────────────────────────
+
+    async def _find_existing_contact(
+        self,
+        person_id: str,
+        name: Optional[str],
+        handles: List[tuple[str, str]],
+    ) -> Optional[Contact]:
+        """Check if a Person already has a matching contact (curated or discovered)."""
+        # 1. Exact person_node_id match
+        contact = await self._store.find_by_person_node_id(person_id)
+        if contact:
+            return contact
+
+        # 2. Handle overlap
+        for gateway, address in handles:
+            contact = await self._store.resolve_handle(gateway, address)
+            if contact:
+                return contact
+
+        # 3. Name similarity
+        if name:
+            matches = await self._store.find_by_name(name, threshold=self._name_match_threshold)
+            if matches:
+                return matches[0]
+
+        return None

apsimo/contextgate/__init__.py

@@ -0,0 +1,69 @@
+"""Context gate — decide per-call whether context fits a model whole,
+or needs chunking + retrieval (RAG) / map-reduce summarization first.
+
+Motivation: a model's *useful* context window (the range over which exact
+retrieval stays reliable) is often far below its advertised maximum.
+Stuffing a 200K document into such a model silently degrades recall.
+The gate measures the input against a configurable per-model budget
+(``TierConfig.useful_context_tokens`` or an explicit budget) and picks
+one of three strategies:
+
+- ``PASS_THROUGH``  — fits; send whole.
+- ``RETRIEVE``      — query-focused task; chunk, rank chunks against the
+                      query (embeddings when available, lexical TF-IDF
+                      otherwise), and pack the best chunks into budget.
+- ``MAP_REDUCE``    — holistic task (summarize/review the whole thing);
+                      summarize chunks via a caller-provided LLM callable,
+                      or fall back to evenly-spaced coverage sampling.
+
+Everything is host-agnostic and dependency-free (pure stdlib); embedding
+and summarization are injected as optional callables so any agent can use
+it with whatever LLM/embedding stack it already has.
+
+Usage::
+
+    from apsimo.contextgate import prepare_context
+
+    prepared = await prepare_context(
+        content=big_document,
+        query="when did the outage start?",
+        budget_tokens=65536,
+    )
+    messages = [{"role": "user", "content": prepared.text}]
+
+Configuration (env, all optional):
+
+- ``COLONY_CONTEXT_GATE``            — ``auto`` (default) | ``on`` | ``off``
+- ``COLONY_CONTEXT_GATE_HEADROOM``   — fraction of budget that triggers
+  gating (default 0.8)
+- ``COLONY_CONTEXT_GATE_BUDGET``     — default token budget when neither
+  the caller nor the model tier provides one (default 0 = no gating)
+- ``COLONY_CONTEXT_CHUNK_TOKENS``    — target chunk size (default 1024)
+- ``COLONY_CONTEXT_OVERLAP_TOKENS``  — chunk overlap (default 128)
+- ``COLONY_CONTEXT_CHARS_PER_TOKEN`` — token estimator ratio (default 4.0)
+"""
+
+from apsimo.contextgate.estimate import estimate_tokens
+from apsimo.contextgate.chunker import Chunk, chunk_text
+from apsimo.contextgate.retrieve import rank_chunks
+from apsimo.contextgate.gate import (
+    GateConfig,
+    GateDecision,
+    PreparedContext,
+    classify_task,
+    decide,
+    prepare_context,
+)
+
+__all__ = [
+    "Chunk",
+    "GateConfig",
+    "GateDecision",
+    "PreparedContext",
+    "chunk_text",
+    "classify_task",
+    "decide",
+    "estimate_tokens",
+    "prepare_context",
+    "rank_chunks",
+]