agentgraph-server 0.5.0__py3-none-any.whl

agentgraph/connectors/status.py

@@ -0,0 +1,244 @@
+"""Connector and auth-provider status formatting shared by CLI and MCP."""
+
+from __future__ import annotations
+
+import inspect
+from datetime import UTC, datetime, timedelta
+from typing import cast
+
+from agentgraph.connectors.base import BaseConnector
+from agentgraph.core.storage import StorageBackend
+
+
+def auth_provider_key(connector: BaseConnector) -> str:
+    return getattr(connector, "auth_label", None) or connector.source
+
+
+def connector_uses_auth(connector: BaseConnector) -> bool:
+    return getattr(type(connector), "appears_in_auth_status", True)
+
+
+def auth_provider_connectors(
+    connectors: list[BaseConnector],
+    *,
+    include_non_auth: bool = False,
+) -> dict[str, list[BaseConnector]]:
+    grouped: dict[str, list[BaseConnector]] = {}
+    for connector in connectors:
+        if not include_non_auth and not connector_uses_auth(connector):
+            continue
+        grouped.setdefault(auth_provider_key(connector), []).append(connector)
+    return grouped
+
+
+def run_auth_provider_flow(
+    connectors: list[BaseConnector],
+    provider: str,
+    *,
+    account_id: str | None = None,
+    add: bool = False,
+    args: list[str] | None = None,
+) -> None:
+    """Dispatch an authentication flow through a provider's representative connector."""
+    grouped = auth_provider_connectors(connectors)
+    members = grouped.get(provider)
+    if not members:
+        available = ", ".join(sorted(grouped))
+        raise ValueError(f"Unknown auth provider {provider!r}. Available: {available}")
+
+    connector_cls = type(members[0])
+    provider_args = args or []
+    auth_hook = getattr(connector_cls, "run_auth_flow_with_args", None)
+    if callable(auth_hook):
+        auth_hook(provider_args, account_id=account_id, add=add)
+        return
+
+    auth_flow = connector_cls.run_auth_flow
+    if "args" in inspect.signature(auth_flow).parameters:
+        auth_flow(account_id=account_id, add=add, args=provider_args)
+        return
+    if provider_args:
+        raise ValueError(
+            f"{provider!r} does not accept auth options: {' '.join(provider_args)}"
+        )
+    auth_flow()
+
+
+def _list_accounts(connector: BaseConnector) -> list[object]:
+    list_accounts = getattr(type(connector), "list_accounts", None)
+    if callable(list_accounts):
+        return cast(list[object], list_accounts())
+    return []
+
+
+async def _verify_auth(
+    connector: BaseConnector,
+    account_id: str | None = None,
+) -> tuple[str, str | None]:
+    verify_auth = type(connector).verify_auth
+    try:
+        return await verify_auth(account_id)
+    except TypeError:
+        return await verify_auth()
+
+
+def _aggregate_auth_status(statuses: list[tuple[str, str | None]]) -> tuple[str, str | None]:
+    if any(status == "invalid" for status, _ in statuses):
+        return next(item for item in statuses if item[0] == "invalid")
+    if any(status == "ok" for status, _ in statuses):
+        return ("ok", f"{len(statuses)} account(s)")
+    return ("missing", None)
+
+
+def _local_auth_status(
+    connector: BaseConnector,
+    accounts: list[object],
+) -> tuple[str, str | None]:
+    if accounts:
+        return ("ok", f"{len(accounts)} account(s)")
+    user = type(connector).get_authenticated_user()
+    if user is not None:
+        return ("ok", user)
+    return ("missing", None)
+
+
+async def auth_provider_status_items(
+    connectors: list[BaseConnector],
+    *,
+    verify: bool = False,
+    include_non_auth: bool = False,
+) -> list[dict[str, object]]:
+    """Build JSON-serialisable auth-provider status rows."""
+    items: list[dict[str, object]] = []
+    for provider, members in auth_provider_connectors(
+        connectors,
+        include_non_auth=include_non_auth,
+    ).items():
+        representative = members[0]
+        accounts = _list_accounts(representative)
+        account_rows: list[dict[str, object]] = []
+        statuses: list[tuple[str, str | None]] = []
+        for account in accounts:
+            account_id = getattr(account, "account_id", None)
+            status, detail = (
+                await _verify_auth(representative, account_id)
+                if verify
+                else ("ok", getattr(account, "label", None))
+            )
+            account_rows.append({
+                "account_id": getattr(account, "account_id", None),
+                "label": getattr(account, "label", None),
+                "user_id": getattr(account, "user_id", None),
+                "workspace_id": getattr(account, "workspace_id", None),
+                "email": getattr(account, "email", None),
+                "auth_method": getattr(account, "auth_method", None),
+                "auth_status": status,
+                "auth_detail": detail,
+            })
+            statuses.append((status, detail))
+        auth_status, auth_detail = (
+            _aggregate_auth_status(statuses)
+            if statuses
+            else await _verify_auth(representative)
+            if verify
+            else _local_auth_status(representative, accounts)
+        )
+        connector_sources = [connector.source for connector in members]
+        items.append({
+            "provider": provider,
+            "description": f"Shared auth for {', '.join(connector_sources)}"
+            if len(connector_sources) > 1
+            else type(representative).auth_description or provider,
+            "connectors": connector_sources,
+            "shared": len(connector_sources) > 1,
+            "auth_status": auth_status,
+            "auth_detail": auth_detail,
+            "auth_verified": verify,
+            "accounts": account_rows,
+        })
+    return items
+
+
+async def connector_status_items(
+    connectors: list[BaseConnector],
+    backend: StorageBackend,
+    *,
+    verify: bool = False,
+) -> list[dict[str, object]]:
+    """Build JSON-serialisable connector status rows."""
+    provider_items = await auth_provider_status_items(connectors, verify=verify)
+    provider_by_key = {str(item["provider"]): item for item in provider_items}
+
+    poll_delegators: dict[str, list[str]] = {}
+    for connector in connectors:
+        for delegated_source in type(connector).poll_delegates:
+            poll_delegators.setdefault(delegated_source, []).append(connector.source)
+
+    last_synced_by_platform = await backend.get_platforms_last_synced_at(
+        [connector.source for connector in connectors]
+    )
+
+    items: list[dict[str, object]] = []
+    for connector in connectors:
+        uses_auth = connector_uses_auth(connector)
+        provider = auth_provider_key(connector) if uses_auth else None
+        provider_item = provider_by_key[str(provider)] if provider is not None else None
+        interval = connector.poll_interval
+        polls = interval is not None
+        polled_by = sorted(poll_delegators.get(connector.source, []))
+        poll_delegates = list(type(connector).poll_delegates)
+        last_synced_at = last_synced_by_platform.get(connector.source)
+        items.append({
+            "source": connector.source,
+            "description": type(connector).auth_description,
+            "auth_provider": provider,
+            "shared_auth": bool(provider_item["shared"]) if provider_item is not None else False,
+            "auth_status": provider_item["auth_status"] if provider_item is not None else None,
+            "auth_detail": provider_item["auth_detail"] if provider_item is not None else None,
+            "auth_verified": provider_item["auth_verified"] if provider_item is not None else False,
+            "account_count": len(cast(list[dict[str, object]], provider_item["accounts"]))
+            if provider_item is not None
+            else 0,
+            "url_patterns": type(connector).url_patterns,
+            "polls": polls,
+            "poll_interval_seconds": int(interval.total_seconds()) if interval is not None else None,
+            "poll_delegates": poll_delegates,
+            "polled_by": polled_by,
+            "sync": _sync_label(polls, interval, polled_by, poll_delegates),
+            "last_synced_at": last_synced_at.isoformat() if last_synced_at is not None else None,
+            "last_sync": _last_sync_label(last_synced_at),
+        })
+    return items
+
+
+def _sync_label(
+    polls: bool,
+    interval: timedelta | None,
+    polled_by: list[str],
+    poll_delegates: list[str],
+) -> str:
+    if polls:
+        assert interval is not None
+        label = f"polling every {_format_interval(int(interval.total_seconds()))}"
+        if poll_delegates:
+            label = f"{label} for {', '.join(poll_delegates)}"
+        return label
+    if polled_by:
+        return f"via {', '.join(polled_by)} poll"
+    return "on-demand"
+
+
+def _last_sync_label(last_synced_at: datetime | None) -> str:
+    if last_synced_at is None:
+        return "never"
+    return last_synced_at.astimezone(UTC).strftime("%Y-%m-%d %H:%M:%SZ")
+
+
+def _format_interval(seconds: int) -> str:
+    if seconds % 3600 == 0:
+        hours = seconds // 3600
+        return f"{hours}h"
+    if seconds % 60 == 0:
+        minutes = seconds // 60
+        return f"{minutes}m"
+    return f"{seconds}s"

