agentgraph-server 0.7.2__tar.gz → 0.8.0__tar.gz

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/.agents/skills/agentgraph/SKILL.md

@@ -13,10 +13,6 @@ Prefer the `agentgraph` CLI when a shell is available. Use the equivalent MCP to
 when AgentGraph is connected directly to the agent. Do not query AgentGraph's SQLite
 database or connector internals directly.
 
-Use `agentgraph demo add` or `add_demo_tool` to add the fictional Atlas fixtures to
-the configured graph. Remove them afterward with `agentgraph demo remove` or
-`remove_demo_tool`.
-
 ## Commands that use the local server
 
 `agentgraph poll` and connector or authentication commands that queue a poll or
@@ -24,6 +20,10 @@ historical ingest always call the local AgentGraph server. Reads (`search`, `get
 `edges`, `traverse`) and `fetch`/`download` use it when it is reachable and
 otherwise read the database directly, so they work with no server running.
 
+Run ordinary commands without setting `AGENTGRAPH_QUERY_TRANSPORT`, even when the
+server is stopped. The default `auto` transport tries the Unix
+socket, then TCP, then falls back to in-process automatically.
+
 Many agent sandboxes deny loopback TCP but allow an allowlisted Unix socket, so the
 server listens on both and clients prefer the socket. If a command fails because the
 sandbox blocked it:
@@ -31,9 +31,12 @@ sandbox blocked it:
 - For `poll`, ingest, or auth commands there is no fallback — request permission to
   contact the local server, or ask the user to allowlist the socket
   (`~/.agentgraph/agentgraph.sock`), then retry.
-- For reads, `AGENTGRAPH_QUERY_TRANSPORT=in-process` bypasses the server entirely.
-- `AGENTGRAPH_QUERY_TRANSPORT=server agentgraph search x --limit 1` reports plainly
-  whether the server is reachable, instead of silently falling back.
+- For reads, retry with `AGENTGRAPH_QUERY_TRANSPORT=in-process` only after an actual
+  sandbox connection failure. This bypasses server probes for that retry.
+
+To diagnose server connectivity explicitly, use
+`AGENTGRAPH_QUERY_TRANSPORT=server agentgraph search x --limit 1`; it reports whether
+the server is reachable instead of silently falling back.
 
 See the Coding agent sandboxes section of the configuration docs for the per-agent
 allowlist settings.
@@ -55,12 +58,25 @@ allowlist settings.
 Start with search unless the user already supplied a graph ID, platform reference, or
 known indexed URL. `search` covers both jobs: pass a query string for ranked
 discovery, and add or use only its filters (`--type`, `--platform`, `--filter`,
-`--since`, `--mine`, `--has-attachments`) when the entity type or constraints are
-already known. Omitting the query string turns it into a deterministic listing
-ordered by date.
+`--since`, `--observed-since`, `--mine`, `--has-attachments`) when the entity type or
+constraints are already known. Omitting the query string turns it into a
+deterministic listing ordered by date.
+
+Use `--observed-since 2d` (MCP: `observed_since="2d"`) for entities observed in
+the browser within the last two days. It accepts the same relative durations and
+ISO timestamps as `--since`, which filters `updated_at`. Both cutoffs are inclusive;
+when combined, both must match. Never-observed entities are excluded by
+`--observed-since`. Add `--order-by observed_at` to sort by observation time.
 
 ## Context lifecycle
 
+`agentgraph list-connectors --json` (MCP: `list_connectors_tool`) reports each
+connector's declared resource `entity_types`, including standard graph types,
+with their names, resource types, and source-specific descriptions. Person
+identities are handled separately. An empty list means the connector has not
+declared resource types; it does not mean the source has no indexed entities.
+The CLI table displays `-` for this empty list.
+
 - **Connect** is setup: installed connectors and their authentication/configuration
   determine which selected sources AgentGraph can access.
 - **Observe** records human attention to a supported browser URL and triggers a

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/.agents/skills/agentgraph/references/commands.md

@@ -3,7 +3,7 @@
 ## CLI
 
 ```bash
-agentgraph search ["<query>"] [--type <type>] [--platform <platform>] [--filter key=value] [--since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|source_created_at|source_updated_at|observed_at|synced_at] [--min-score N] [--json]
+agentgraph search [--type <type>] [--platform <platform>] [--filter key=value] [--since 12h|30m|2d] [--observed-since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|source_created_at|source_updated_at|observed_at|synced_at] [--min-score N] [--json]
 agentgraph get <entity-id|platform/ref|url> [--resolve] [--json]
 agentgraph edges <entity-id|platform/ref> [--type <edge-type>] [--direction in|out|both] [--json]
 agentgraph traverse <entity-id|platform/ref> [--resolve] [--depth 0..4] [--json]
@@ -14,6 +14,11 @@ filter is applied as a hard constraint (`--limit` defaults to 10). Without one t
 is no ranking: the filters select the entities, `--order-by` sorts them newest first,
 `--min-score` is ignored, and `--limit` defaults to 50.
 
+`--since` filters `updated_at`; `--observed-since` filters browser observation time
+(`observed_at`), excluding never-observed entities. Both accept ISO timestamps or
+relative durations and include the cutoff itself. When supplied together, both
+must match. Neither flag changes ordering.
+
 `get` and `traverse` do not resolve stubs unless `--resolve` is supplied. Depth 0
 returns only the starting entity; depths 1 through 4 include that many relationship
 hops.
@@ -28,7 +33,7 @@ accept full UUIDs, unambiguous UUID prefixes, and platform references.
 ## MCP equivalents
 
 ```text
-agentgraph search ...    -> search_entities_tool(query, entity_types, platform, filters, since, authored_by_me, has_attachments, limit, order_by, min_score, refresh)
+agentgraph search ...    -> search_entities_tool(query, entity_types, platform, filters, since, authored_by_me, has_attachments, limit, order_by, min_score, refresh, observed_since)
 agentgraph get ...       -> get_entity_tool(entity_id, resolve)
 agentgraph edges ...     -> get_edges_tool(entity_id, edge_type, direction)
 agentgraph traverse ...  -> traverse_graph_tool(entity_id, max_depth, resolve)

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/.agents/skills/agentgraph/references/data-model.md

@@ -14,7 +14,12 @@
 | `Task` | Tracked work items such as Jira issues. Issue key, status, and assignee live in `metadata`. |
 | `Video` | Recorded videos such as Looms. The transcript is indexed as content and `metadata.web_url` links to the video. |
 
-The valid core model does not currently include `Project`.
+Installed connectors may add shared entity type names such as `Project`. The complete
+alphabetical catalog, including connector descriptions, is embedded in the
+`search_entities_tool` MCP description. With the CLI, connector-specific declarations
+are available from `agentgraph list-connectors --json`. Undeclared type strings remain
+storable and searchable for compatibility, but do not receive automatic discovery or
+reference routing.
 
 ## Relationships
 

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/.agents/skills/agentgraph/references/operations.md

@@ -10,8 +10,10 @@ agentgraph auth remove <provider> [--account <account-id>] [--json]
 ```
 
 Use `agentgraph list-connectors --json` to discover installed connector source names,
-valid platform values, URL ownership, polling delegation, and sync state. Do not rely
-on a hardcoded platform list. Use `--verify` only when a live provider check is
+valid platform values, connector-declared entity types, URL ownership, polling
+delegation, and sync state. Do not rely on a hardcoded platform list. MCP clients
+receive the full installed entity type catalog in the `search_entities_tool`
+description during tool discovery. Use `--verify` only when a live provider check is
 needed.
 
 MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,

{agentgraph_server-0.7.2/agentgraph_server.egg-info → agentgraph_server-0.8.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.7.2
+Version: 0.8.0
 Summary: A local-first CLI and MCP server that turns selected digital sources into a searchable graph for the AI agent you already use.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiosqlite>=0.20.0
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5
+Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0
 Requires-Dist: apscheduler>=3.11.2
 Requires-Dist: click<8.4
 Requires-Dist: fastapi>=0.135.2
@@ -22,21 +22,21 @@ Requires-Dist: sqlite-vec>=0.1.9
 Requires-Dist: typer>=0.24.1
 Requires-Dist: uvicorn>=0.42.0
 Provides-Extra: google
-Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.0; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.0; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.0; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.6.0; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "all"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0; extra == "all"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.0; extra == "all"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.0; extra == "all"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.0; extra == "all"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.6.0; extra == "all"
 Dynamic: license-file
 
 # AgentGraph

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/agentgraph/backends/sqlite/backend.py

@@ -116,6 +116,7 @@ def _entity_predicates(
     since: datetime | None = None,
     authored_by: list[str] | None = None,
     has_attachments: bool = False,
+    observed_since: datetime | None = None,
 ) -> tuple[str, list[Any], str, list[Any]]:
     """Build the entity-selection predicates shared by every leg of a search.
 
@@ -143,6 +144,9 @@ def _entity_predicates(
     if since:
         clauses.append("e.updated_at >= ?")
         params.append(_utc_stamp(since))
+    if observed_since:
+        clauses.append("e.observed_at >= ?")
+        params.append(_utc_stamp(observed_since))
     if has_attachments:
         clauses.append(
             "json_extract(e.metadata, '$.attachments') IS NOT NULL"
@@ -1269,6 +1273,7 @@ class SQLiteBackend(StorageBackend):
         has_attachments: bool = False,
         order_by: str | None = None,
         content_limit: int | None = None,
+        observed_since: datetime | None = None,
     ) -> list[EntityResult]:
         """Select entities by predicate, ranked by relevance or ordered by date.
 
@@ -1286,6 +1291,7 @@ class SQLiteBackend(StorageBackend):
             since,
             authored_by,
             has_attachments,
+            observed_since=observed_since,
         )
 
         if query_text is None or query_vec is None:

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/agentgraph/cli.py

@@ -484,7 +484,7 @@ def list_connectors(
         False, "--verify", help="Live-check connector credentials with provider APIs"
     ),
 ) -> None:
