wavemind 2.0.0__py3-none-any.whl

wavemind/__init__.py

@@ -0,0 +1,22 @@
+from .core import QueryResult, WaveField, WaveMind
+from .encoders import (
+    FieldProjector,
+    HashingTextEncoder,
+    SentenceTransformerTextEncoder,
+    TextEncoder,
+    create_text_encoder,
+)
+from .storage import MemoryRecord, SQLiteMemoryStore
+
+__all__ = [
+    "FieldProjector",
+    "HashingTextEncoder",
+    "MemoryRecord",
+    "QueryResult",
+    "SentenceTransformerTextEncoder",
+    "SQLiteMemoryStore",
+    "TextEncoder",
+    "WaveField",
+    "WaveMind",
+    "create_text_encoder",
+]

wavemind/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+raise SystemExit(main())
+

wavemind/api.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import Body, FastAPI, Query
+from pydantic import BaseModel, Field
+
+from .core import WaveMind
+from .encoders import create_text_encoder
+from .importers import import_path
+
+
+logger = logging.getLogger("wavemind.api")
+
+
+class RememberRequest(BaseModel):
+    text: str
+    namespace: str = "default"
+    tags: list[str] = Field(default_factory=list)
+    ttl_seconds: float | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    priority: float = 1.0
+
+
+class RememberResponse(BaseModel):
+    id: int
+
+
+class QueryRequest(BaseModel):
+    text: str
+    namespace: str = "default"
+    top_k: int = 3
+    tags: list[str] = Field(default_factory=list)
+    min_score: float | None = None
+
+
+class QueryResultResponse(BaseModel):
+    id: int
+    text: str
+    score: float
+    vector_score: float
+    field_score: float
+    namespace: str
+    tags: list[str]
+    metadata: dict[str, Any]
+
+
+class QueryResponse(BaseModel):
+    results: list[QueryResultResponse]
+
+
+class ForgetRequest(BaseModel):
+    id: int | None = None
+    text: str | None = None
+    namespace: str | None = None
+
+
+class ForgetResponse(BaseModel):
+    deleted: int
+
+
+class ImportRequest(BaseModel):
+    path: str
+    namespace: str = "default"
+    tags: list[str] = Field(default_factory=list)
+    max_chars: int = 1000
+    overlap: int = 120
+
+
+class ImportResponse(BaseModel):
+    ids: list[int]
+
+
+def build_default_mind() -> WaveMind:
+    db_path = (
+        Path(os.environ["WAVEMIND_DB"])
+        if "WAVEMIND_DB" in os.environ
+        else Path.cwd() / "wavemind.sqlite3"
+    )
+    index_kind = os.environ.get("WAVEMIND_INDEX", "numpy")
+    encoder_kind = os.environ.get("WAVEMIND_ENCODER", "hash").lower()
+    score_threshold = float(os.environ.get("WAVEMIND_SCORE_THRESHOLD", "0.0"))
+    encoder = create_text_encoder(
+        kind=encoder_kind,
+        vector_dim=int(os.environ.get("WAVEMIND_VECTOR_DIM", "384")),
+        model_name=os.environ.get(
+            "WAVEMIND_MODEL",
+            "sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
+        ),
+    )
+    return WaveMind(
+        db_path=db_path,
+        encoder=encoder,
+        index_kind=index_kind,
+        score_threshold=score_threshold,
+    )
+
+
+def create_app(mind: WaveMind | None = None) -> FastAPI:
+    logging.basicConfig(level=os.environ.get("WAVEMIND_LOG_LEVEL", "INFO"))
+    app = FastAPI(title="WaveMind", version="2.0.0")
+    app.state.mind = mind or build_default_mind()
+
+    @app.post("/remember", response_model=RememberResponse)
+    def remember(request: RememberRequest) -> RememberResponse:
+        id = app.state.mind.remember(
+            request.text,
+            namespace=request.namespace,
+            tags=request.tags,
+            ttl_seconds=request.ttl_seconds,
+            metadata=request.metadata,
+            priority=request.priority,
+        )
+        logger.info("remembered id=%s namespace=%s", id, request.namespace)
+        return RememberResponse(id=id)
+
+    @app.post("/query", response_model=QueryResponse)
+    def query(request: QueryRequest) -> QueryResponse:
+        results = app.state.mind.query(
+            request.text,
+            namespace=request.namespace,
+            top_k=request.top_k,
+            tags=request.tags,
+            min_score=request.min_score,
+        )
+        return QueryResponse(
+            results=[
+                QueryResultResponse(
+                    id=result.id,
+                    text=result.text,
+                    score=result.score,
+                    vector_score=result.vector_score,
+                    field_score=result.field_score,
+                    namespace=result.namespace,
+                    tags=list(result.tags),
+                    metadata=result.metadata,
+                )
+                for result in results
+            ]
+        )
+
+    @app.delete("/forget", response_model=ForgetResponse)
+    def forget(
+        request: ForgetRequest | None = Body(default=None),
+        id: int | None = Query(default=None),
+        text: str | None = Query(default=None),
+        namespace: str | None = Query(default=None),
+    ) -> ForgetResponse:
+        payload = request or ForgetRequest(id=id, text=text, namespace=namespace)
+        deleted = app.state.mind.forget(
+            id=payload.id,
+            text=payload.text,
+            namespace=payload.namespace,
+        )
+        logger.info("forgot deleted=%s namespace=%s", deleted, payload.namespace)
+        return ForgetResponse(deleted=deleted)
+
+    @app.get("/stats")
+    def stats(namespace: str | None = None):
+        return app.state.mind.stats(namespace=namespace)
+
+    @app.post("/import", response_model=ImportResponse)
+    def batch_import(request: ImportRequest) -> ImportResponse:
+        ids = import_path(
+            request.path,
+            app.state.mind,
+            namespace=request.namespace,
+            tags=request.tags,
+            max_chars=request.max_chars,
+            overlap=request.overlap,
+        )
+        return ImportResponse(ids=ids)
+
+    return app