agentgraph/core/context.py

@@ -0,0 +1,26 @@
+"""Module-level StorageBackend singleton."""
+
+from __future__ import annotations
+
+from agentgraph.core.storage import StorageBackend
+
+_backend: StorageBackend | None = None
+
+
+def set_backend(backend: StorageBackend) -> None:
+    global _backend
+    _backend = backend
+
+
+def clear_backend() -> None:
+    global _backend
+    _backend = None
+
+
+def get_backend() -> StorageBackend:
+    if _backend is None:
+        raise RuntimeError(
+            "No storage backend initialized. "
+            "Call set_backend() before using the graph layer."
+        )
+    return _backend

agentgraph/core/runtime.py

@@ -0,0 +1,36 @@
+"""Runtime helpers for constructing configured backends."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from agentgraph.core.storage import StorageBackend
+
+
+def create_backend() -> StorageBackend:
+    """Create the configured storage backend without initialising it."""
+    from agentgraph.backends import get_backend_class
+    from agentgraph.config import get_settings
+
+    settings = get_settings()
+    backend_class: Any = get_backend_class(settings.backend)
+    if settings.backend == "sqlite":
+        return backend_class(settings.backend_sqlite_path, settings.backend_sqlite_vector_mode)
+    return backend_class(settings)
+
+
+@asynccontextmanager
+async def backend_context() -> AsyncGenerator[StorageBackend, None]:
+    """Initialise the configured backend, set graph context, and close it."""
+    from agentgraph.core.context import clear_backend, set_backend
+
+    backend = create_backend()
+    await backend.initialize()
+    set_backend(backend)
+    try:
+        yield backend
+    finally:
+        await backend.close()
+        clear_backend()

agentgraph/core/storage.py

@@ -0,0 +1,240 @@
+"""StorageBackend ABC — the persistence-agnostic interface for AgentGraph."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from agentgraph.connectors.base import EntityBatch
+
+EntityResult = dict[str, Any]
+EdgeResult = dict[str, Any]
+
+
+class StorageBackend(ABC):
+    """Persistence-agnostic interface for the AgentGraph knowledge store.
+
+    All methods are async. The backend is responsible for all SQL/storage
+    operations; the graph layer computes embeddings and passes them in.
+    """
+
+    # --- Lifecycle ---
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Apply schema, run migrations, open connection pool."""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release all connections and resources."""
+        ...
+
+    # --- Write ---
+
+    @abstractmethod
+    async def upsert_batch(
+        self,
+        batch: EntityBatch,
+        person_embeddings: dict[str, list[float] | None],
+        entity_embeddings: dict[str, list[float] | None],
+    ) -> None:
+        """Atomically persist an EntityBatch.
+
+        person_embeddings: canonical_key (email or "platform:user_id") → vector
+        entity_embeddings: platform_entity_id → vector
+        """
+        ...
+
+    @abstractmethod
+    async def merge_person_entities(
+        self,
+        primary_entity_id: str,
+        duplicate_entity_ids: list[str],
+    ) -> EntityResult:
+        """Merge duplicate Person entities into primary_entity_id.
+
+        Backends must move all edges from duplicate persons to the primary person,
+        merge non-conflicting metadata onto the primary, delete the duplicates,
+        and return the updated primary entity.
+        """
+        ...
+
+    @abstractmethod
+    async def set_entity_bookmarked(
+        self,
+        entity_id: str,
+        bookmarked: bool,
+    ) -> EntityResult:
+        """Set or clear GC protection for an entity and return the updated entity."""
+        ...
+
+    @abstractmethod
+    async def delete_entity(self, entity_id: str) -> EntityResult:
+        """Delete an entity and return the deleted entity."""
+        ...
+
+    # --- Read: entities ---
+
+    @abstractmethod
+    async def search_entities(
+        self,
+        query_vec: list[float],
+        query_text: str,
+        entity_types: list[str] | None,
+        limit: int,
+        min_score: float,
+        platform: str | None = None,
+    ) -> list[EntityResult]: ...
+
+    @abstractmethod
+    async def get_entity_by_id(self, entity_id: str) -> EntityResult | None: ...
+
+    @abstractmethod
+    async def get_entities_by_ids(self, entity_ids: list[str]) -> list[EntityResult]: ...
+
+    @abstractmethod
+    async def get_entities_by_id_prefix(self, prefix: str) -> list[EntityResult]: ...
+
+    @abstractmethod
+    async def get_entity_by_platform(
+        self, platform: str, platform_entity_id: str
+    ) -> EntityResult | None: ...
+
+    @abstractmethod
+    async def list_entities(
+        self,
+        entity_types: list[str] | None,
+        platform: str | None,
+        since: datetime | None,
+        limit: int,
+    ) -> list[EntityResult]: ...
+
+    @abstractmethod
+    async def list_entities_page(
+        self,
+        entity_types: list[str] | None,
+        platform: str | None,
+        since: datetime | None,
+        limit: int,
+        offset: int,
+        order_by: str | None,
+        order_dir: str,
+    ) -> tuple[list[EntityResult], int]:
+        """Return an entity page and total count, optionally ordered by a supported field."""
+        ...
+
+    @abstractmethod
+    async def query_by_filter(
+        self,
+        entity_type: str,
+        filters: dict[str, str],
+        limit: int,
+        order_by: str,
+        since: datetime | None,
+        authored_by: list[str] | None,
+        has_attachments: bool = False,
+    ) -> list[EntityResult]: ...
+
+    # --- Read: edges ---
+
+    @abstractmethod
+    async def get_edges(
+        self,
+        entity_id: str,
+        edge_type: str | None,
+        direction: str,
+    ) -> list[EdgeResult]: ...
+
+    @abstractmethod
+    async def get_edges_for_entities(self, entity_ids: list[str]) -> list[EdgeResult]: ...
+
+    @abstractmethod
+    async def traverse_graph(
+        self, entity_id: str, max_depth: int
+    ) -> dict[str, Any]: ...
+
+    # --- Linking ---
+
+    @abstractmethod
+    async def find_entity_id(
+        self, platform: str, platform_entity_id: str
+    ) -> str | None: ...
+
+    @abstractmethod
+    async def upsert_stub_entity(
+        self,
+        entity_type: str,
+        platform: str,
+        platform_entity_id: str,
+    ) -> str:
+        """Insert a stub entity with synced_at=NULL. Returns internal UUID string."""
+        ...
+
+    @abstractmethod
+    async def insert_references_edge(self, source_id: str, target_id: str) -> None: ...
+
+    # --- GC ---
+
+    @abstractmethod
+    async def gc_entities(self, retention_days: int) -> int: ...
+
+    # --- Sync state ---
+
+    @abstractmethod
+    async def load_cursor(self, source: str) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def save_cursor(self, source: str, cursor: dict[str, Any]) -> None: ...
+
+    # --- Connector support ---
+
+    @abstractmethod
+    async def increment_dwell_time(
+        self, platform: str, platform_entity_id: str, dwell_ms: int
+    ) -> None:
+        """Increment cumulative dwell time for an entity."""
+        ...
+
+    @abstractmethod
+    async def get_last_synced_at(
+        self, platform: str, platform_entity_id: str
+    ) -> datetime | None: ...
+
+    @abstractmethod
+    async def get_platform_last_synced_at(self, platform: str) -> datetime | None: ...
+
+    async def get_platforms_last_synced_at(
+        self,
+        platforms: list[str],
+    ) -> dict[str, datetime | None]:
+        return {
+            platform: await self.get_platform_last_synced_at(platform)
+            for platform in platforms
+        }
+
+    @abstractmethod
+    async def reset_synced_at(
+        self, platform: str, platform_entity_id: str
+    ) -> None: ...
+
+    @abstractmethod
+    async def touch_last_accessed(
+        self, platform: str, platform_entity_id: str
+    ) -> None: ...
+
+    @abstractmethod
+    async def touch_last_accessed_by_ids(self, entity_ids: list[str]) -> None: ...
+
+    @abstractmethod
+    async def get_entity_type(
+        self, platform: str, platform_entity_id: str
+    ) -> str | None: ...
+
+    @abstractmethod
+    async def get_entity_platform_ref(
+        self, entity_id: str
+    ) -> tuple[str, str] | None:
+        """Return (platform, platform_entity_id) for an internal UUID, or None."""
+        ...

