Merge branch 'main' into feature/entity-sharing-full-mcp

Author: visahak

.env.example

@@ -1,8 +1,8 @@
 # Required: API key for LLM access
 OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
 
-# Optional: Evolve Backend Configuration
-# EVOLVE_BACKEND=filesystem
+# Optional: Evolve Backend Configuration (default: filesystem)
+# EVOLVE_BACKEND=filesystem  # Options: filesystem, postgres, milvus
 # EVOLVE_NAMESPACE_ID=evolve
 
 # Optional: LLM Configuration
@@ -11,4 +11,17 @@ OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
 # OPENAI_BASE_URL=https://api.openai.com/v1
 
 # Optional: Advanced Settings
-# EVOLVE_CLUSTERING_THRESHOLD=0.80
+# EVOLVE_CLUSTERING_THRESHOLD=0.80
+
+# Optional: Postgres backend (requires: pip install altk-evolve[pgvector])
+# EVOLVE_BACKEND=postgres
+# EVOLVE_PG_HOST=127.0.0.1
+# EVOLVE_PG_PORT=5432
+# EVOLVE_PG_USER=postgres
+# EVOLVE_PG_PASSWORD=postgres  # pragma: allowlist secret
+# EVOLVE_PG_DBNAME=evolve
+# EVOLVE_PG_AUTO_CREATE_DB=true
+# EVOLVE_PG_BOOTSTRAP_DB=postgres
+
+# Optional: Milvus backend (requires: pip install altk-evolve[milvus])
+# EVOLVE_BACKEND=milvus

.pre-commit-config.yaml

@@ -2,6 +2,16 @@
 # See https://pre-commit.com for more information
 
 repos:
+  # Mypy - Python static type checking (using uv)
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy .
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+
   # Ruff - Python linting and formatting (using uv)
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.3

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$|package-lock\\.json$",
     "lines": null
   },
-  "generated_at": "2026-04-16T17:29:52Z",
+  "generated_at": "2026-04-20T15:55:53Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -82,7 +82,7 @@
         "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 58,
+        "line_number": 74,
         "type": "Secret Keyword",
         "verified_result": null
       }

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 <!-- version list -->
 