-    """List installed connectors and their sync status."""
+    """List installed connectors, their resource entity types, and sync status."""
     from agentgraph.connectors.registry import bootstrap, get_all_connectors
     from agentgraph.connectors.status import connector_status_items
     from agentgraph.core.runtime import backend_context
@@ -505,6 +505,7 @@ def list_connectors(
     table = Table(title="Connectors", show_lines=True)
     table.add_column("Connector", style="bold", no_wrap=True)
     table.add_column("Description", ratio=1)
+    table.add_column("Types")
     table.add_column("Auth")
     table.add_column("Sync")
     table.add_column("Last sync", no_wrap=True)
@@ -513,6 +514,11 @@ def list_connectors(
         table.add_row(
             str(item["source"]),
             str(desc),
+            ", ".join(
+                str(definition["name"])
+                for definition in cast(list[dict[str, object]], item["entity_types"])
+            )
+            or "-",
             _connector_auth_label(item),
             str(item["sync"]),
             str(item["last_sync"]),
@@ -591,7 +597,7 @@ def search(
         None,
         "--since",
         "-s",
-        help="Only results after this time: ISO timestamp or relative (12h, 30m, 2d)",
+        help="Only results updated at or after this time: ISO timestamp or relative (12h, 30m, 2d)",
     ),
     mine: bool = typer.Option(False, "--mine", "-m", help="Only entities authored by me"),
     has_attachments: bool = typer.Option(
@@ -613,6 +619,11 @@ def search(
         0.03, "--min-score", help="Minimum relevance score (0–1); ignored without a query"
     ),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    observed_since: str | None = typer.Option(
+        None,
+        "--observed-since",
+        help="Only results observed at or after this time: ISO timestamp or relative (12h, 30m, 2d)",
+    ),
 ) -> None:
     """Search the knowledge graph, or list entities matching filters alone."""
     from agentgraph.cli_query import cmd_search
@@ -623,6 +634,7 @@ def search(
         platform=platform,
         filters=dict(f.split("=", 1) for f in filter if "=" in f),
         since=since,
+        observed_since=observed_since,
         authored_by_me=mine,
         has_attachments=has_attachments,
         limit=limit,
@@ -874,7 +886,13 @@ def install_skill(
 
     typer.echo(f"Installed AgentGraph skill '{result.skill}' to {result.destination}")
     if result.claude_destination is not None:
-        typer.echo(f"Linked Claude skill to {result.claude_destination}")
+        if result.claude_linked:
+            typer.echo(f"Linked Claude skill to {result.claude_destination}")
+        else:
+            typer.echo(
+                f"Claude reads {result.claude_destination} already; "
+                "its skill directory is the same one."
+            )
 
 
 @app.command()

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/agentgraph/cli_query.py

@@ -109,6 +109,7 @@ def cmd_search(
     authored_by_me: bool = False,
     has_attachments: bool = False,
     order_by: str | None = None,
+    observed_since: str | None = None,
 ) -> None:
     # An empty or whitespace-only argument is an absent query, not a query for
     # nothing: this keeps the limit default, the renderer, and the backend's
@@ -127,6 +128,7 @@ def cmd_search(
             platform,
             filters=filters,
             since=since,
+            observed_since=observed_since,
             authored_by_me=authored_by_me,
             has_attachments=has_attachments,
             order_by=order_by,

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/agentgraph/connectors/base.py

@@ -11,24 +11,13 @@ from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from typing import Any, ClassVar, Literal
 
-from pydantic import BaseModel, Field
-
-# All resource_type values understood by the connector layer.
-# Each value maps to a distinct fetch strategy within a connector.
-ResourceType = Literal[
-    "channel",
-    "dm",
-    "document",
-    "folder",
-    "message",
-    "spreadsheet",
-    "thread",
-    "video",
-    "work-item",
-]
+from pydantic import BaseModel, ConfigDict, Field
+
+# Resource types name connector-local fetch strategies. Connectors may extend them.
+type ResourceType = str
 RetentionPolicy = Literal["observed", "owned", "connected", "persistent"]
 
-# All valid entity_type values stored in the DB.
+# Built-in entity type vocabulary. Storage also accepts connector-defined names.
 ENTITY_TYPES: tuple[str, ...] = (
     "Channel",
     "Document",
@@ -41,6 +30,18 @@ ENTITY_TYPES: tuple[str, ...] = (
     "Video",
 )
 
+ENTITY_TYPE_DESCRIPTIONS: dict[str, str] = {
+    "Channel": "Chat channels and direct-message threads.",
+    "Document": "Text documents, web pages, files, and attachment stubs.",
+    "Email": "Email threads.",
+    "Folder": "Containers such as Drive folders and RSS feeds.",
+    "Message": "Chat messages, including chat uploads stored in metadata.",
+    "Person": "Source identities and confirmed cross-source identity merges.",
+    "Spreadsheet": "Spreadsheets and tabular workbook resources.",
+    "Task": "Tracked work items such as issues and tasks.",
+    "Video": "Recorded videos whose searchable content may include a transcript.",
+}
+
 # Broad URL extractor — classify_url does fine-grained matching
 _URL_RE = re.compile(r"https?://\S+")
 
@@ -57,6 +58,27 @@ RESOURCE_TYPE_TO_ENTITY_TYPE: dict[str, str] = {
     "work-item": "Task",
 }
 
+_ENTITY_TYPE_TO_RESOURCE_TYPE: dict[str, ResourceType] = {
+    "Channel": "channel",
+    "Document": "document",
+    "Email": "thread",
+    "Folder": "folder",
+    "Message": "message",
+    "Spreadsheet": "spreadsheet",
+    "Task": "work-item",
+    "Video": "video",
+}
+
+
+class EntityTypeDefinition(BaseModel):
+    """A connector-local fetch resource mapped to a shared graph entity type."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(pattern=r"^[A-Z][A-Za-z0-9]*$")
+    resource_type: str = Field(pattern=r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$")
+    description: str = Field(min_length=1)
+
 
 @dataclass(frozen=True)
 class SourceReference:
@@ -147,6 +169,7 @@ class EntityBatch(BaseModel):
         """
         if not entity.content:
             return
+        from agentgraph.connectors.registry import entity_type_for_reference
         from agentgraph.server.router import classify_url
 
         seen: set[str] = set()
@@ -163,7 +186,7 @@ class EntityBatch(BaseModel):
             seen.add(key)
             self.entities.append(
                 EntityRecord(
-                    entity_type=RESOURCE_TYPE_TO_ENTITY_TYPE[ref.resource_type],
+                    entity_type=entity_type_for_reference(ref),
                     platform=ref.source,
                     platform_entity_id=ref.resource_id,
                     is_stub=True,
@@ -260,6 +283,13 @@ class ResourceUnavailableError(RuntimeError):
 class BaseConnector(ABC):
     source: ClassVar[str]  # platform name, e.g. "slack" — must be set by subclass
     fetch_policy: ClassVar[FetchPolicy]  # staleness policy — must be set by subclass
+    entity_types: ClassVar[tuple[EntityTypeDefinition, ...]] = ()
+    """Resource entity types exposed by this connector, including core vocabulary.
+
+    Used for capability discovery and to extend or override core resource mappings.
+    Person identities are emitted separately through EntityBatch.persons.
+    """
+
     is_generic_url_fallback: ClassVar[bool] = False
     """True for broad fallback connectors that should not claim URLs during discovery."""
 
@@ -387,21 +417,33 @@ class BaseConnector(ABC):
     def normalise_fetch_id(self, resource_id: str, entity_type: str) -> tuple[str, ResourceType]:
         """Map a stored resource_id + entity_type to the (id, resource_type) that fetch() expects.
 
-        The default maps entity_type to ResourceType using the standard table and
-        returns resource_id unchanged. Connectors override this when their stored IDs
-        differ from their fetchable IDs (e.g. Discord message IDs encode the channel).
+        The default prefers connector-declared mappings, falls back to the core
+        vocabulary, and returns resource_id unchanged. Connectors override this when
+        their stored IDs differ from their fetchable IDs (e.g. Discord message IDs
+        encode the channel).
         """
-        resource_type_map: dict[str, ResourceType] = {
-            "Document": "document",
-            "Folder": "folder",
-            "Spreadsheet": "spreadsheet",
-            "Channel": "channel",
-            "Message": "message",
-            "Email": "thread",
-            "Task": "work-item",
-            "Video": "video",
-        }
-        return resource_id, resource_type_map.get(entity_type, "document")  # type: ignore[return-value]
+        return resource_id, type(self).resource_type_for_entity_type(entity_type)
+
+    @classmethod
+    def entity_type_for_resource_type(cls, resource_type: ResourceType) -> str:
+        """Map this connector's fetch resource type to a stored entity type."""
+        for definition in cls.entity_types:
+            if definition.resource_type == resource_type:
+                return definition.name
+        try:
+            return RESOURCE_TYPE_TO_ENTITY_TYPE[resource_type]
+        except KeyError as exc:
+            raise ValueError(
+                f"Connector {cls.source!r} does not declare resource type {resource_type!r}"
+            ) from exc
+
+    @classmethod
+    def resource_type_for_entity_type(cls, entity_type: str) -> ResourceType:
+        """Map a stored entity type to this connector's canonical fetch resource type."""
+        for definition in cls.entity_types:
+            if definition.name == entity_type:
+                return definition.resource_type
+        return _ENTITY_TYPE_TO_RESOURCE_TYPE.get(entity_type, "document")
 
     @classmethod
     def current_user_id(cls) -> str | None:

{agentgraph_server-0.7.2 → agentgraph_server-0.8.0}/agentgraph/connectors/feed.py

@@ -13,11 +13,7 @@ from uuid import UUID, uuid4
 
 from pydantic import BaseModel, Field
 
-from agentgraph.connectors.base import (
-    RESOURCE_TYPE_TO_ENTITY_TYPE,
-    BaseConnector,
-    ResourceType,
-)
+from agentgraph.connectors.base import BaseConnector, ResourceType
 
 logger = logging.getLogger(__name__)
 
@@ -201,11 +197,19 @@ def mutation_target_from_reference(
     url: str,
 ) -> MutationTarget:
     """Build a target from a connector-owned source reference."""
+    from agentgraph.connectors.base import SourceReference
+    from agentgraph.connectors.registry import entity_type_for_reference
 
     return MutationTarget(
         platform=platform,
         platform_entity_id=platform_entity_id,
-        entity_type=RESOURCE_TYPE_TO_ENTITY_TYPE[resource_type],
+        entity_type=entity_type_for_reference(
+            SourceReference(
+                source=platform,
+                resource_type=resource_type,
+                resource_id=platform_entity_id,
+            )
+        ),
         resource_type=resource_type,
         url=url,
     )

agentgraph_server-0.8.0/agentgraph/connectors/registry.py

@@ -0,0 +1,175 @@
+"""Connector registry: maps source names to connector instances.
+
+Built-in connectors are discovered via Python entry points
+(``agentgraph.connectors`` group). Third-party connectors can be installed
+as separate packages that declare the same entry point group.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from collections.abc import Iterable, Sequence
+from typing import cast
+
+from agentgraph.connectors.base import (
+    ENTITY_TYPE_DESCRIPTIONS,
+    ENTITY_TYPES,
+    RESOURCE_TYPE_TO_ENTITY_TYPE,
+    BaseConnector,
+    EntityTypeDefinition,
+    SourceReference,
+)
+
+logger = logging.getLogger(__name__)
+
+_registry: dict[str, BaseConnector] = {}
+_entry_points: dict[str, importlib.metadata.EntryPoint] = {}
+_load_errors: dict[str, str] = {}
+_bootstrapped = False
+
+
+def register(connector: BaseConnector) -> None:
+    _validate_entity_types(connector)
+    _registry[connector.source] = connector
+
+
+def _validate_entity_types(connector: BaseConnector) -> None:
+    raw_definitions: object = getattr(type(connector), "entity_types", None)
+    if not isinstance(raw_definitions, tuple):
+        raise TypeError(f"Connector {connector.source!r} entity_types must be a tuple")
+    definitions = cast(tuple[object, ...], raw_definitions)
+
+    names: set[str] = set()
+    resource_types: set[str] = set()
+    for definition in definitions:
+        if not isinstance(definition, EntityTypeDefinition):
+            raise TypeError(
+                f"Connector {connector.source!r} entity_types must contain "
+                "EntityTypeDefinition values"
+            )
+        if definition.name in names:
+            raise ValueError(
+                f"Connector {connector.source!r} declares entity type "
+                f"{definition.name!r} more than once"
+            )
+        if definition.resource_type in resource_types:
+            raise ValueError(
+                f"Connector {connector.source!r} declares resource type "
+                f"{definition.resource_type!r} more than once"
+            )
+        names.add(definition.name)
+        resource_types.add(definition.resource_type)
+
+
+def get_entity_type_names(connectors: Sequence[BaseConnector] | None = None) -> list[str]:
+    """Return the sorted union of core and installed connector entity type names."""
+    resolved = list(connectors) if connectors is not None else get_all_connectors()
+    names = set(ENTITY_TYPES)
+    for connector in resolved:
+        names.update(definition.name for definition in _entity_type_definitions(connector))
+    return sorted(names)
+
+
+def get_entity_type_catalog(
+    connectors: Sequence[BaseConnector] | None = None,
+) -> list[tuple[str, list[tuple[str, str]]]]:
+    """Return entity types with their core or connector-labelled descriptions."""
+    resolved = list(connectors) if connectors is not None else get_all_connectors()
+    descriptions: dict[str, list[tuple[str, str]]] = {
+        name: [("core", ENTITY_TYPE_DESCRIPTIONS[name])] for name in ENTITY_TYPES
+    }
+    for connector in resolved:
+        for definition in _entity_type_definitions(connector):
+            entries = descriptions.setdefault(definition.name, [])
+            detail = (connector.source, definition.description)
+            if detail not in entries:
+                entries.append(detail)
+    catalog: list[tuple[str, list[tuple[str, str]]]] = []
+    for name in sorted(descriptions):
+        entries = descriptions[name]
+        entries.sort(key=lambda item: (item[0] != "core", item[0], item[1]))
+        catalog.append((name, entries))
+    return catalog
+
+
+def _entity_type_definitions(connector: BaseConnector) -> tuple[EntityTypeDefinition, ...]:
+    return cast(
+        tuple[EntityTypeDefinition, ...],
+        getattr(type(connector), "entity_types", ()),
+    )
+
+
+def entity_type_for_reference(reference: SourceReference) -> str:
+    """Resolve a source-scoped resource type to the stored graph entity type."""
+    connector = get_connector(reference.source)
+    if connector is not None:
+        return type(connector).entity_type_for_resource_type(reference.resource_type)
+    try:
+        return RESOURCE_TYPE_TO_ENTITY_TYPE[reference.resource_type]
+    except KeyError as exc:
+        raise ValueError(
+            f"No connector registered for source {reference.source!r} and resource type "
+            f"{reference.resource_type!r} is not a core resource type"
+        ) from exc
+
+
+def get_connector(source: str) -> BaseConnector | None:
+    bootstrap()
+    if source not in _registry and source in _entry_points:
+        _load_entry_point(source, _entry_points[source])
+    return _registry.get(source)
+
+
+def get_connector_load_error(source: str) -> str | None:
+    """Return the recorded entry-point import error for a connector, if any."""
+    return _load_errors.get(source)
+
+
+def registered_sources() -> list[str]:
+    bootstrap()
+    return list(dict.fromkeys([*_registry.keys(), *_entry_points.keys()]))
+
+
+def get_all_connectors() -> list[BaseConnector]:
+    bootstrap()
+    for name, ep in list(_entry_points.items()):
+        if name not in _registry:
+            _load_entry_point(name, ep)
+    return list(_registry.values())
+
+
+def bootstrap() -> None:
+    """Discover connector entry points without importing connector packages."""
+    global _bootstrapped
+    if _bootstrapped:
+        return
+    _bootstrapped = True
+
+    for ep in _connector_entry_points():
+        _entry_points.setdefault(ep.name, ep)
+
+    if not _entry_points and not _registry:
+        logger.warning(
+            "No connectors discovered. Install connector packages (e.g. pip install agentgraph[all]) "
+            "or declare entry points in the 'agentgraph.connectors' group."
+        )
+
+
+def _connector_entry_points() -> Iterable[importlib.metadata.EntryPoint]:
+    return importlib.metadata.entry_points(group="agentgraph.connectors")
+
+
+def _load_entry_point(name: str, ep: importlib.metadata.EntryPoint) -> None:
+    try:
+        connector_class: type[BaseConnector] = ep.load()
+        connector = connector_class()
+        register(connector)
+        _load_errors.pop(name, None)
+        logger.debug("Loaded connector %r from %s", ep.name, ep.value)
+        if connector.source != name:
+            _entry_points.pop(name, None)
+    except Exception as exc:
+        _entry_points.pop(name, None)
+        _load_errors[name] = str(exc)
+        logger.warning("Failed to load connector %r: %s", ep.name, exc)