agentgraph/graph/__init__.py

@@ -0,0 +1 @@
+"""Knowledge graph operations: upsert, identity resolution, GC."""

agentgraph/graph/bookmark.py

@@ -0,0 +1,87 @@
+"""Bookmark graph entities to protect them from garbage collection."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from agentgraph.core.context import get_backend
+from agentgraph.core.storage import EntityResult
+from agentgraph.graph.query import get_entity
+
+
+async def bookmark_entity(entity_id: str) -> EntityResult:
+    """Mark an entity as bookmarked by UUID, UUID prefix, or platform ref."""
+    return await set_entity_bookmark(entity_id, True)
+
+
+async def set_entity_bookmark(entity_id: str, bookmarked: bool) -> EntityResult:
+    """Set bookmark state by UUID, UUID prefix, or platform ref."""
+    entity = await get_entity(entity_id)
+    if entity is None:
+        raise ValueError(f"Entity {entity_id!r} not found")
+    return await get_backend().set_entity_bookmarked(entity["id"], bookmarked)
+
+
+async def bookmark_target(target: str) -> EntityResult:
+    """Bookmark an entity target or fetch and bookmark an http(s) URL."""
+    if _is_http_url(target):
+        return await bookmark_url(target)
+    return await bookmark_entity(target)
+
+
+async def bookmark_url(url: str) -> EntityResult:
+    """Fetch a URL through its owning connector or the web fallback, then bookmark it."""
+    from agentgraph.connectors.registry import bootstrap, get_connector
+    from agentgraph.graph.upsert import upsert_batch
+    from agentgraph.server.router import classify_url
+
+    bootstrap()
+    ref = classify_url(url)
+    connector = get_connector(ref.source) if ref is not None else get_connector("web")
+    if connector is None:
+        raise ValueError("No connector available to fetch this URL")
+
+    resource_type = ref.resource_type if ref is not None else "document"
+    resource_id = ref.resource_id if ref is not None else url
+    batch = await connector.fetch(resource_type, resource_id)
+
+    backend = get_backend()
+    if ref is not None:
+        entity = await backend.get_entity_by_platform(ref.source, ref.resource_id)
+    else:
+        entity = None
+
+    if entity is None:
+        entity = await _find_batch_entity(batch)
+
+    if entity is None and batch.entities:
+        await upsert_batch(batch)
+        if ref is not None:
+            entity = await backend.get_entity_by_platform(ref.source, ref.resource_id)
+        else:
+            entity = await _find_batch_entity(batch)
+
+    if entity is None:
+        raise ValueError(f"URL {url!r} was fetched but no graph entity was created")
+    return await backend.set_entity_bookmarked(entity["id"], True)
+
+
+async def _find_batch_entity(batch: object) -> EntityResult | None:
+    from agentgraph.connectors.base import EntityBatch
+
+    if not isinstance(batch, EntityBatch):
+        return None
+    backend = get_backend()
+    for candidate in batch.entities:
+        entity = await backend.get_entity_by_platform(
+            candidate.platform,
+            candidate.platform_entity_id,
+        )
+        if entity is not None:
+            return entity
+    return None
+
+
+def _is_http_url(target: str) -> bool:
+    parsed = urlparse(target)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)

agentgraph/graph/delete.py

@@ -0,0 +1,17 @@
+"""Delete graph entities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentgraph.core.context import get_backend
+from agentgraph.graph.query import get_entity
+
+
+async def delete_entity(target: str) -> dict[str, Any]:
+    """Delete an entity by UUID, UUID prefix, platform ref, or URL."""
+    entity = await get_entity(target)
+    if entity is None:
+        raise ValueError(f"Entity {target!r} not found")
+    deleted = await get_backend().delete_entity(entity["id"])
+    return {"deleted": True, "entity": deleted}

agentgraph/graph/download.py

@@ -0,0 +1,35 @@
+"""Authenticated source-file downloads for graph entities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentgraph.graph.query import get_entity
+
+
+async def download_entity(entity_ref: str, output_path: str | None = None) -> dict[str, Any]:
+    """Download an entity's source file using its connector's stored auth."""
+    from agentgraph.connectors.registry import bootstrap, get_connector
+
+    entity = await get_entity(entity_ref)
+    if entity is None:
+        raise ValueError(f"Entity not found: {entity_ref}")
+
+    platform = str(entity["platform"])
+    platform_entity_id = str(entity["platform_entity_id"])
+    entity_type = str(entity["entity_type"])
+
+    bootstrap()
+    connector = get_connector(platform)
+    if connector is None:
+        raise ValueError(f"No connector registered for platform '{platform}'")
+
+    resource_id, resource_type = connector.normalise_fetch_id(platform_entity_id, entity_type)
+    try:
+        return await connector.download(
+            resource_type=resource_type,
+            resource_id=resource_id,
+            output_path=output_path,
+        )
+    except NotImplementedError as exc:
+        raise ValueError(str(exc)) from exc