wavemind/benchmark.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import statistics
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class BenchmarkCase:
+    query: str
+    expected_text: str
+    namespace: str = "default"
+    tags: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class BenchmarkReport:
+    precision_at_k: float
+    recall_at_k: float
+    avg_latency_ms: float
+    p95_latency_ms: float
+    capacity: int
+    cases: int
+    misses: list[str] = field(default_factory=list)
+
+
+def run_benchmark(mind, cases: list[BenchmarkCase], k: int = 3) -> BenchmarkReport:
+    if not cases:
+        return BenchmarkReport(0.0, 0.0, 0.0, 0.0, mind.stats()["active_memories"], 0, [])
+
+    hits = 0
+    precision_terms = []
+    latencies = []
+    misses = []
+    for case in cases:
+        started = time.perf_counter()
+        results = mind.query(case.query, namespace=case.namespace, tags=case.tags, top_k=k)
+        latencies.append((time.perf_counter() - started) * 1000.0)
+        texts = [result.text for result in results]
+        if case.expected_text in texts:
+            hits += 1
+            precision_terms.append(1.0 / max(1, len(texts)))
+        else:
+            precision_terms.append(0.0)
+            misses.append(case.query)
+
+    sorted_latencies = sorted(latencies)
+    p95_index = min(len(sorted_latencies) - 1, int(len(sorted_latencies) * 0.95))
+    return BenchmarkReport(
+        precision_at_k=sum(precision_terms) / len(precision_terms),
+        recall_at_k=hits / len(cases),
+        avg_latency_ms=statistics.mean(latencies),
+        p95_latency_ms=sorted_latencies[p95_index],
+        capacity=mind.stats()["active_memories"],
+        cases=len(cases),
+        misses=misses,
+    )
+
+
+def synthetic_cases(namespace: str = "bench") -> list[tuple[str, str]]:
+    return [
+        ("кошка", "кошка сидит на подоконнике"),
+        ("собака", "собака лает во дворе"),
+        ("market breakout", "market breakout above resistance"),
+        ("agent recall", "agent memory recall improves answers"),
+    ]
+