+## v1.0.10 (2026-04-20)
+
+### Bug Fixes
+
+- **mcp**: Align metadata filters and harden SSE teardown
+  ([`a0bcc6d`](https://github.com/AgentToolkit/altk-evolve/commit/a0bcc6db5ac5fdb4808d6e11e451eb3156ba9596))
+
+- **postgres**: Prevent ambiguous filter behavior across backends
+  ([`a0bcc6d`](https://github.com/AgentToolkit/altk-evolve/commit/a0bcc6db5ac5fdb4808d6e11e451eb3156ba9596))
+
+
 ## v1.0.9 (2026-04-17)
 
 ### Bug Fixes

README.md

@@ -51,6 +51,22 @@ From PyPI
 pip install altk-evolve
 ```
 
+**Optional Backend Dependencies:**
+
+The default filesystem backend uses simple text matching and requires no additional dependencies. For semantic vector similarity search, install one of these backends:
+
+For PostgreSQL with pgvector support (recommended for production):
+```bash
+uv sync --extra pgvector
+```
+
+For Milvus support (optimized for large-scale vector search):
+```bash
+uv sync --extra milvus
+```
+
+See the [Backend Configuration Guide](docs/guides/backend-configuration.md) for detailed comparison and setup instructions.
+
 ### Configuration
 
 For direct OpenAI usage:
@@ -96,6 +112,13 @@ npx @modelcontextprotocol/inspector@latest http://127.0.0.1:8201/sse --cli --met
 - `create_entity(content: str, entity_type: str, metadata: str | None, enable_conflict_resolution: bool)`: Create a single entity in the namespace.
 - `delete_entity(entity_id: str)`: Delete a specific entity by its ID.
 
+### Filter Migration Note
+Entity search filters reserve bare keys for top-level schema columns only: `id`, `type`, `content`, and `created_at`.
+
+If you need to filter on JSON metadata, use the `metadata.<key>` form. For example, use `filters={"type": "trajectory", "metadata.task_id": "123"}` instead of `filters={"type": "trajectory", "task_id": "123"}`.
+
+Existing integrations that stored custom fields in entity metadata should update filter writers to add the `metadata.` prefix for those keys.
+
 ## Features
 - **Proactive**: Learns how to recognize problems and their solutions, and generates guidelines that get automatically applied to new tasks.
 - **Conflict Resolution**: Update existing guidelines when new information contradicts them.
@@ -164,4 +187,4 @@ Evolve is an active project, and real‑world usage helps guide its direction.
 
 If you’re experimenting with Evolve or exploring on‑the‑job learning for agents, feel free to open an issue or discussion to share use cases, ideas, or feedback.
 
-See the [Contributing Guide](CONTRIBUTING.md) to understand our development process, or how to submit changes, report bugs, or propose features.
+See the [Contributing Guide](CONTRIBUTING.md) to understand our development process, or how to submit changes, report bugs, or propose features.

altk_evolve/__init__.py

@@ -1 +1 @@
-__version__ = "1.0.9"
+__version__ = "1.0.10"

altk_evolve/backend/postgres.py

@@ -43,18 +43,13 @@ class PostgresEntityBackend(BaseEntityBackend):
     embedding_model: SentenceTransformer
     embedding_dim: int
     _settings: PostgresDBSettings
+    _schema_filter_fields = {"id", "type", "content", "created_at"}
+    _metadata_filter_prefix = "metadata."
 
     def __init__(self, config: BaseSettings | None = None):
         super().__init__(config)
         self._settings = config if isinstance(config, type(postgres_db_settings)) else postgres_db_settings
-        self.conn = psycopg.connect(
-            host=self._settings.host,
-            port=self._settings.port,
-            user=self._settings.user,
-            password=self._settings.password,
-            dbname=self._settings.dbname,
-            autocommit=True,
-        )
+        self.conn = self._connect_target_db()
         try:
             self._ensure_pgvector_extension()
             register_vector(self.conn)
@@ -70,6 +65,87 @@ def __init__(self, config: BaseSettings | None = None):
                 self.conn.close()
             raise
 
+    def _connect(self, dbname: str) -> psycopg.Connection:
+        return psycopg.connect(
+            host=self._settings.host,
+            port=self._settings.port,
+            user=self._settings.user,
+            password=self._settings.password,
+            dbname=dbname,
+            autocommit=True,
+        )
+
+    def _is_missing_database_error(self, error: Exception) -> bool:
+        # Check for SQL state code 3D000 (invalid catalog name)
+        if getattr(error, "sqlstate", None) == "3D000":
+            return True
+        # Also check error message for database does not exist
+        error_msg = str(error).lower()
+        return "database" in error_msg and "does not exist" in error_msg
+
+    def _create_database(self) -> None:
+        logger.info(
+            "Database '%s' not found; attempting bootstrap via '%s'",
+            self._settings.dbname,
+            self._settings.bootstrap_db,
+        )
+
+        # Try multiple common administrative databases as fallbacks
+        bootstrap_candidates = [
+            self._settings.bootstrap_db,  # User-configured (default: "postgres")
+            "template1",  # PostgreSQL default template database
+            self._settings.user,  # User's default database (often created automatically)
+        ]
+
+        # Remove duplicates while preserving order
+        seen = set()
+        bootstrap_dbs = []
+        for db in bootstrap_candidates:
+            if db not in seen:
+                seen.add(db)
+                bootstrap_dbs.append(db)
+
+        last_error = None
+        for bootstrap_db in bootstrap_dbs:
+            try:
+                logger.debug("Attempting to connect to bootstrap database: %s", bootstrap_db)
+                admin_conn = self._connect(bootstrap_db)
+                try:
+                    with admin_conn.cursor() as cur:
+                        cur.execute(sql.SQL("CREATE DATABASE {dbname}").format(dbname=sql.Identifier(self._settings.dbname)))
+                    logger.info("Successfully created database '%s' using bootstrap database '%s'", self._settings.dbname, bootstrap_db)
+                    return
+                except Exception as create_error:
+                    # Check if database already exists (race condition with another process)
+                    sqlstate = getattr(create_error, "sqlstate", None)
+                    if sqlstate == "42P04":  # duplicate_database
+                        logger.debug("Database '%s' already exists (created by another process)", self._settings.dbname)
+                        return  # Treat as success
+                    raise  # Re-raise other errors
+                finally:
+                    if not admin_conn.closed:
+                        admin_conn.close()
+            except Exception as e:
+                last_error = e
+                logger.debug("Failed to use bootstrap database '%s': %s", bootstrap_db, e)
+                continue
+
+        # If all bootstrap databases failed, raise the last error with helpful message
+        raise EvolveException(
+            f"Failed to create database '{self._settings.dbname}'. "
+            f"Tried bootstrap databases: {', '.join(bootstrap_dbs)}. "
+            f"Last error: {last_error}"
+        )
+
+    def _connect_target_db(self) -> psycopg.Connection:
+        try:
+            return self._connect(self._settings.dbname)
+        except Exception as e:
+            if not self._settings.auto_create_db or not self._is_missing_database_error(e):
+                raise
+            self._create_database()
+            return self._connect(self._settings.dbname)
+
     def _ensure_pgvector_extension(self):
         """Ensure the pgvector extension is installed."""
         with self.conn.cursor() as cur:
@@ -214,11 +290,38 @@ def search_entities(
         table = self._table_name(namespace_id)
         filters = filters or {}
 
-        where_parts = []
-        params: list = []
-        for k, v in filters.items():
-            where_parts.append(sql.SQL("{} = %s").format(sql.Identifier(k)))
-            params.append(v)
+        where_parts: list[sql.Composable] = []
+        params: list[Any] = []
+        for key, value in filters.items():
+            if value is None:
+                continue
+
+            if key in self._schema_filter_fields:
+                where_parts.append(sql.SQL("{} = %s").format(sql.Identifier(key)))
+                params.append(value)
+                continue
+
+            if not key.startswith(self._metadata_filter_prefix):
+                accepted_keys = sorted(self._schema_filter_fields)
+                logger.error(
+                    "Invalid Postgres search filter key %r. Accepted schema keys: %s. "
+                    "Metadata filters must be prefixed with %r. filters=%r metadata_key=%r where_parts=%r params=%r",
+                    key,
+                    accepted_keys,
+                    self._metadata_filter_prefix,
+                    filters,
+                    None,
+                    [repr(part) for part in where_parts],
+                    params,
+                )
+                raise ValueError(
+                    f"Invalid filter key '{key}'. Accepted schema keys: {accepted_keys}. "
+                    f"Metadata filters must use the '{self._metadata_filter_prefix}<key>' form."
+                )
+
+            metadata_key = key.split(".", 1)[1]
+            where_parts.append(sql.SQL("metadata @> %s::jsonb"))
+            params.append(json.dumps({metadata_key: value}))
         where_clause = sql.SQL(" AND ").join(where_parts) if where_parts else sql.SQL("TRUE")
 
         if query is None:

altk_evolve/cli/cli.py

@@ -23,11 +23,13 @@
 entities_app = typer.Typer(help="Entity management commands")
 sync_app = typer.Typer(help="Sync commands")
 skills_app = typer.Typer(help="Skill management commands")
+viz_app = typer.Typer(help="Visualization commands")
 
 app.add_typer(namespaces_app, name="namespaces")
 app.add_typer(entities_app, name="entities")
 app.add_typer(sync_app, name="sync")
 app.add_typer(skills_app, name="skills")
+app.add_typer(viz_app, name="viz")
 
 console = Console()
 
@@ -544,5 +546,22 @@ def package_skills(
         sys.exit(1)
 
 
+# =============================================================================
+# Viz Commands
+# =============================================================================
+
+
+@viz_app.command("serve")
+def serve_viz(
+    evolve_dir: Annotated[Path, typer.Option("--evolve-dir", "-d", help="Path to .evolve directory")] = Path(".evolve"),
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to serve on")] = 7891,
+    no_browser: Annotated[bool, typer.Option("--no-browser", help="Don't open browser automatically")] = False,
+):
+    """Serve the Evolve Viz web interface for browsing entities and trajectories."""
+    from altk_evolve.viz.server import serve
+
+    serve(evolve_dir=evolve_dir.resolve(), port=port, open_browser=not no_browser)
+
+
 if __name__ == "__main__":
     app()

altk_evolve/config/evolve.py

@@ -4,7 +4,7 @@
 
 class EvolveConfig(BaseSettings):
     model_config = SettingsConfigDict(env_prefix="EVOLVE_")
-    backend: Literal["milvus", "filesystem", "postgres"] = "milvus"
+    backend: Literal["milvus", "filesystem", "postgres"] = "filesystem"
     namespace_id: str = "evolve"
     settings: BaseSettings | None = None
     clustering_threshold: float = 0.80

altk_evolve/config/postgres.py

@@ -10,6 +10,8 @@ class PostgresDBSettings(BaseSettings):
     user: str = Field(default="postgres")
     password: str = Field(default="postgres")
     dbname: str = Field(default="evolve")
+    auto_create_db: bool = Field(default=False)
+    bootstrap_db: str = Field(default="postgres")
 
 
 # to reload settings call postgres_db_settings.__init__()