agentgraph-server 0.5.3__tar.gz → 0.6.0__tar.gz

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/.agents/skills/AgentGraph/SKILL.md

@@ -13,6 +13,10 @@ 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 localhost
 
 `agentgraph poll` and connector or authentication commands that queue a poll or

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.5.3
+Version: 0.6.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

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/agentgraph/backends/sqlite/backend.py

@@ -64,7 +64,7 @@ _LIST_PAGE_ORDER_BY = {
 _COLUMN_FILTERS = {"platform", "platform_entity_id", "entity_type"}
 _FTS_DELETE_CHUNK_SIZE = 500
 _BUSY_TIMEOUT_MS = 5_000
-_SCHEMA_VERSION = 2
+_SCHEMA_VERSION = 3
 
 
 def _now() -> str:
@@ -208,9 +208,9 @@ class SQLiteBackend(StorageBackend):
     async def _run_migrations(self) -> None:
         conn = self._conn_or_raise()
         cursor = await conn.execute("PRAGMA table_info(entities)")
-        entity_columns = {
-            str(row["name"]): bool(row["notnull"]) for row in await cursor.fetchall()
-        }
+        table_info = await cursor.fetchall()
+        entity_columns = {str(row["name"]): bool(row["notnull"]) for row in table_info}
+        entity_defaults = {str(row["name"]): row["dflt_value"] for row in table_info}
         columns = set(entity_columns)
         if "cumulative_dwell_ms" in columns:
             await conn.execute(
@@ -236,6 +236,8 @@ class SQLiteBackend(StorageBackend):
             "last_accessed" in columns
             or not entity_columns.get("created_at", False)
             or not entity_columns.get("updated_at", False)
+            or entity_defaults.get("created_at") is None
+            or entity_defaults.get("updated_at") is None
             or entity_columns.get("observed_at", False)
             or "source_created_at" not in columns
             or "source_updated_at" not in columns
@@ -249,9 +251,7 @@ class SQLiteBackend(StorageBackend):
             "UPDATE observations SET event_type = 'observation_threshold' "
             "WHERE event_type = 'dwell_threshold'"
         )
-        await conn.execute(
-            "UPDATE entities SET entity_type = 'Email' WHERE entity_type = 'Thread'"
-        )
+        await conn.execute("UPDATE entities SET entity_type = 'Email' WHERE entity_type = 'Thread'")
         await conn.execute(
             "CREATE INDEX IF NOT EXISTS idx_entities_bookmarked ON entities(bookmarked)"
         )
@@ -352,10 +352,13 @@ class SQLiteBackend(StorageBackend):
                 "AND cumulative_observation_duration_ms > 0 THEN observed_at ELSE NULL END"
             )
         observed = (
-            "CASE WHEN platform = 'rss' AND entity_type = 'Folder' THEN NULL "
-            f"ELSE {observed} END"
+            f"CASE WHEN platform = 'rss' AND entity_type = 'Folder' THEN NULL ELSE {observed} END"
+        )
+        duration = (
+            "cumulative_observation_duration_ms"
+            if "cumulative_observation_duration_ms" in columns
+            else "0"
         )
-        duration = "cumulative_observation_duration_ms" if "cumulative_observation_duration_ms" in columns else "0"
         bookmarked = "bookmarked" if "bookmarked" in columns else "0"
         await conn.execute("PRAGMA foreign_keys=OFF")
         try:
@@ -371,8 +374,8 @@ class SQLiteBackend(StorageBackend):
                     content TEXT,
                     content_embedding BLOB,
                     metadata TEXT NOT NULL DEFAULT '{}',
-                    created_at TEXT NOT NULL,
-                    updated_at TEXT NOT NULL,
+                    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+                    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
                     source_created_at TEXT,
                     source_updated_at TEXT,
                     synced_at TEXT,
@@ -503,6 +506,7 @@ class SQLiteBackend(StorageBackend):
         for p in persons:
             canonical_key = p.canonical_email or f"{p.platform}:{p.platform_user_id}"
             meta: dict[str, str] = {}
+            meta.update({key: str(value) for key, value in p.metadata.items() if value is not None})
             if p.canonical_email:
                 meta["canonical_email"] = p.canonical_email
             meta[f"{p.platform}_user_id"] = p.platform_user_id
