everalgo-clustering 0.1.0__tar.gz

everalgo_clustering-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage / cache
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+
+# Project local artifacts (placed under local/ per project convention)
+local/
+
+# Claude Code session-local state (scheduled tasks, agent caches, locks)
+.claude/

everalgo_clustering-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `cluster_by_geometry(embedding, state, *, threshold, time_window_days) -> tuple[int, ClusterState]`: cosine similarity + time-window incremental assignment; no LLM; pure-sync function.
+- `cluster_by_llm(embedding, state, cluster_previews, *, llm, threshold, time_window_days, k_candidates, llm_skip_threshold) -> tuple[int, ClusterState]`: embedding top-K recall + cosine fast-path skip + LLM ranking; async; raises on LLM failure or malformed JSON.
+- `ClusterState` frozen pydantic model with four fields: `centroids: dict[int, list[float]]`, `counts: dict[int, int]`, `last_ts: dict[int, int]` (ms-epoch int), `next_idx: int`. Provides `empty()`, `to_dict()`, `from_dict()`, and a private `_assign()` mutation method.
+- English clustering prompt `CLUSTER_LLM_ASSIGN_PROMPT` in `prompts/en/cluster.py`; Chinese variant re-exports the English prompt (the template is language-neutral; responses adapt to the corpus language).
+
+### Changed
+
+- `ClusterState.last_ts` stores millisecond epoch integers instead of float seconds, aligning with `MemCell.timestamp` and `Episode.timestamp` conventions across EverAlgo.
+- `ClusterState` tracks `next_idx` as an explicit field instead of deriving cluster numbering from `max(centroids.keys()) + 1`, which was a footgun when cluster IDs were deleted.
+
+### Removed
+
+- `ClusterConfig` dataclass: threshold, time-window, and candidate-count parameters are now keyword arguments on each function, allowing callers to pass only what they use.
+- Geometric fallback path inside `cluster_by_llm`: the function raises on LLM failure rather than silently falling back to geometry.
+- 3-retry loop in `cluster_by_llm`: the function raises `ValueError` immediately on bad LLM JSON.
+
+[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/main...HEAD

everalgo_clustering-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EverMind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everalgo_clustering-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: everalgo-clustering
+Version: 0.1.0
+Summary: EverAlgo clustering: cluster_by_geometry / cluster_by_llm functional operators with ClusterState value object.
+Project-URL: Homepage, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Repository, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Issues, https://github.com/EverMind-AI/EverAlgo/issues
+Project-URL: Documentation, https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-clustering
+Project-URL: Changelog, https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-clustering/CHANGELOG.md
+Author: EverMind
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: everalgo-core<2.0.0,>=0.1.0
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# everalgo-clustering
+
+Online incremental clustering for EverAlgo — two async functions (`cluster_by_geometry` / `cluster_by_llm`) operating on caller-owned `list[Cluster]` state.
+
+Stateless: the package never embeds, never queries storage, never holds a lock. The caller owns embedding computation, persistence (`list[Cluster]` serialisation), and read-modify-write coordination across concurrent writers.
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-clustering
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `Cluster` | Frozen Pydantic value object — one cluster snapshot. Caller-supplied `id` / `members`; algorithm supplies merged `centroid`, `count`, `last_ts`, `preview`. |
+| `cluster_by_geometry` | Cosine similarity + time-window filter + threshold; no LLM; async |
+| `cluster_by_llm` | Top-K geometric recall → fast-path skip → LLM semantic ranking; raises on LLM failure; async |
+
+## Cluster type
+
+```python
+class Cluster(BaseModel):
+    id: str | None = None           # caller-supplied business id; algo only passes through, never mints
+    centroid: np.ndarray
+    count: int = 1
+    last_ts: int                    # Unix epoch milliseconds
+    preview: list[str] = []
+    members: list[str] = []         # caller-supplied entity ids; algo appends on merge, never inspects
+```
+
+The caller wraps each incoming item as a size-1 `Cluster` (count=1) before passing to either function.
+Both functions return `Cluster | None`: a merged snapshot when the item is assigned to an existing cluster, or `None` when no match — the caller then appends the original size-1 `Cluster` as a brand-new entry and mints its own `id`.
+
+## Quick start
+
+```python
+import asyncio
+import numpy as np
+from everalgo.clustering import Cluster, cluster_by_geometry
+
+async def main() -> None:
+    existing: list[Cluster] = []  # caller loads from storage; empty on first run
+    vector = np.random.rand(2560).astype(np.float32)
+    timestamp_ms = 1_700_000_000_000
+
+    new_cluster = Cluster(centroid=vector, last_ts=timestamp_ms)
+    merged = await cluster_by_geometry(
+        new_cluster,
+        existing,
+        threshold=0.65,        # cosine similarity floor
+        time_window_days=7.0,  # ignore clusters older than this window
+    )
+
+    if merged is not None:
+        # item assigned to an existing cluster; caller updates the matching entry
+        print(f"merged into cluster id={merged.id!r}, new count={merged.count}")
+    else:
+        # no match — caller appends new_cluster and stamps its own id
+        new_cluster_with_id = new_cluster.model_copy(update={"id": "cid_001"})
+        existing.append(new_cluster_with_id)
+        print("created new cluster")
+
+asyncio.run(main())
+```
+
+## LLM-refined clustering
+
+`cluster_by_llm` adds a semantic ranking step over the top-K geometrically-nearest candidates. It **raises** on LLM failure — there is no internal fallback; the caller decides whether to retry or fall back to `cluster_by_geometry`.
+
+Populate `new_cluster.preview` with the item's representative text so the LLM has something to rank against.
+
+```python
+import asyncio
+import numpy as np
+from everalgo.clustering import Cluster, cluster_by_llm
+from everalgo.llm.types import ChatResponse
+from everalgo.testing.fake_llm import FakeLLMClient
+
+_LLM_JSON = '{"idx": 0}'
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_LLM_JSON, model="fake")])
+    existing: list[Cluster] = []
+    vector = np.random.rand(2560).astype(np.float32)
+
+    new_cluster = Cluster(
+        centroid=vector,
+        last_ts=1_700_000_000_000,
+        preview=["Python async retry patterns"],  # shown to the LLM
+    )
+    merged = await cluster_by_llm(
+        new_cluster,
+        existing,
+        llm=fake,
+        k_candidates=30,
+        llm_skip_threshold=0.85,
+    )
+    print(f"merged: {merged}")
+
+asyncio.run(main())
+```
+
+## Persistence pattern
+
+`Cluster` is a frozen Pydantic model — serialise with `model_dump()` and reconstruct with `Cluster.model_validate()`. The caller owns the list and the lock:
+
+```python
+raw_list = await store.load(user_id) or []
+clusters = [Cluster.model_validate(r) for r in raw_list]
+
+async with caller.lock(f"cluster:{user_id}"):
+    merged = await cluster_by_geometry(new_cluster, clusters)
+    if merged is not None:
+        idx = next(i for i, c in enumerate(clusters) if c.id == merged.id)
+        clusters[idx] = merged
+    else:
+        new_cluster_stamped = new_cluster.model_copy(update={"id": new_id})
+        clusters.append(new_cluster_stamped)
+    await store.save(user_id, [c.model_dump() for c in clusters])
+```
+
+## API reference
+
+```python
+async def cluster_by_geometry(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    threshold: float = 0.65,
+    time_window_days: float = 7.0,
+    preview_cap: int = 5,
+) -> Cluster | None: ...
+
+async def cluster_by_llm(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    llm: LLMClient,
+    k_candidates: int = 30,
+    llm_skip_threshold: float = 0.85,
+    prompt: str | None = None,
+    preview_cap: int = 5,
+) -> Cluster | None: ...
+```
+
+Both functions return the **merged** `Cluster` (existing cluster's `id` preserved, centroid/count/members updated) or `None` (no match — caller creates a new cluster entry and mints its own `id`).
+
+Tested embedding model: `Qwen3-Embedding-4B` (2560-dim float32). Any consistent-dimension embedding works; EverAlgo does not import or manage embedding SDKs.
+
+## Related distributions
+
+- [`everalgo-user-memory`](../everalgo-user-memory/) — uses `cluster_by_geometry` in the full user-memory pipeline
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — uses `cluster_by_llm` for skill clustering

everalgo_clustering-0.1.0/README.md

@@ -0,0 +1,157 @@
+# everalgo-clustering
+
+Online incremental clustering for EverAlgo — two async functions (`cluster_by_geometry` / `cluster_by_llm`) operating on caller-owned `list[Cluster]` state.
+
+Stateless: the package never embeds, never queries storage, never holds a lock. The caller owns embedding computation, persistence (`list[Cluster]` serialisation), and read-modify-write coordination across concurrent writers.
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-clustering
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `Cluster` | Frozen Pydantic value object — one cluster snapshot. Caller-supplied `id` / `members`; algorithm supplies merged `centroid`, `count`, `last_ts`, `preview`. |
+| `cluster_by_geometry` | Cosine similarity + time-window filter + threshold; no LLM; async |
+| `cluster_by_llm` | Top-K geometric recall → fast-path skip → LLM semantic ranking; raises on LLM failure; async |
+
+## Cluster type
+
+```python
+class Cluster(BaseModel):
+    id: str | None = None           # caller-supplied business id; algo only passes through, never mints
+    centroid: np.ndarray
+    count: int = 1
+    last_ts: int                    # Unix epoch milliseconds
+    preview: list[str] = []
+    members: list[str] = []         # caller-supplied entity ids; algo appends on merge, never inspects
+```
+
+The caller wraps each incoming item as a size-1 `Cluster` (count=1) before passing to either function.
+Both functions return `Cluster | None`: a merged snapshot when the item is assigned to an existing cluster, or `None` when no match — the caller then appends the original size-1 `Cluster` as a brand-new entry and mints its own `id`.
+
+## Quick start
+
+```python
+import asyncio
+import numpy as np
+from everalgo.clustering import Cluster, cluster_by_geometry
+
+async def main() -> None:
+    existing: list[Cluster] = []  # caller loads from storage; empty on first run
+    vector = np.random.rand(2560).astype(np.float32)
+    timestamp_ms = 1_700_000_000_000
+
+    new_cluster = Cluster(centroid=vector, last_ts=timestamp_ms)
+    merged = await cluster_by_geometry(
+        new_cluster,
+        existing,
+        threshold=0.65,        # cosine similarity floor
+        time_window_days=7.0,  # ignore clusters older than this window
+    )
+
+    if merged is not None:
+        # item assigned to an existing cluster; caller updates the matching entry
+        print(f"merged into cluster id={merged.id!r}, new count={merged.count}")
+    else:
+        # no match — caller appends new_cluster and stamps its own id
+        new_cluster_with_id = new_cluster.model_copy(update={"id": "cid_001"})
+        existing.append(new_cluster_with_id)
+        print("created new cluster")
+
+asyncio.run(main())
+```
+
+## LLM-refined clustering
+
+`cluster_by_llm` adds a semantic ranking step over the top-K geometrically-nearest candidates. It **raises** on LLM failure — there is no internal fallback; the caller decides whether to retry or fall back to `cluster_by_geometry`.
+
+Populate `new_cluster.preview` with the item's representative text so the LLM has something to rank against.
+
+```python
+import asyncio
+import numpy as np
+from everalgo.clustering import Cluster, cluster_by_llm
+from everalgo.llm.types import ChatResponse
+from everalgo.testing.fake_llm import FakeLLMClient
+
+_LLM_JSON = '{"idx": 0}'
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_LLM_JSON, model="fake")])
+    existing: list[Cluster] = []
+    vector = np.random.rand(2560).astype(np.float32)
+
+    new_cluster = Cluster(
+        centroid=vector,
+        last_ts=1_700_000_000_000,
+        preview=["Python async retry patterns"],  # shown to the LLM
+    )
+    merged = await cluster_by_llm(
+        new_cluster,
+        existing,
+        llm=fake,
+        k_candidates=30,
+        llm_skip_threshold=0.85,
+    )
+    print(f"merged: {merged}")
+
+asyncio.run(main())
+```
+
+## Persistence pattern
+
+`Cluster` is a frozen Pydantic model — serialise with `model_dump()` and reconstruct with `Cluster.model_validate()`. The caller owns the list and the lock:
+
+```python
+raw_list = await store.load(user_id) or []
+clusters = [Cluster.model_validate(r) for r in raw_list]
+
+async with caller.lock(f"cluster:{user_id}"):
+    merged = await cluster_by_geometry(new_cluster, clusters)
+    if merged is not None:
+        idx = next(i for i, c in enumerate(clusters) if c.id == merged.id)
+        clusters[idx] = merged
+    else:
+        new_cluster_stamped = new_cluster.model_copy(update={"id": new_id})
+        clusters.append(new_cluster_stamped)
+    await store.save(user_id, [c.model_dump() for c in clusters])
+```
+
+## API reference
+
+```python
+async def cluster_by_geometry(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    threshold: float = 0.65,
+    time_window_days: float = 7.0,
+    preview_cap: int = 5,
+) -> Cluster | None: ...
+
+async def cluster_by_llm(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    llm: LLMClient,
+    k_candidates: int = 30,
+    llm_skip_threshold: float = 0.85,
+    prompt: str | None = None,
+    preview_cap: int = 5,
+) -> Cluster | None: ...
+```
+
+Both functions return the **merged** `Cluster` (existing cluster's `id` preserved, centroid/count/members updated) or `None` (no match — caller creates a new cluster entry and mints its own `id`).
+
+Tested embedding model: `Qwen3-Embedding-4B` (2560-dim float32). Any consistent-dimension embedding works; EverAlgo does not import or manage embedding SDKs.
+
+## Related distributions
+
+- [`everalgo-user-memory`](../everalgo-user-memory/) — uses `cluster_by_geometry` in the full user-memory pipeline
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — uses `cluster_by_llm` for skill clustering

everalgo_clustering-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everalgo-clustering"
+version = "0.1.0"
+description = "EverAlgo clustering: cluster_by_geometry / cluster_by_llm functional operators with ClusterState value object."
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "EverMind" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "everalgo-core>=0.1.0,<2.0.0",
+  "numpy>=1.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/EverMind-AI/EverAlgo"
+Repository = "https://github.com/EverMind-AI/EverAlgo"
+Issues = "https://github.com/EverMind-AI/EverAlgo/issues"
+Documentation = "https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-clustering"
+Changelog = "https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-clustering/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everalgo"]

everalgo_clustering-0.1.0/src/everalgo/clustering/__init__.py

@@ -0,0 +1,26 @@
+"""Online incremental clustering operators — pure-function state-in / state-out.
+
+Public API:
+
+* :func:`cluster_by_geometry` — cosine similarity + time-window filter + threshold; no LLM.
+* :func:`cluster_by_llm` — embedding top-K recall + fast-path skip + LLM ranking.
+* :class:`Cluster` — frozen value object the caller threads through and persists as list[Cluster].
+
+Caller responsibilities: embedding (EverAlgo accepts any np.ndarray dimension as long as it is
+consistent across calls), persistence (Cluster.model_dump() / model_validate()), and
+read-modify-write serialisation if multiple writers share a list.
+"""
+
+import logging
+
+from everalgo.clustering.algorithm import cluster_by_geometry, cluster_by_llm
+from everalgo.clustering.state import Cluster
+
+__all__ = [
+    "Cluster",
+    "cluster_by_geometry",
+    "cluster_by_llm",
+]
+
+# ADR-013: per-subpackage logger gets a NullHandler so library use never emits to stderr by default.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

everalgo_clustering-0.1.0/src/everalgo/clustering/algorithm.py

@@ -0,0 +1,210 @@
+"""Cluster operators — geometry and LLM-refined paths over a list[Cluster] state.
+
+Both operators are async and stateless: accept a new_cluster + existing_clusters list, return
+a merged Cluster or None without mutating any input. The caller owns persistence and concurrency control.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from everalgo.clustering.prompts.en.cluster import CLUSTER_LLM_ASSIGN_PROMPT
+from everalgo.clustering.state import Cluster
+from everalgo.llm.parse import parse_llm_json_object
+from everalgo.llm.types import ChatMessage as LLMChatMessage
+from everalgo.prompts import render_prompt
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+
+__all__ = ["cluster_by_geometry", "cluster_by_llm"]
+
+logger = logging.getLogger(__name__)
+
+_MS_PER_DAY = 86_400_000
+_NORM_EPSILON = 1e-9
+
+
+async def cluster_by_geometry(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    threshold: float = 0.65,
+    time_window_days: float = 7.0,
+    preview_cap: int = 5,
+) -> Cluster | None:
+    """Cosine + time-window assignment.
+
+    Args:
+        new_cluster: Size-1 Cluster representing the incoming item.
+        existing_clusters: Caller-owned list; never mutated.
+        threshold: Cosine similarity >= this assigns to top-1. Default 0.65.
+        time_window_days: Clusters whose last_ts is older than this gap are excluded. Default 7.0.
+        preview_cap: Maximum preview length on the merged snapshot. Default 5.
+
+    Returns:
+        Merged Cluster when assigned to an existing one (id is passed through from
+        existing_clusters[i].id), or None when no match — caller appends new_cluster as a brand-new
+        cluster and mints its own id.
+    """
+    if not existing_clusters:
+        return None
+
+    idx = _find_best_within_window(
+        existing_clusters, new_cluster.centroid, new_cluster.last_ts, threshold, time_window_days
+    )
+    if idx is None:
+        return None
+    return _merge(existing_clusters[idx], new_cluster, preview_cap=preview_cap)
+
+
+async def cluster_by_llm(
+    new_cluster: Cluster,
+    existing_clusters: list[Cluster],
+    *,
+    llm: LLMClient,
+    k_candidates: int = 30,
+    llm_skip_threshold: float = 0.85,
+    prompt: str | None = None,
+    preview_cap: int = 5,
+) -> Cluster | None:
+    """LLM-refined assignment: top-K recall → fast path → LLM ranking by idx.
+
+    LLM ranking query text comes from new_cluster.preview[0] if preview else "".
+
+    Args:
+        new_cluster: Size-1 Cluster representing the incoming item.
+        existing_clusters: Caller-owned list; never mutated.
+        llm: LLM client for the Stage-2 ranking call.
+        k_candidates: Number of nearest clusters fetched before LLM ranking. Default 30.
+        llm_skip_threshold: Skip LLM and assign to top-1 when its similarity meets this. Default 0.85.
+        prompt: Optional override of the built-in LLM ranking prompt template.
+        preview_cap: Maximum preview length on the merged snapshot. Default 5.
+
+    Returns:
+        Merged Cluster when LLM ranks a match (id passed through), or None when LLM picks
+        "new" — caller appends new_cluster as a brand-new cluster and mints its own id.
+        LLM internally uses idx; idx -> existing_clusters[idx].id transparent to caller.
+
+    Raises:
+        LLMError: Propagated from the underlying LLM client call.
+        ValueError: If the LLM response cannot be parsed or is missing the 'idx' field.
+    """
+    if not existing_clusters:
+        return None
+
+    candidates = _find_top_k_clusters(existing_clusters, new_cluster.centroid, k_candidates)
+    if not candidates:
+        return None
+
+    top_idx, top_sim = candidates[0]
+
+    if top_sim >= llm_skip_threshold:
+        return _merge(existing_clusters[top_idx], new_cluster, preview_cap=preview_cap)
+
+    query_text = new_cluster.preview[0] if new_cluster.preview else ""
+    candidate_indices = [idx for idx, _ in candidates]
+    clusters_json = _build_clusters_json(existing_clusters, candidate_indices)
+    rendered = render_prompt(
+        CLUSTER_LLM_ASSIGN_PROMPT,
+        prompt,
+        memcell_text=query_text,
+        clusters_json=clusters_json,
+    )
+    response = await llm.chat(
+        messages=[LLMChatMessage(role="user", content=rendered)],
+        response_format={"type": "json_object"},
+    )
+    llm_result = parse_llm_json_object(response.content)
+    if "idx" not in llm_result:
+        raise ValueError("cluster_by_llm: LLM response missing 'idx' field")
+
+    chosen_idx = llm_result.get("idx")
+    if isinstance(chosen_idx, int) and 0 <= chosen_idx < len(existing_clusters):
+        return _merge(existing_clusters[chosen_idx], new_cluster, preview_cap=preview_cap)
+    return None
+
+
+# --- private helpers --------------------------------------------------------
+
+
+def _merge(existing: Cluster, new: Cluster, *, preview_cap: int) -> Cluster:
+    """Weighted centroid merge + preview concat + members append."""
+    total = existing.count + new.count
+    return Cluster(
+        id=existing.id,  # transparent passthrough — algo never generates id
+        centroid=(existing.centroid * existing.count + new.centroid * new.count) / total,
+        count=total,
+        last_ts=max(existing.last_ts, new.last_ts),
+        preview=(existing.preview + new.preview)[-preview_cap:],
+        members=existing.members + new.members,
+    )
+
+
+def _cosine(v: np.ndarray, c: np.ndarray) -> float:
+    """Cosine similarity with _NORM_EPSILON divide-by-zero guard."""
+    v_norm = float(np.linalg.norm(v)) + _NORM_EPSILON
+    c_norm = float(np.linalg.norm(c)) + _NORM_EPSILON
+    return float(np.dot(v, c) / (v_norm * c_norm))
+
+
+def _find_best_within_window(
+    clusters: list[Cluster],
+    vector: np.ndarray,
+    timestamp_ms: int,
+    threshold: float,
+    time_window_days: float,
+) -> int | None:
+    """Top-1 cluster index within the time window clearing threshold; None otherwise."""
+    max_gap_ms = int(time_window_days * _MS_PER_DAY)
+    best_idx: int | None = None
+    best_sim = -1.0
+
+    for i, cluster in enumerate(clusters):
+        if cluster.centroid.size == 0:
+            continue
+        if abs(timestamp_ms - cluster.last_ts) > max_gap_ms:
+            continue
+        sim = _cosine(vector, cluster.centroid)
+        if sim > best_sim:
+            best_sim = sim
+            best_idx = i
+
+    if best_idx is not None and best_sim >= threshold:
+        return best_idx
+    return None
+
+
+def _find_top_k_clusters(
+    clusters: list[Cluster],
+    vector: np.ndarray,
+    k: int,
+) -> list[tuple[int, float]]:
+    """Top-K clusters by cosine similarity (no time-window filter); empty-centroid clusters skipped."""
+    scored: list[tuple[int, float]] = []
+    for i, cluster in enumerate(clusters):
+        if cluster.centroid.size == 0:
+            continue
+        scored.append((i, _cosine(vector, cluster.centroid)))
+    scored.sort(key=lambda x: x[1], reverse=True)
+    return scored[:k]
+
+
+def _build_clusters_json(clusters: list[Cluster], candidate_indices: list[int]) -> str:
+    """Serialise candidate clusters to JSON for the {clusters_json} prompt placeholder."""
+    if not candidate_indices:
+        return "(No existing clusters)"
+
+    items = [
+        {
+            "idx": idx,
+            "count": clusters[idx].count,
+            "preview": clusters[idx].preview,
+        }
+        for idx in candidate_indices
+    ]
+    return json.dumps(items, ensure_ascii=False, indent=2)

everalgo_clustering-0.1.0/src/everalgo/clustering/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Clustering prompts (en + zh).
+
+Each prompt is a module-level Python string constant per AGENTS.md §5 (Code Style). Algorithm authors customize via
+per-call ``prompt=`` argument or by monkey-patching the constant at startup.
+"""

everalgo_clustering-0.1.0/src/everalgo/clustering/prompts/en/__init__.py

@@ -0,0 +1 @@
+"""English clustering prompts."""

everalgo_clustering-0.1.0/src/everalgo/clustering/prompts/en/cluster.py

@@ -0,0 +1,38 @@
+"""English clustering prompts for LLM-based cluster assignment.
+
+Placeholders (rendered via :py:meth:`str.format`):
+    - ``{memcell_text}`` — text representation of the new event (caller-supplied; typically the
+      preview[0] of the incoming Cluster).
+    - ``{clusters_json}`` — JSON list of candidate clusters as
+      ``[{"idx": int, "count": int, "preview": [...]}]``.
+
+Output schema (the LLM must return strictly): ``{"idx": int, "reason": str}``.
+Use ``{"idx": -1, ...}`` to signal a new cluster (sentinel; avoids null ambiguity).
+"""
+
+CLUSTER_LLM_ASSIGN_PROMPT = """You are a clustering expert. Your goal is to group similar and related tasks together so that patterns and reusable strategies can be extracted from each cluster. Assign the new task intent to an existing cluster, or signal a new cluster if no existing cluster fits.
+
+[How to decide]
+The goal of clustering is to group cases that would produce a **specific, actionable skill** — not generic advice. Use this test: "Would an agent who solved one task in this cluster have a **concrete advantage** (reusable tools, domain knowledge, verified strategies) when facing the other tasks?"
+
+1. **Identify two dimensions**: the task's **subject domain** (e.g., medical research, urban planning, e-commerce) and its **problem-solving pattern** (e.g., root cause analysis, constraint satisfaction, data pipeline design).
+2. **Cluster by the more specific dimension**. If the domain is already narrow (e.g., "clinical trial data extraction"), domain alone is enough. If the domain is broad (e.g., "software engineering"), use the problem-solving pattern to differentiate (e.g., "performance profiling" vs. "schema migration").
+3. **Do NOT merge across unrelated domains just because the strategy is similar.** "Diagnose a patient's symptoms via differential diagnosis" and "diagnose a supply chain bottleneck via constraint analysis" both use diagnostic reasoning, but involve completely different domain knowledge and belong in separate clusters.
+4. Scan candidate clusters. Prefer the cluster whose existing items would **benefit most from sharing a skill** with the new task.
+5. Signal a new cluster (idx: -1) only when no candidate cluster is a good fit.
+
+[Candidate Clusters]
+Each cluster is represented by its list index (idx), item count, and recent preview texts.
+{clusters_json}
+
+[New Task Intent]
+{memcell_text}
+
+[Rules]
+- Output decision as JSON. Keep "reason" under 50 tokens.
+- To assign to an existing cluster: use its idx (non-negative integer).
+- To create a new cluster: use idx -1.
+
+Return ONLY valid JSON (no markdown fences, no explanation):
+{{"idx": <existing_idx or -1>, "reason": "short reason"}}
+"""

everalgo_clustering-0.1.0/src/everalgo/clustering/prompts/zh/__init__.py

@@ -0,0 +1 @@
+"""Chinese clustering prompts."""

everalgo_clustering-0.1.0/src/everalgo/clustering/prompts/zh/cluster.py

@@ -0,0 +1,10 @@
+"""Chinese clustering prompts — re-export of the English template.
+
+The clustering LLM template is language-neutral: responses match the candidate corpus' language while
+the template itself works either way. This module re-exports the English constant so callers that
+import from ``prompts/zh/`` get the same prompt without duplication.
+"""
+
+from everalgo.clustering.prompts.en.cluster import CLUSTER_LLM_ASSIGN_PROMPT
+
+__all__ = ["CLUSTER_LLM_ASSIGN_PROMPT"]

everalgo_clustering-0.1.0/src/everalgo/clustering/state.py

@@ -0,0 +1,31 @@
+"""Cluster value object — frozen Pydantic model; caller persists list[Cluster] across calls.
+
+Each Cluster carries its own centroid/count/last_ts/preview. The clustering operators treat an
+incoming item as a size-1 Cluster (BIRCH CF-tree N=1 equivalence), so input and existing
+elements share one type.
+"""
+
+from __future__ import annotations
+
+import numpy as np  # noqa: TC002 — np.ndarray is a Pydantic field type; Pydantic resolves it at runtime
+from pydantic import BaseModel, ConfigDict
+
+
+class Cluster(BaseModel):
+    """Frozen value object representing one cluster snapshot.
+
+    ``members`` carries caller-supplied entity ids; the algorithm appends them on merge but never
+    inspects their semantics.
+
+    For an incoming item, build a size-1 Cluster (count=1 default; preview=[item_text] when
+    cluster_by_llm will be called).
+    """
+
+    id: str | None = None  # caller-supplied business id; algo only passes it through, never mints
+    centroid: np.ndarray
+    count: int = 1
+    last_ts: int  # ms epoch
+    preview: list[str] = []
+    members: list[str] = []  # caller-supplied entity ids (e.g. MemCell.id); algo appends on merge, no cap
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)

everalgo_clustering-0.1.0/tests/clustering/test_clustering_geometry.py

@@ -0,0 +1,154 @@
+"""Behaviour tests for :func:`everalgo.clustering.cluster_by_geometry`."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from everalgo.clustering import Cluster, cluster_by_geometry
+
+_BASE_TS_MS = 1_700_000_000_000  # 2023-11-14, far enough from epoch to be realistic.
+_DAY_MS = 86_400_000
+
+
+def _c(vec: list[float], ts: int = _BASE_TS_MS, count: int = 1, cid: str | None = None) -> Cluster:
+    return Cluster(centroid=np.array(vec, dtype=np.float32), last_ts=ts, count=count, id=cid)
+
+
+async def test_empty_existing_returns_none() -> None:
+    new_c = _c([1.0, 0.0])
+
+    result = await cluster_by_geometry(new_c, [])
+
+    assert result is None
+
+
+async def test_above_threshold_returns_merged_cluster() -> None:
+    existing = [_c([1.0, 0.0], cid="cid_0")]
+    # cosine([0.99, 0.01], [1,0]) ≈ 0.9999 > 0.65 threshold.
+    new_c = _c([0.99, 0.01], ts=_BASE_TS_MS + 1000)
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is not None
+    assert result.id == "cid_0"
+    assert result.count == 2
+    assert result.last_ts == _BASE_TS_MS + 1000
+
+
+async def test_below_threshold_returns_none() -> None:
+    existing = [_c([1.0, 0.0])]
+    # cosine([1,0], [0,1]) = 0 < 0.65 threshold → new cluster.
+    new_c = _c([0.0, 1.0], ts=_BASE_TS_MS + 1000)
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is None
+
+
+async def test_time_window_excludes_old_clusters() -> None:
+    old_ts = _BASE_TS_MS - 10 * _DAY_MS  # 10 days ago > 7-day window.
+    existing = [_c([1.0, 0.0], ts=old_ts)]
+    # Cosine match would be perfect, but time window kicks the candidate out → new cluster.
+    new_c = _c([1.0, 0.0])
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is None
+
+
+async def test_centroid_merges_via_weighted_average() -> None:
+    # count=2, centroid=[1.0, 0.0]. New vector [0.95, 0.05] → weighted avg.
+    existing = [_c([1.0, 0.0], count=2)]
+    new_vec = np.array([0.95, 0.05], dtype=np.float32)
+    new_c = Cluster(centroid=new_vec, last_ts=_BASE_TS_MS, count=1)
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is not None
+    expected = (np.array([1.0, 0.0], dtype=np.float32) * 2 + new_vec) / 3
+    np.testing.assert_allclose(result.centroid, expected, rtol=1e-5)
+    assert result.count == 3
+
+
+async def test_existing_unchanged_after_call() -> None:
+    existing = [_c([1.0, 0.0])]
+    original_centroid = existing[0].centroid.copy()
+    new_c = _c([0.99, 0.01], ts=_BASE_TS_MS + 1)
+
+    await cluster_by_geometry(new_c, existing)
+
+    # existing list itself and Cluster inside must be unchanged (frozen).
+    np.testing.assert_array_equal(existing[0].centroid, original_centroid)
+    assert existing[0].count == 1
+
+
+async def test_last_ts_uses_max() -> None:
+    # Existing ts is newer; merge should keep the larger of the two.
+    later_ts = _BASE_TS_MS + 5_000
+    existing = [_c([1.0, 0.0], ts=later_ts)]
+    new_c = _c([0.99, 0.01], ts=_BASE_TS_MS)  # older timestamp
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is not None
+    assert result.last_ts == later_ts
+
+
+async def test_preview_is_merged_and_capped() -> None:
+    existing = [Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=_BASE_TS_MS, count=1, preview=["old"])]
+    new_c = Cluster(
+        centroid=np.array([0.99, 0.01], dtype=np.float32), last_ts=_BASE_TS_MS + 1, count=1, preview=["new"]
+    )
+
+    result = await cluster_by_geometry(new_c, existing, preview_cap=5)
+
+    assert result is not None
+    assert result.preview == ["old", "new"]
+
+
+async def test_pick_best_among_multiple_existing() -> None:
+    existing = [
+        _c([1.0, 0.0], cid="cid_0"),  # cosine([0.9, 0.1], ...) ≈ 0.994
+        _c([0.0, 1.0], cid="cid_1"),  # cosine([0.9, 0.1], ...) ≈ 0.099
+    ]
+    new_c = _c([0.9, 0.1], ts=_BASE_TS_MS + 1)
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is not None
+    assert result.id == "cid_0"  # best match
+    assert result.count == 2
+
+
+async def test_merge_appends_members() -> None:
+    existing = [
+        Cluster(
+            centroid=np.array([1.0, 0.0], dtype=np.float32),
+            last_ts=_BASE_TS_MS,
+            members=["a", "b"],
+        )
+    ]
+    new_c = Cluster(
+        centroid=np.array([0.99, 0.01], dtype=np.float32),
+        last_ts=_BASE_TS_MS + 1,
+        members=["c"],
+    )
+
+    result = await cluster_by_geometry(new_c, existing)
+
+    assert result is not None
+    assert result.members == ["a", "b", "c"]
+
+
+async def test_none_path_preserves_new_members() -> None:
+    # No existing clusters → None returned; caller uses new_c as-is with its members intact.
+    new_c = Cluster(
+        centroid=np.array([1.0, 0.0], dtype=np.float32),
+        last_ts=_BASE_TS_MS,
+        members=["entity_x"],
+    )
+
+    result = await cluster_by_geometry(new_c, [])
+
+    assert result is None
+    assert new_c.members == ["entity_x"]

everalgo_clustering-0.1.0/tests/clustering/test_clustering_llm.py

@@ -0,0 +1,235 @@
+"""Behaviour tests for :func:`everalgo.clustering.cluster_by_llm`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pytest
+
+from everalgo.clustering import Cluster, cluster_by_llm
+from everalgo.llm.types import ChatMessage, ChatResponse
+from everalgo.testing.fake_llm import FakeLLMClient
+
+_BASE_TS_MS = 1_700_000_000_000
+
+
+def _c(vec: list[float], ts: int = _BASE_TS_MS, count: int = 1, preview: list[str] | None = None) -> Cluster:
+    return Cluster(centroid=np.array(vec, dtype=np.float32), last_ts=ts, count=count, preview=preview or [])
+
+
+def _two_clusters() -> list[Cluster]:
+    return [
+        _c([1.0, 0.0], count=3),
+        _c([0.0, 1.0], count=2),
+    ]
+
+
+async def test_empty_existing_skips_llm_and_returns_none() -> None:
+    new_c = _c([1.0, 0.0])
+    llm = FakeLLMClient(responses=[])
+
+    result = await cluster_by_llm(new_c, [], llm=llm)
+
+    assert result is None
+    assert llm.call_count == 0
+
+
+async def test_fast_path_top1_above_skip_threshold_skips_llm() -> None:
+    existing = _two_clusters()
+    # cosine([0.999, 0.001], [1,0]) ≈ 0.9999 > 0.85 skip threshold.
+    new_c = _c([0.999, 0.001])
+    llm = FakeLLMClient(responses=[])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert result is not None
+    assert result.count == 4
+    assert llm.call_count == 0
+
+
+async def test_llm_called_when_top1_below_skip_threshold() -> None:
+    existing = _two_clusters()
+    # cosine([0.7, 0.7], [1,0]) ≈ 0.707 — below 0.85 skip.
+    new_c = _c([0.7, 0.7], preview=["ambiguous task"])
+    llm = FakeLLMClient(responses=['{"idx": 1, "reason": "matches case bucket"}'])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert llm.call_count == 1
+    assert result is not None
+    assert result.count == 3  # LLM's choice (existing[1], count=2) + new
+
+
+async def test_llm_returns_minus_one_creates_new() -> None:
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7], preview=["novel task"])
+    llm = FakeLLMClient(responses=['{"idx": -1, "reason": "new domain"}'])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert result is None
+
+
+async def test_llm_returns_out_of_range_idx_creates_new() -> None:
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7])
+    llm = FakeLLMClient(responses=['{"idx": 999, "reason": "new domain"}'])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert result is None
+
+
+async def test_bad_llm_response_raises_value_error() -> None:
+    """Non-JSON response from LLM → ValueError propagates (no retry, no fallback)."""
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7])
+    llm = FakeLLMClient(responses=["not json"])
+
+    with pytest.raises(ValueError):
+        await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert llm.call_count == 1
+
+
+async def test_llm_missing_idx_field_raises_value_error() -> None:
+    """Valid JSON but missing 'idx' field → ValueError propagates (no fallback)."""
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7])
+    llm = FakeLLMClient(responses=['{"reason": "x"}'])
+
+    with pytest.raises(ValueError, match="missing 'idx' field"):
+        await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert llm.call_count == 1
+
+
+async def test_llm_clusters_json_contains_idx_count_preview() -> None:
+    existing = [
+        _c([1.0, 0.0], count=3, preview=["fix login bug"]),
+        _c([0.0, 1.0], count=2, preview=["refactor auth"]),
+    ]
+    new_c = _c([0.7, 0.7], preview=["investigate token leak"])
+    captured: dict[str, str] = {}
+
+    def handler(messages: list[ChatMessage], **_kwargs: Any) -> ChatResponse:
+        assert isinstance(messages[0].content, str)  # narrow for test
+        captured["prompt"] = messages[0].content
+        return ChatResponse(
+            content='{"idx": 0, "reason": "test"}',
+            model="fake",
+            usage=None,
+            finish_reason="stop",
+            raw=None,
+        )
+
+    llm = FakeLLMClient(handler=handler)
+
+    await cluster_by_llm(new_c, existing, llm=llm)
+
+    rendered = captured["prompt"]
+    assert "investigate token leak" in rendered
+    assert "fix login bug" in rendered
+    assert "refactor auth" in rendered
+    assert '"count": 3' in rendered
+    assert '"idx": 0' in rendered
+
+
+async def test_caller_supplied_prompt_overrides_default() -> None:
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7], preview=["hello"])
+    custom = "OVERRIDE memcell={memcell_text} clusters={clusters_json}"
+    captured: dict[str, str] = {}
+
+    def handler(messages: list[ChatMessage], **_kwargs: Any) -> ChatResponse:
+        assert isinstance(messages[0].content, str)  # narrow for test
+        captured["prompt"] = messages[0].content
+        return ChatResponse(
+            content='{"idx": 0, "reason": "ok"}',
+            model="fake",
+            usage=None,
+            finish_reason="stop",
+            raw=None,
+        )
+
+    llm = FakeLLMClient(handler=handler)
+
+    await cluster_by_llm(new_c, existing, llm=llm, prompt=custom)
+
+    assert captured["prompt"].startswith("OVERRIDE memcell=hello")
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        '```json\n{"idx": 0, "reason": "fence-wrapped"}\n```',
+    ],
+)
+async def test_llm_response_with_json_fence_is_parsed(raw: str) -> None:
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7])
+    llm = FakeLLMClient(responses=[raw])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert result is not None
+    assert llm.call_count == 1
+
+
+async def test_preview_empty_when_new_cluster_has_no_preview() -> None:
+    """When new_cluster.preview is empty, query_text is '' and prompt still renders."""
+    existing = _two_clusters()
+    new_c = _c([0.7, 0.7])  # no preview
+    captured: dict[str, str] = {}
+
+    def handler(messages: list[ChatMessage], **_kwargs: Any) -> ChatResponse:
+        assert isinstance(messages[0].content, str)  # narrow for test
+        captured["prompt"] = messages[0].content
+        return ChatResponse(
+            content='{"idx": 0, "reason": "ok"}', model="fake", usage=None, finish_reason="stop", raw=None
+        )
+
+    llm = FakeLLMClient(handler=handler)
+    await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert "idx" in captured["prompt"]  # prompt rendered without error
+
+
+async def test_merge_appends_members_via_llm_path() -> None:
+    existing = [
+        Cluster(
+            centroid=np.array([1.0, 0.0], dtype=np.float32),
+            last_ts=_BASE_TS_MS,
+            count=2,
+            members=["a", "b"],
+        )
+    ]
+    new_c = Cluster(
+        centroid=np.array([0.999, 0.001], dtype=np.float32),
+        last_ts=_BASE_TS_MS + 1,
+        members=["c"],
+    )
+    # cosine ~0.9999 >= 0.85 skip threshold → fast-path merge, no LLM call.
+    llm = FakeLLMClient(responses=[])
+
+    result = await cluster_by_llm(new_c, existing, llm=llm)
+
+    assert result is not None
+    assert result.members == ["a", "b", "c"]
+    assert llm.call_count == 0
+
+
+async def test_none_path_preserves_new_members_llm() -> None:
+    # Empty existing → None; caller keeps new_c with its members.
+    new_c = Cluster(
+        centroid=np.array([1.0, 0.0], dtype=np.float32),
+        last_ts=_BASE_TS_MS,
+        members=["entity_y"],
+    )
+    llm = FakeLLMClient(responses=[])
+
+    result = await cluster_by_llm(new_c, [], llm=llm)
+
+    assert result is None
+    assert new_c.members == ["entity_y"]

