topos-node 1.2.4__tar.gz → 1.2.6__tar.gz

{topos_node-1.2.4/topos_node.egg-info → topos_node-1.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.2.4
+Version: 1.2.6
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai
@@ -213,6 +213,76 @@ pip install -e ".[dev,engine]"
 pytest tests -m "public and not e2e" -q
 ```
 
+## Plugins
+
+Topos Node supports **optional plugins**: separate Python packages installed alongside
+`topos-node` that register handlers, connectors, or other runtime hooks. The core node
+does not hardcode plugin names — discovery is entirely via setuptools entry points.
+
+### Contract: `topos.extensions`
+
+| Rule | Detail |
+| --- | --- |
+| **Entry-point group** | `topos.extensions` |
+| **Entry-point target** | A callable, e.g. `my_plugin:register` |
+| **When it runs** | At process startup, before the server accepts traffic (`topos/extensions.py`) |
+| **Failure mode** | A broken plugin is logged and skipped; the node keeps running |
+| **Dependencies** | Your plugin declares `topos-node` (or `topos-node[local]`) in its own `pyproject.toml` |
+
+**Minimal plugin**
+
+`pyproject.toml`:
+
+```toml
+[project]
+name = "my-topos-plugin"
+dependencies = ["topos-node[local]"]
+
+[project.entry-points."topos.extensions"]
+my_plugin = "my_topos_plugin:register"
+```
+
+`my_topos_plugin/__init__.py`:
+
+```python
+def register() -> None:
+    from my_topos_plugin.handlers import example  # noqa: F401 — registers @handles
+```
+
+`my_topos_plugin/handlers/example.py`:
+
+```python
+from typing import Any, Dict, Optional
+from topos.core.handlers.registry import handles
+
+@handles("my_message_type")
+async def handle_my_message(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    return {"status": "ok", "payload": {"received": message.get("type")}}
+```
+
+**Install and run**
+
+```bash
+pip install topos-node my-topos-plugin
+topos-node
+```
+
+Handlers registered in `register()` are available to the control-plane WebSocket
+and local API paths that dispatch through `topos.core.handlers`.
+
+### Starter template
+
+Fork **[dialoguesai/topos-plugin-template](https://github.com/dialoguesai/topos-plugin-template)**
+for a working package with tests and CI. It registers a sample `plugin_template_ping`
+handler you can copy and rename.
+
+### Guidelines
+
+- Use **unique message type names** (prefix with your project) to avoid colliding with core handlers.
+- Keep plugins in **separate repositories** — do not add proprietary logic to this repo.
+- Message types your plugin handles do not need to appear in the public engine protocol
+  snapshot unless the hosted control plane will send them to all nodes.
+
 ## Contributing
 
 See `CONTRIBUTING.md` for:

{topos_node-1.2.4 → topos_node-1.2.6}/README.md

@@ -156,6 +156,76 @@ pip install -e ".[dev,engine]"
 pytest tests -m "public and not e2e" -q
 ```
 
+## Plugins
+
+Topos Node supports **optional plugins**: separate Python packages installed alongside
+`topos-node` that register handlers, connectors, or other runtime hooks. The core node
+does not hardcode plugin names — discovery is entirely via setuptools entry points.
+
+### Contract: `topos.extensions`
+
+| Rule | Detail |
+| --- | --- |
+| **Entry-point group** | `topos.extensions` |
+| **Entry-point target** | A callable, e.g. `my_plugin:register` |
+| **When it runs** | At process startup, before the server accepts traffic (`topos/extensions.py`) |
+| **Failure mode** | A broken plugin is logged and skipped; the node keeps running |
+| **Dependencies** | Your plugin declares `topos-node` (or `topos-node[local]`) in its own `pyproject.toml` |
+
+**Minimal plugin**
+
+`pyproject.toml`:
+
+```toml
+[project]
+name = "my-topos-plugin"
+dependencies = ["topos-node[local]"]
+
+[project.entry-points."topos.extensions"]
+my_plugin = "my_topos_plugin:register"
+```
+
+`my_topos_plugin/__init__.py`:
+
+```python
+def register() -> None:
+    from my_topos_plugin.handlers import example  # noqa: F401 — registers @handles
+```
+
+`my_topos_plugin/handlers/example.py`:
+
+```python
+from typing import Any, Dict, Optional
+from topos.core.handlers.registry import handles
+
+@handles("my_message_type")
+async def handle_my_message(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    return {"status": "ok", "payload": {"received": message.get("type")}}
+```
+
+**Install and run**
+
+```bash
+pip install topos-node my-topos-plugin
+topos-node
+```
+
+Handlers registered in `register()` are available to the control-plane WebSocket
+and local API paths that dispatch through `topos.core.handlers`.
+
+### Starter template
+
+Fork **[dialoguesai/topos-plugin-template](https://github.com/dialoguesai/topos-plugin-template)**
+for a working package with tests and CI. It registers a sample `plugin_template_ping`
+handler you can copy and rename.
+
+### Guidelines
+
+- Use **unique message type names** (prefix with your project) to avoid colliding with core handlers.
+- Keep plugins in **separate repositories** — do not add proprietary logic to this repo.
+- Message types your plugin handles do not need to appear in the public engine protocol
+  snapshot unless the hosted control plane will send them to all nodes.
+
 ## Contributing
 
 See `CONTRIBUTING.md` for:

{topos_node-1.2.4 → topos_node-1.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.2.4"
+version = "1.2.6"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"

topos_node-1.2.6/tests/test_extensions.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import pytest
+
+from topos.core.handlers.registry import handles
+from topos.extensions import load_extensions
+
+
+@pytest.mark.public
+def test_load_extensions_does_not_raise_when_no_plugins_installed() -> None:
+    load_extensions()
+
+
+@pytest.mark.public
+def test_load_extensions_invokes_entry_point_callables(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[str] = []
+
+    def _init() -> None:
+        seen.append("ran")
+
+    class _FakeEntryPoint:
+        name = "test"
+
+        def load(self) -> object:
+            return _init
+
+    monkeypatch.setattr(
+        "topos.extensions._iter_extension_entry_points",
+        lambda: [_FakeEntryPoint()],
+    )
+    load_extensions()
+    assert seen == ["ran"]

{topos_node-1.2.4 → topos_node-1.2.6}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.2.4"
-__version_info__ = (1, 2, 4)
+__version__ = "1.2.6"
+__version_info__ = (1, 2, 6)
 
 __all__ = ["__version__", "__version_info__"]

{topos_node-1.2.4 → topos_node-1.2.6}/topos/api/llm.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import hashlib
+import logging
 
 from fastapi import APIRouter, Depends
 
@@ -10,6 +11,8 @@ from ..engine.usage_observation import emit_usage_observation
 from ..rate_limit import rate_limit
 from ..services.container import Services, get_services
 
+logger = logging.getLogger("topos.api.llm")
+
 router = APIRouter()
 
 
@@ -19,6 +22,12 @@ router = APIRouter()
     dependencies=[Depends(require_api_key), Depends(rate_limit)],
 )
 async def llm_generation(body: GenerationRequest):
+    logger.info(
+        "llm_generation request: provider=%r model=%r prompt_chars=%d",
+        body.provider,
+        body.model,
+        len(body.prompt or ""),
+    )
     services: Services = get_services()
     result = await services.llm.generate(body.model_dump())
     usage = result.get("usage") if isinstance(result, dict) else {}
@@ -45,6 +54,12 @@ async def llm_generation(body: GenerationRequest):
     dependencies=[Depends(require_api_key), Depends(rate_limit)],
 )
 async def llm_generation_alias(body: GenerationRequest):
+    logger.info(
+        "llm_generation request (alias): provider=%r model=%r prompt_chars=%d",
+        body.provider,
+        body.model,
+        len(body.prompt or ""),
+    )
     services: Services = get_services()
     result = await services.llm.generate(body.model_dump())
     usage = result.get("usage") if isinstance(result, dict) else {}

{topos_node-1.2.4 → topos_node-1.2.6}/topos/api/signal.py

@@ -232,11 +232,13 @@ async def list_entities(
 # as an entity id.
 @router.get("/entities/graph")
 async def get_entity_graph(
-    limit_nodes: int = Query(default=100, ge=1, le=500),
-    limit_edges: int = Query(default=300, ge=1, le=1500),
+    limit_nodes: int = Query(default=100, ge=1, le=5000),
+    limit_edges: int = Query(default=300, ge=1, le=20000),
     min_weight: float = Query(default=0.0, ge=0.0),
     include_closed: bool = Query(default=False),
     as_of: Optional[str] = Query(default=None),
+    selection: str = Query(default="weight"),
+    offset: int = Query(default=0, ge=0),
     _api_key: str = Depends(require_api_key),
 ):
     """Entity-spine graph (decayed typed edges) in list_graph node/edge shape.
@@ -244,16 +246,25 @@ async def get_entity_graph(
     Each edge carries valid_from/valid_to/last_event_at. ``as_of`` (ISO date)
     returns the graph as it stood at that instant (temporal scrubber);
     ``include_closed`` adds ended edges to the present view.
+
+    ``selection=weight`` (default) ranks by weight for MCP/minimal slices;
+    ``selection=all`` ranks by recency for the owner knowledge-graph UI.
     """
+    import asyncio
+
     from ..features.entities.reads import entity_graph
 
-    return entity_graph(
-        _entities_conn(),
+    conn = _entities_conn()
+    return await asyncio.to_thread(
+        entity_graph,
+        conn,
         limit_nodes=limit_nodes,
         limit_edges=limit_edges,
         min_weight=min_weight,
         include_closed=include_closed,
         as_of=as_of,
+        selection=selection,
+        offset=offset,
     )
 
 

topos_node-1.2.6/topos/api/tool_index.py

@@ -0,0 +1,91 @@
+"""Tool-RAG endpoints: sync the tool index, retrieve top-K tools for a query.
+
+PLAN_AGENT_QUALITY WS-3 (M2). The chat orchestration (topos-react-app) pushes
+the gateway's tool list here after ``tools/list`` (hash-deduped upsert → cheap
+no-op when unchanged) and calls ``/v1/tools/retrieve`` per turn to build a
+focused tool doc sized to the model instead of a flat 52-tool dump.
+
+Handlers are sync ``def`` on purpose: the embedding path is blocking HF
+inference, and FastAPI runs sync handlers in its threadpool.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from ..auth import require_api_key
+from ..core.state import get_db_connection
+from ..features.signal.tool_index import index_status, index_tools, retrieve_tools
+from ..rate_limit import rate_limit
+
+router = APIRouter()
+
+
+class ToolSpecIn(BaseModel):
+    name: str
+    description: str = ""
+    connector_id: Optional[str] = None
+
+
+class IndexToolsRequest(BaseModel):
+    tools: List[ToolSpecIn] = Field(default_factory=list, max_length=2000)
+    # Prune index rows absent from this payload (full-list syncs only).
+    prune_missing: bool = False
+
+
+class RetrieveToolsRequest(BaseModel):
+    query: str
+    connector_scope: Optional[str] = None
+    k: int = 8
+    # Per-connector identity-tool override (PLAN_HELP_NUDGE A2): bare names to
+    # ride along beyond IDENTITY_TOOL_NAMES, for connectors whose identity tool
+    # has a nonstandard name (e.g. GraphQL ``viewer``).
+    identity_tools: Optional[List[str]] = None
+
+
+def _require_conn():
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="Database unavailable")
+    return conn
+
+
+@router.post(
+    "/v1/tools/index",
+    dependencies=[Depends(require_api_key), Depends(rate_limit)],
+)
+def tools_index(body: IndexToolsRequest):
+    conn = _require_conn()
+    specs = [spec.model_dump() for spec in body.tools if str(spec.name or "").strip()]
+    if not specs and not body.prune_missing:
+        raise HTTPException(status_code=422, detail="tools must be a non-empty list")
+    return index_tools(conn, specs, prune_missing=body.prune_missing)
+
+
+@router.post(
+    "/v1/tools/retrieve",
+    dependencies=[Depends(require_api_key), Depends(rate_limit)],
+)
+def tools_retrieve(body: RetrieveToolsRequest):
+    if not str(body.query or "").strip():
+        raise HTTPException(status_code=422, detail="query is required")
+    conn = _require_conn()
+    return retrieve_tools(
+        conn,
+        body.query,
+        connector_scope=body.connector_scope,
+        k=body.k,
+        extra_identity_names=body.identity_tools or (),
+    )
+
+
+@router.get(
+    "/v1/tools/index/status",
+    dependencies=[Depends(require_api_key), Depends(rate_limit)],
+)
+def tools_index_status():
+    conn = _require_conn()
+    return index_status(conn)

{topos_node-1.2.4 → topos_node-1.2.6}/topos/app.py

@@ -45,10 +45,12 @@ from .api import (
     home_chat as home_chat_routes,
     privacy_disclose as privacy_disclose_routes,
     signal as signal_routes,
+    tool_index as tool_index_routes,
     upgrades as upgrades_routes,
 )
 from .config.settings import settings
 from .core.logging import align_uvicorn_loggers, configure_logging
+from .extensions import load_extensions
 from .core import state
 from .core.handlers import handle_control_plane_request
 from .control_plane_client import ControlPlaneClient
@@ -65,6 +67,7 @@ from .sync import SyncClient
 from .sync_handlers import handle_sync_op
 
 configure_logging()
+load_extensions()
 logger = logging.getLogger("topos.app")
 
 app = FastAPI(
@@ -128,10 +131,15 @@ app.include_router(privacy_disclose_routes.router)
 app.include_router(compute_remote_routes.router)
 app.include_router(engine_run_routes.router)
 app.include_router(data_commit_routes.router)
+app.include_router(tool_index_routes.router)
 
 
 @app.on_event("startup")
 async def startup_event() -> None:
+    from .runtime_shutdown import clear_shutdown, install_shutdown_signal_hooks
+
+    clear_shutdown()
+    install_shutdown_signal_hooks()
     align_uvicorn_loggers()
     _log_runtime_banner()
     logger.info("CORS allowed origins: %s", settings.allowed_origins)
@@ -199,6 +207,16 @@ async def startup_event() -> None:
             )
     except Exception as e:
         logger.warning("Active source install rehydration at startup failed (non-fatal): %s", e)
+    if getattr(settings, "sanitization_prewarm_on_startup", True):
+        async def _prewarm_sanitization() -> None:
+            try:
+                from .sanitization.prewarm import prewarm_sanitization_models
+
+                await asyncio.to_thread(prewarm_sanitization_models)
+            except Exception as prewarm_exc:  # noqa: BLE001
+                logger.warning("Sanitization prewarm at startup failed (non-fatal): %s", prewarm_exc)
+
+        asyncio.create_task(_prewarm_sanitization())
     if settings.topos_control_plane_url:
         if settings.hosted_pool_lease_enabled:
             try:
@@ -296,6 +314,11 @@ async def startup_event() -> None:
 
 @app.on_event("shutdown")
 async def shutdown_event() -> None:
+    from .runtime_shutdown import request_shutdown
+
+    # Wake cooperative workers (fact_llm / Ollama threads) before awaiting
+    # network teardown so Ctrl+C does not wait out a full enrichment batch.
+    request_shutdown("app_shutdown")
     await stop_runtime_update_monitor()
     if state.engine_presence_task:
         state.engine_presence_task.cancel()

{topos_node-1.2.4 → topos_node-1.2.6}/topos/canonicalization/mappers/__init__.py

@@ -13,7 +13,9 @@ from .demo_mappers import (
     DemoPlacesMapper,
     DemoProfileMapper,
 )
+from .documents_mapper import DocumentsCanonicalMapper
 from .github_activity_mapper import GithubActivityCanonicalMapper
+from .google_calendar_mapper import GoogleCalendarMapper
 from .grok_mapper import GrokCanonicalMapper
 from .messenger_mapper import ImessageCanonicalMapper, SignalCanonicalMapper, VoxtermTranscriptCanonicalMapper
 
@@ -33,13 +35,17 @@ MAPPER_REGISTRY = {
     "demo_places": DemoPlacesMapper,
     "demo_contacts": DemoContactsMapper,
     "journal_time_log": JournalTimeLogMapper,
+    "documents": DocumentsCanonicalMapper,
+    "google_calendar": GoogleCalendarMapper,
 }
 
 __all__ = [
     "BrowserActivityCanonicalMapper",
     "CanonicalMapper",
     "ChatGPTCanonicalMapper",
+    "DocumentsCanonicalMapper",
     "GithubActivityCanonicalMapper",
+    "GoogleCalendarMapper",
     "GrokCanonicalMapper",
     "ImessageCanonicalMapper",
     "SignalCanonicalMapper",

topos_node-1.2.6/topos/canonicalization/mappers/documents_mapper.py

@@ -0,0 +1,43 @@
+"""Documents canonical mapper (PLAN_CANONICAL_CALENDAR_DOCUMENTS Part A).
+
+Notion pages and Google Drive files both normalize to the same pinned
+documents shape before reaching this mapper: doc_id, title, content, url,
+mime_type, author, created_at, modified_at. Producing that shape from each
+connector's native tool output (Notion's structured JSON, Drive's file
+metadata) is a client/CP-side shaping concern (PLAN §A7, save-to-Topos
+capability) — a separate, follow-up change. ``map()`` here is deliberately a
+thin, near-identity read of the already-normalized keys (with a fallback to
+the ingest record_id for doc_id), the same shape for both sources, which is
+why one mapper class serves both ``notion_pages`` and ``gdrive_files``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...ingestion.parsers.base import NormalizedRecord
+from .base import CanonicalMapper, CanonicalRecord, MappingMetadata
+
+
+@dataclass
+class DocumentsCanonicalMapper(CanonicalMapper):
+    version: str = "v1"
+
+    def map(self, normalized: NormalizedRecord) -> CanonicalRecord:
+        p = normalized.payload
+        doc_id = str(p.get("doc_id") or normalized.record_id)
+        canonical = {
+            "doc_id": doc_id,
+            "title": p.get("title"),
+            "content": p.get("content"),
+            "url": p.get("url"),
+            "mime_type": p.get("mime_type"),
+            "author": p.get("author"),
+            "created_at": p.get("created_at"),
+            "modified_at": p.get("modified_at"),
+            "source_record_id": doc_id,
+        }
+        return CanonicalRecord(record_id=doc_id, payload=canonical)
+
+    def mapping_metadata(self, normalized: NormalizedRecord) -> MappingMetadata:
+        return MappingMetadata(source_id="documents", mapping_version=self.version)

{topos_node-1.2.4 → topos_node-1.2.6}/topos/canonicalization/mappers/github_activity_mapper.py

@@ -5,6 +5,15 @@ Additionally, each commit inside a PushEvent ``payload.commits[]`` maps to one
 ``journal_entries`` row — a commit reads like a work-journal entry (category
 'code', content = commit message). Only PushEvent commits fan out; PRs/issues
 stay activity-only.
+
+Journal-lane policy (strict): when a commit carries an ``authorship`` field
+(authored | ai_assisted | participated | bot — stamped by callers that know the
+owner's login and can detect AI co-author trailers / bot authors), only
+``authored`` commits become journal entries; the rest stay activity-only.
+External contributions and AI-generated commits are how the owner's time was
+spent (activity), not the owner's personal words (journal). Commits without the
+field (legacy webhook/UI-stream payloads) keep the historical all-commits
+behavior.
 """
 
 from __future__ import annotations
@@ -160,6 +169,17 @@ class GithubActivityCanonicalMapper(CanonicalMapper):
             sha = str(commit.get("sha") or "").strip()
             if not sha:
                 continue  # no deterministic identity without a sha
+            # Journal-lane policy (strict): only commits the owner personally
+            # authored read as journal entries. Callers that can classify (they
+            # know the owner's login + can detect AI co-author trailers / bots)
+            # stamp `authorship` on each commit: authored | ai_assisted |
+            # participated | bot. Anything non-authored stays activity-only —
+            # external contributions and AI-generated commits are how time was
+            # spent, not the owner's personal journal. Absent field (legacy
+            # webhook/UI-stream payloads) keeps the historical behavior.
+            authorship = str(commit.get("authorship") or "").strip().lower() or None
+            if authorship is not None and authorship != "authored":
+                continue
             entry_id = f"github:{repo_name}:{sha}" if repo_name else f"github:{sha}"
             entry_at = _commit_timestamp(commit) or created_at
             metadata: Dict[str, Any] = {
@@ -168,6 +188,7 @@ class GithubActivityCanonicalMapper(CanonicalMapper):
                 "ref": ref,
                 "branch": branch,
                 "event_id": f"github:{event_record_id}",
+                "authorship": authorship,
             }
             journal = {
                 "entry_id": entry_id,