@@ -534,7 +538,9 @@ class SQLiteBackend(StorageBackend):
                 existing_metadata = json.loads(existing_row[3] or "{}") if existing_row else {}
                 merged_metadata = {**existing_metadata, **meta}
                 new_title = p.display_name if p.display_name is not None else existing_row[0]
-                new_content = p.canonical_email if p.canonical_email is not None else existing_row[1]
+                new_content = (
+                    p.canonical_email if p.canonical_email is not None else existing_row[1]
+                )
                 new_embedding = emb_blob if emb_blob is not None else existing_row[2]
                 changed = (
                     new_title != existing_row[0]
@@ -647,9 +653,7 @@ class SQLiteBackend(StorageBackend):
                 if parent_id is None:
                     parent_id = await self._resolve_existing_entity_id(conn, e.platform, parent_ref)
                 if parent_id is None:
-                    raise ValueError(
-                        f"Retention parent {e.platform}:{parent_ref} is not available"
-                    )
+                    raise ValueError(f"Retention parent {e.platform}:{parent_ref} is not available")
             elif e.retention_parent_platform_entity_id is not None:
                 raise ValueError(
                     f"Entity {e.platform}:{e.platform_entity_id} has a parent but is not owned"
@@ -660,8 +664,8 @@ class SQLiteBackend(StorageBackend):
                     """
                     INSERT INTO entities
                         (id, entity_type, platform, platform_entity_id, title, metadata,
-                         retention_policy, retention_parent_id)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                         created_at, updated_at, retention_policy, retention_parent_id)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                     ON CONFLICT (platform, platform_entity_id) DO UPDATE SET
                         entity_type = entities.entity_type
                     RETURNING id
@@ -673,6 +677,8 @@ class SQLiteBackend(StorageBackend):
                         e.platform_entity_id,
                         e.title,
                         json.dumps(dict(e.metadata)),
+                        now,
+                        now,
                         e.retention_policy,
                         parent_id,
                     ],
@@ -689,8 +695,12 @@ class SQLiteBackend(StorageBackend):
                     [e.platform, e.platform_entity_id],
                 )
                 existing_row = await existing_cursor.fetchone()
-                existing_title = str(existing_row["title"]) if existing_row and existing_row["title"] else ""
-                existing_content = str(existing_row["content"]) if existing_row and existing_row["content"] else ""
+                existing_title = (
+                    str(existing_row["title"]) if existing_row and existing_row["title"] else ""
+                )
+                existing_content = (
+                    str(existing_row["content"]) if existing_row and existing_row["content"] else ""
+                )
                 fts_title = e.title if e.title is not None else existing_title
                 fts_content = e.content if e.content is not None else existing_content
                 rewrite_fts = (
@@ -752,8 +762,8 @@ class SQLiteBackend(StorageBackend):
                     INSERT INTO entities
                         (id, entity_type, platform, platform_entity_id, title, content,
                          content_embedding, metadata, source_created_at, source_updated_at,
-                         synced_at, retention_policy, retention_parent_id)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                         synced_at, created_at, updated_at, retention_policy, retention_parent_id)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                     ON CONFLICT (platform, platform_entity_id) DO UPDATE SET
                         entity_type       = CASE WHEN entities.entity_type = 'Document' THEN EXCLUDED.entity_type ELSE entities.entity_type END,
                         title             = COALESCE(EXCLUDED.title, entities.title),
@@ -780,6 +790,8 @@ class SQLiteBackend(StorageBackend):
                         source_created,
                         source_updated,
                         now,
+                        now,
+                        local_updated,
                         e.retention_policy,
                         parent_id,
                         local_updated,
@@ -1734,7 +1746,14 @@ class SQLiteBackend(StorageBackend):
             WHERE platform = ? AND platform_entity_id = ?
               AND retention_policy = 'observed'
             """,
-            [observation_duration_ms, now, observation_duration_ms, now, platform, platform_entity_id],
+            [
+                observation_duration_ms,
+                now,
+                observation_duration_ms,
+                now,
+                platform,
+                platform_entity_id,
+            ],
         )
 
     async def record_observation_once(
@@ -1772,7 +1791,14 @@ class SQLiteBackend(StorageBackend):
                         WHERE platform = ? AND platform_entity_id = ?
                           AND retention_policy = 'observed'
                         """,
-                        [observation_duration_ms, now, observation_duration_ms, now, platform, platform_entity_id],
+                        [
+                            observation_duration_ms,
+                            now,
+                            observation_duration_ms,
+                            now,
+                            platform,
+                            platform_entity_id,
+                        ],
                     )
                 await conn.execute("COMMIT")
                 return inserted is not None
@@ -1871,8 +1897,12 @@ def _row_to_entity(row: Any) -> EntityResult:
         "synced_at": row["synced_at"] if "synced_at" in keys else None,
         "observed_at": row["observed_at"] if "observed_at" in keys else None,
         "retention_policy": row["retention_policy"] if "retention_policy" in keys else "observed",
-        "retention_parent_id": row["retention_parent_id"] if "retention_parent_id" in keys else None,
-        "cumulative_observation_duration_ms": row["cumulative_observation_duration_ms"] if "cumulative_observation_duration_ms" in keys else 0,
+        "retention_parent_id": row["retention_parent_id"]
+        if "retention_parent_id" in keys
+        else None,
+        "cumulative_observation_duration_ms": row["cumulative_observation_duration_ms"]
+        if "cumulative_observation_duration_ms" in keys
+        else 0,
         "bookmarked": bool(row["bookmarked"]) if "bookmarked" in keys else False,
         "score": row["score"] if "score" in keys else None,
     }

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/agentgraph/cli.py

@@ -4,8 +4,12 @@ from __future__ import annotations
 
 import asyncio
 import json as _json
+import urllib.error
+import urllib.request
 from collections.abc import Iterator
 from contextlib import contextmanager
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
 from typing import TYPE_CHECKING, cast
 
 import typer
@@ -18,6 +22,33 @@ app = typer.Typer(
     help="Local knowledge graph for AI agents.",
     no_args_is_help=True,
 )
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+
+    try:
+        current = package_version("agentgraph-server")
+    except PackageNotFoundError:
+        current = "unknown"
+    typer.echo(f"agentgraph {current}")
+    raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the installed version and exit.",
+    ),
+) -> None:
+    """Configure global CLI options."""
+
+
 demo_app = typer.Typer(
     help="Create reproducible local demo graphs.",
     no_args_is_help=True,
@@ -50,30 +81,58 @@ def _status_label(status: str) -> str:
     )
 
 
-@demo_app.command("seed")
-def seed_demo_command(
-    force: bool = typer.Option(False, "--force", help="Replace an existing demo database"),
+def _server_is_running() -> bool:
+    """Return whether the configured AgentGraph server responds to health checks."""
+    from agentgraph.config import get_settings
+
+    settings = get_settings()
+    host = "127.0.0.1" if settings.server_host in ("", "0.0.0.0", "::") else settings.server_host
+    url = f"http://{host}:{settings.server_port}/health"
+    try:
+        with urllib.request.urlopen(url, timeout=1) as response:
+            return response.status == 200
+    except (OSError, urllib.error.URLError):
+        return False
+
+
+@demo_app.command("add")
+def add_demo_command(
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
-    """Seed the fictional Atlas graph used by the launch demo."""
+    """Add the fictional Atlas graph to the configured database."""
     from agentgraph.config import get_config_paths
-    from agentgraph.demo import seed_demo
+    from agentgraph.demo import add_demo
 
     try:
-        result = asyncio.run(seed_demo(get_config_paths()[0], force=force))
-    except (FileExistsError, ValueError) as exc:
+        result = asyncio.run(add_demo(get_config_paths()[0]))
+    except ValueError as exc:
         typer.echo(str(exc), err=True)
         raise typer.Exit(code=1) from exc
 
     if json:
         typer.echo(_json.dumps(result, indent=2))
         return
-    typer.echo(f"Seeded Atlas demo graph at {result['database']}")
+    typer.echo(f"Added Atlas demo fixtures to {result['database']}")
     typer.echo(
         f"{result['entities']} entities, {result['persons']} people, {result['edges']} edges"
     )
 
 
+@demo_app.command("remove")
+def remove_demo_command(
+    json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Remove Atlas demo fixtures from the configured database."""
+    from agentgraph.config import get_config_paths
+    from agentgraph.demo import remove_demo
+
+    result = asyncio.run(remove_demo(get_config_paths()[0]))
+    if json:
+        typer.echo(_json.dumps(result, indent=2))
+        return
+    typer.echo(f"Removed {result['removed']} Atlas demo entities from {result['database']}")
+
+
 def _remove_auth_credentials(provider: str, account_id: str | None) -> dict[str, object]:
     from agentgraph.auth.credentials import remove_platform, remove_platform_account
 
@@ -416,6 +475,7 @@ def serve(
     settings = get_settings()
     configure_logging(settings.log_level, settings.log_file)
     typer.echo(f"AgentGraph config directory: {get_config_paths()[0]}")
+    typer.echo(f"AgentGraph log file: {settings.log_file.expanduser()}")
     uvicorn.run(
         "agentgraph.server.app:app",
         host=settings.server_host,
@@ -581,8 +641,15 @@ def onboard() -> None:
         if label not in seen:
             seen[label] = connector
 
-    steps = list(seen.items())
-    total = len(steps)
+    # Only connectors with an explicit onboarding prompt own an interactive setup flow.
+    # Generic connectors such as Web are configured through connector commands instead.
+    steps = [
+        (label, connector)
+        for label, connector in seen.items()
+        if getattr(connector, "onboard_prompt", None)
+    ]
+    steps.sort(key=lambda item: getattr(item[1], "onboard_last", False))
+    total = len(steps) + 1
 
     typer.echo("=== AgentGraph Setup ===\n")
 
@@ -597,11 +664,12 @@ def onboard() -> None:
         if i < total:
             typer.echo()
 
+    typer.echo(f"\nStep {total}/{total}: Install the AgentGraph Chrome Extension")
     typer.echo(
-        "\nInstall the AgentGraph Chrome Extension: "
         "https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi"
     )
-    typer.echo("Run `agentgraph serve` to start the server.")
+    if not _server_is_running():
+        typer.echo("Run `agentgraph serve` to start the server.")
 
 
 @app.command()

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/agentgraph/config.py

@@ -125,7 +125,7 @@ class Settings(BaseSettings):
     )
     # Logging
     log_level: str = Field(default="INFO")
-    log_file: Path = Field(default=Path("/tmp/agentgraph.log"))
+    log_file: Path = Field(default_factory=lambda: get_config_paths()[0] / "agentgraph.log")
 
     def __init__(self, **values: Any) -> None:
         # Resolve the config-directory .env at instantiation time as well as

{agentgraph_server-0.5.3 → agentgraph_server-0.6.0}/agentgraph/connectors/base.py

@@ -34,13 +34,13 @@ _URL_RE = re.compile(r"https?://\S+")
 
 # Maps ResourceType values to entity_type strings stored in the DB
 RESOURCE_TYPE_TO_ENTITY_TYPE: dict[str, str] = {
-    "channel":     "Channel",
-    "dm":          "Channel",
-    "document":    "Document",
-    "folder":      "Folder",
-    "message":     "Message",
+    "channel": "Channel",
+    "dm": "Channel",
+    "document": "Document",
+    "folder": "Folder",
+    "message": "Message",
     "spreadsheet": "Spreadsheet",
-    "thread":      "Email",
+    "thread": "Email",
 }
 
 
@@ -76,10 +76,11 @@ class PersonRecord(BaseModel):
     platform_username: str | None = None
     canonical_email: str | None = None
     display_name: str | None = None
+    metadata: dict[str, str | int | float | bool | None] = {}
 
 
 class EntityRecord(BaseModel):
-    entity_type: str          # 'Message' | 'Document' | 'Channel' | 'Task'
+    entity_type: str  # 'Message' | 'Document' | 'Channel' | 'Task'
     platform: str
     platform_entity_id: str
     title: str | None = None
@@ -87,13 +88,13 @@ class EntityRecord(BaseModel):
     source_created_at: datetime | None = None
     source_updated_at: datetime | None = None
     metadata: dict[str, str | int | float | bool | None] = {}
-    is_stub: bool = False     # True → placeholder pending a full fetch; preserves synced_at=NULL
+    is_stub: bool = False  # True → placeholder pending a full fetch; preserves synced_at=NULL
     retention_policy: RetentionPolicy = "observed"
     retention_parent_platform_entity_id: str | None = None
 
 
 class EdgeRecord(BaseModel):
-    edge_type: str            # 'authored' | 'posted_in' | 'replied_to' | 'mentions'
+    edge_type: str  # 'authored' | 'posted_in' | 'replied_to' | 'mentions'
     source_platform_entity_id: str | None = None
     source_platform_user_id: str | None = None
     target_platform_entity_id: str | None = None
@@ -132,18 +133,22 @@ class EntityBatch(BaseModel):
             if ref.source == entity.platform and ref.resource_id == entity.platform_entity_id:
                 continue
             seen.add(key)
-            self.entities.append(EntityRecord(
-                entity_type=RESOURCE_TYPE_TO_ENTITY_TYPE[ref.resource_type],
-                platform=ref.source,
-                platform_entity_id=ref.resource_id,
-                is_stub=True,
-            ))
-            self.edges.append(EdgeRecord(
-                edge_type="references",
-                source_platform_entity_id=entity.platform_entity_id,
-                target_platform_entity_id=ref.resource_id,
-                platform="cross",
-            ))
+            self.entities.append(
+                EntityRecord(
+                    entity_type=RESOURCE_TYPE_TO_ENTITY_TYPE[ref.resource_type],
+                    platform=ref.source,
+                    platform_entity_id=ref.resource_id,
+                    is_stub=True,
+                )
+            )
+            self.edges.append(
+                EdgeRecord(
+                    edge_type="references",
+                    source_platform_entity_id=entity.platform_entity_id,
+                    target_platform_entity_id=ref.resource_id,
+                    platform="cross",
+                )
+            )
 
 
 async def get_known_channel_syncs(
@@ -195,7 +200,6 @@ class ConnectorAccount(BaseModel):
     metadata: dict[str, str] = Field(default_factory=dict)
 
 
-
 class FetchPolicy:
     """Encapsulates refresh policy decisions for a resource."""
 
@@ -222,7 +226,7 @@ class FetchPolicy:
 
 
 class BaseConnector(ABC):
-    source: ClassVar[str]           # platform name, e.g. "slack" — must be set by subclass
+    source: ClassVar[str]  # platform name, e.g. "slack" — must be set by subclass
     fetch_policy: ClassVar[FetchPolicy]  # staleness policy — must be set by subclass
     is_generic_url_fallback: ClassVar[bool] = False
     """True for broad fallback connectors that should not claim URLs during discovery."""
@@ -242,6 +246,7 @@ class BaseConnector(ABC):
     auth_label: ClassVar[str | None] = None
     auth_description: ClassVar[str | None] = None
     onboard_prompt: ClassVar[str | None] = None
+    onboard_last: ClassVar[bool] = False
     appears_in_auth_status: ClassVar[bool] = True
     """True for connectors backed by user/provider credentials.
 
@@ -280,14 +285,16 @@ class BaseConnector(ABC):
         user = cls.get_authenticated_user()
         if user is None:
             return []
-        return [ConnectorAccount(
-            account_id=cls.source,
-            label=user,
-            auth_group=cls.auth_label or cls.source,
-            source=cls.source,
-            user_id=user,
-            email=user if "@" in user else None,
-        )]
+        return [
+            ConnectorAccount(
+                account_id=cls.source,
+                label=user,
+                auth_group=cls.auth_label or cls.source,
+                source=cls.source,
+                user_id=user,
+                email=user if "@" in user else None,
+            )
+        ]
 
     @classmethod
     async def verify_auth(cls, account_id: str | None = None) -> tuple[str, str | None]:
@@ -339,9 +346,7 @@ class BaseConnector(ABC):
         _ = (args, result)
         return ConnectorCommandEffects()
 
-    def normalise_fetch_id(
-        self, resource_id: str, entity_type: str
-    ) -> tuple[str, ResourceType]:
+    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