wavemind/cli.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .benchmark import BenchmarkCase, run_benchmark, synthetic_cases
+from .core import WaveMind
+from .encoders import create_text_encoder
+from .importers import import_path
+
+
+def configure_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wavemind",
+        description="WaveMind persistent dynamic memory engine",
+    )
+    parser.add_argument("--db", default=None, help="SQLite database path")
+    parser.add_argument("--index", default="numpy", choices=["numpy", "faiss", "annoy"])
+    parser.add_argument("--encoder", default="hash", choices=["hash", "sentence"])
+    parser.add_argument(
+        "--model",
+        default="sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
+        help="sentence-transformers model name when --encoder sentence is used",
+    )
+    parser.add_argument("--score-threshold", type=float, default=0.0)
+    parser.add_argument("--width", type=int, default=128)
+    parser.add_argument("--height", type=int, default=128)
+    parser.add_argument("--layers", type=int, default=6)
+
+    sub = parser.add_subparsers(dest="command")
+
+    remember = sub.add_parser("remember", help="Store a memory")
+    remember.add_argument("text")
+    remember.add_argument("--namespace", default="default")
+    remember.add_argument("--tag", action="append", default=[])
+    remember.add_argument("--ttl-seconds", type=float)
+    remember.add_argument("--priority", type=float, default=1.0)
+
+    query = sub.add_parser("query", help="Query memories")
+    query.add_argument("text")
+    query.add_argument("--namespace", default="default")
+    query.add_argument("--tag", action="append", default=[])
+    query.add_argument("--top-k", type=int, default=3)
+    query.add_argument("--min-score", type=float)
+    query.add_argument("--json", action="store_true")
+
+    forget = sub.add_parser("forget", help="Delete a memory")
+    forget.add_argument("--id", type=int)
+    forget.add_argument("--text")
+    forget.add_argument("--namespace")
+
+    stats = sub.add_parser("stats", help="Show memory stats")
+    stats.add_argument("--namespace")
+
+    imp = sub.add_parser("import", help="Import txt/pdf/json")
+    imp.add_argument("path")
+    imp.add_argument("--namespace", default="default")
+    imp.add_argument("--tag", action="append", default=[])
+    imp.add_argument("--max-chars", type=int, default=1000)
+    imp.add_argument("--overlap", type=int, default=120)
+
+    backup = sub.add_parser("backup", help="Backup SQLite database")
+    backup.add_argument("--out", required=True)
+
+    bench = sub.add_parser("benchmark", help="Run a synthetic recall benchmark")
+    bench.add_argument("--namespace", default="bench")
+    bench.add_argument("--top-k", type=int, default=1)
+
+    serve = sub.add_parser("serve", help="Run FastAPI daemon")
+    serve.add_argument("--host", default="0.0.0.0")
+    serve.add_argument("--port", type=int, default=8000)
+
+    sub.add_parser("test", help="Run pytest suite")
+    return parser
+
+
+def make_mind(args) -> WaveMind:
+    encoder = create_text_encoder(kind=args.encoder, vector_dim=384, model_name=args.model)
+    db_path = Path(args.db) if args.db else Path.cwd() / "wavemind.sqlite3"
+    return WaveMind(
+        db_path=db_path,
+        width=args.width,
+        height=args.height,
+        layers=args.layers,
+        encoder=encoder,
+        index_kind=args.index,
+        score_threshold=args.score_threshold,
+    )
+
+
+def print_stats(stats: dict) -> None:
+    for key, value in stats.items():
+        print(f"{key}: {value}")
+
+
+def run_interactive(args) -> int:
+    mind = make_mind(args)
+    print("WaveMind v2 interactive CLI. Type help or exit.")
+    while True:
+        try:
+            line = input("> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nexit")
+            return 0
+        if not line:
+            continue
+        if line in {"exit", "quit"}:
+            print("exit")
+            return 0
+        if line == "help":
+            print("remember <text> | query <text> | query5 <text> | stats | list | exit")
+            continue
+        command, _, rest = line.partition(" ")
+        if command == "remember" and rest:
+            id = mind.remember(rest)
+            print(f"remembered id={id}")
+        elif command == "query" and rest:
+            for result in mind.query(rest, top_k=3):
+                print(f"{result.score:.4f} id={result.id} {result.text}")
+        elif command == "query5" and rest:
+            for result in mind.query(rest, top_k=5):
+                print(f"{result.score:.4f} id={result.id} {result.text}")
+        elif command == "stats":
+            print_stats(mind.stats())
+        elif command == "list":
+            for record in mind.store.list(include_expired=False):
+                print(f"{record.id}: [{record.namespace}] {record.text}")
+        else:
+            print("unknown command")
+
+
+def main(argv: list[str] | None = None) -> int:
+    configure_stdio()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        if argv is not None:
+            parser.print_help()
+            return 0
+        return run_interactive(args)
+
+    if args.command == "test":
+        import pytest
+
+        return int(pytest.main(["-q"]))
+
+    if args.command == "serve":
+        import uvicorn
+
+        from .api import create_app
+
+        uvicorn.run(create_app(mind=make_mind(args)), host=args.host, port=args.port)
+        return 0
+
+    mind = make_mind(args)
+    if args.command == "remember":
+        id = mind.remember(
+            args.text,
+            namespace=args.namespace,
+            tags=args.tag,
+            ttl_seconds=args.ttl_seconds,
+            priority=args.priority,
+        )
+        print(f"remembered id={id}")
+        return 0
+
+    if args.command == "query":
+        results = mind.query(
+            args.text,
+            namespace=args.namespace,
+            tags=args.tag,
+            top_k=args.top_k,
+            min_score=args.min_score,
+        )
+        if args.json:
+            print(json.dumps([result.__dict__ for result in results], ensure_ascii=False, indent=2))
+        else:
+            for result in results:
+                print(
+                    f"{result.score:.4f} "
+                    f"vector={result.vector_score:.4f} "
+                    f"field={result.field_score:.4f} "
+                    f"id={result.id} {result.text}"
+                )
+        return 0
+
+    if args.command == "forget":
+        print(f"deleted={mind.forget(id=args.id, text=args.text, namespace=args.namespace)}")
+        return 0
+
+    if args.command == "stats":
+        print_stats(mind.stats(namespace=args.namespace))
+        return 0
+
+    if args.command == "import":
+        ids = import_path(
+            args.path,
+            mind,
+            namespace=args.namespace,
+            tags=args.tag,
+            max_chars=args.max_chars,
+            overlap=args.overlap,
+        )
+        print(f"imported={len(ids)} ids={','.join(str(id) for id in ids)}")
+        return 0
+
+    if args.command == "backup":
+        path = mind.save(args.out)
+        print(f"backup: {path}")
+        return 0
+
+    if args.command == "benchmark":
+        existing = {
+            record.text
+            for record in mind.store.list(namespace=args.namespace, include_expired=False)
+        }
+        for query, text in synthetic_cases(namespace=args.namespace):
+            if text not in existing:
+                mind.remember(text, namespace=args.namespace)
+                existing.add(text)
+        cases = [
+            BenchmarkCase(query=query, expected_text=text, namespace=args.namespace)
+            for query, text in synthetic_cases(namespace=args.namespace)
+        ]
+        report = run_benchmark(mind, cases, k=args.top_k)
+        print(json.dumps(report.__dict__, ensure_ascii=False, indent=2))
+        return 0
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())