everalgo_clustering-0.1.0/tests/clustering/test_clustering_state.py

@@ -0,0 +1,46 @@
+"""Cluster value-object tests — frozen invariants + basic field access."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from pydantic import ValidationError
+
+from everalgo.clustering import Cluster
+
+
+def test_cluster_default_count_is_one() -> None:
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=1_700_000_000_000)
+    assert c.count == 1
+
+
+def test_cluster_preview_defaults_to_empty() -> None:
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=1_700_000_000_000)
+    assert c.preview == []
+
+
+def test_cluster_is_frozen_raises_on_assignment() -> None:
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=1_700_000_000_000)
+    with pytest.raises(ValidationError):
+        c.count = 99  # type: ignore[misc]
+
+
+def test_cluster_arbitrary_ndarray_allowed() -> None:
+    vec = np.array([0.1, 0.2, 0.3], dtype=np.float32)
+    c = Cluster(centroid=vec, last_ts=0)
+    np.testing.assert_array_equal(c.centroid, vec)
+
+
+def test_cluster_with_preview() -> None:
+    c = Cluster(centroid=np.array([1.0], dtype=np.float32), last_ts=0, preview=["a", "b"])
+    assert c.preview == ["a", "b"]
+
+
+def test_cluster_members_defaults_to_empty() -> None:
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=1_700_000_000_000)
+    assert c.members == []
+
+
+def test_cluster_members_roundtrip() -> None:
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=0, members=["id_a", "id_b"])
+    assert c.members == ["id_a", "id_b"]

everalgo_clustering-0.1.0/tests/clustering/test_public_api.py

@@ -0,0 +1,34 @@
+"""Surface tests for ``everalgo.clustering`` public API."""
+
+from __future__ import annotations
+
+import inspect
+
+
+def test_top_level_exports() -> None:
+    from everalgo.clustering import __all__
+
+    assert sorted(__all__) == sorted(
+        [
+            "Cluster",
+            "cluster_by_geometry",
+            "cluster_by_llm",
+        ]
+    )
+
+
+def test_cluster_instantiates_with_required_fields() -> None:
+    import numpy as np
+
+    from everalgo.clustering import Cluster
+
+    c = Cluster(centroid=np.array([1.0, 0.0], dtype=np.float32), last_ts=0)
+    assert c.count == 1
+    assert c.preview == []
+
+
+def test_cluster_functions_are_async() -> None:
+    from everalgo.clustering import cluster_by_geometry, cluster_by_llm
+
+    assert inspect.iscoroutinefunction(cluster_by_geometry)
+    assert inspect.iscoroutinefunction(cluster_by_llm)