phorvec 0.1.2__cp38-abi3-win_amd64.whl

phorvec/__init__.py

@@ -0,0 +1,135 @@
+"""phorvec — persistent vector memory for AI agents (Python bindings).
+
+The low-level engine (`Engine`) exposes every phorvec tool via
+`Engine.call(name, params_json)`. On top of it, each feature family gets an
+ergonomic wrapper class:
+
+- `Memory` / `Recall` — durable agent memory (+ core-memory admin: pin, forget,
+  rewrite, prioritize, consolidate, export/import, gc, list, promote)
+- `Team`                — multi-agent teams (paid tier)
+- `Graph`               — knowledge graph (entities, links, queries, stats)
+- `Facts`               — temporal facts (supersede/invalidate/reactivate/history)
+- `Skills`              — skill library (ingest/search/get/list/sync)
+- `Rag`                 — retrieval over indexed files/directories
+- `MemoryBlocks`        — shared, token-budgeted memory blocks
+- `Context`             — working-context store/retrieve + lifecycle ops
+- `Snapshots`           — context snapshots (save/restore/list/delete)
+- `Branches`            — context branches (create/switch/merge/…)
+- `Watches`             — semantic context watches
+- `Agents`              — agent versioning, diff/rollback, export/import, templates
+- `Chat`                — chat session search/resume
+- `Projects` / `Outcomes` — project lifecycle + outcome tracking
+- `Maintenance` / `Quantization` — buffer/cache/GC ops + vector quantization
+- `Analytics` / `Security` / `Anchors` / `Export` — analytics/metrics, PII scan,
+  anchors, obsidian export
+
+Every wrapper except `Memory` BORROWS an externally-created `Engine` and does
+not own its lifecycle — construct one `Engine` (or a `Memory`) and layer the
+others on top of the same handle.
+"""
+from ._phorvec import (
+    Engine,
+    PhorvecError,
+    TierRequiredError,
+    UnknownToolError,
+    run_cli,
+)
+from .memory import Memory, Recall
+from .team import Team
+from .graph import Graph, Entity, GraphStats
+from .facts import Facts, FactHistory, FactCurrentFact, FactEntry
+from .skills import Skills, SkillEntry, SkillDetail, SkillHit
+from .rag import Rag, RagHit
+from .memory_blocks import MemoryBlocks, Block, BlockListResult
+from .context import Context, StoreResult, RetrieveHit, TokenCount
+from .snapshots import Snapshots, SnapshotInfo
+from .branches import Branches, BranchInfo
+from .watches import Watches, Watch, WatchInfo
+from .agents import (
+    Agents,
+    VersionEntry,
+    AgentHistory,
+    DiffResult,
+    DiffStats,
+    Template,
+    TemplateVariable,
+)
+from .chat import Chat, SearchHit, SearchSession, Session, Turn, ResumeResult
+from .projects import Projects, Outcomes, ProjectInfo, OutcomeEntry
+from .maintenance import Maintenance, Quantization, BufferStatus
+from .admin import (
+    Analytics,
+    Security,
+    Anchors,
+    Export,
+    DetectedSecret,
+    ScanResult,
+    Anchor,
+)
+
+__all__ = [
+    # core
+    "Engine",
+    "PhorvecError",
+    "TierRequiredError",
+    "UnknownToolError",
+    "run_cli",
+    # wrapper classes
+    "Memory",
+    "Recall",
+    "Team",
+    "Graph",
+    "Entity",
+    "GraphStats",
+    "Facts",
+    "FactHistory",
+    "FactCurrentFact",
+    "FactEntry",
+    "Skills",
+    "SkillEntry",
+    "SkillDetail",
+    "SkillHit",
+    "Rag",
+    "RagHit",
+    "MemoryBlocks",
+    "Block",
+    "BlockListResult",
+    "Context",
+    "StoreResult",
+    "RetrieveHit",
+    "TokenCount",
+    "Snapshots",
+    "SnapshotInfo",
+    "Branches",
+    "BranchInfo",
+    "Watches",
+    "Watch",
+    "WatchInfo",
+    "Agents",
+    "VersionEntry",
+    "AgentHistory",
+    "DiffResult",
+    "DiffStats",
+    "Template",
+    "TemplateVariable",
+    "Chat",
+    "SearchHit",
+    "SearchSession",
+    "Session",
+    "Turn",
+    "ResumeResult",
+    "Projects",
+    "Outcomes",
+    "ProjectInfo",
+    "OutcomeEntry",
+    "Maintenance",
+    "Quantization",
+    "BufferStatus",
+    "Analytics",
+    "Security",
+    "Anchors",
+    "Export",
+    "DetectedSecret",
+    "ScanResult",
+    "Anchor",
+]

phorvec/_cli.py

@@ -0,0 +1,7 @@
+"""Console-script entry: `phorvec ...` -> the Rust CLI via the extension."""
+import sys
+from ._phorvec import run_cli
+
+
+def main() -> None:
+    raise SystemExit(run_cli(sys.argv))

phorvec/admin.py

@@ -0,0 +1,281 @@
+"""Admin tools for analytics, security scanning, anchor management, and vault export.
+
+Wraps four singleton tool families: `analytics`/`metrics` (Analytics class),
+`security_scan` (Security class), `anchor_manage` (Anchors class), and
+`obsidian_export` (Export class). All four classes borrow an externally-created
+Engine and do NOT own it — the caller controls the Engine lifecycle.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from ._phorvec import Engine
+
+
+# ============================================================================
+# Analytics — wraps `analytics` and `metrics` tools
+# ============================================================================
+
+class Analytics:
+    """Conversation analytics and token-savings metrics for a phorvec store.
+
+    `Analytics` BORROWS an externally-created `Engine` and does NOT own it,
+    so it has no `close()`/context-manager — the caller owns the Engine.
+    """
+
+    def __init__(self, engine: Engine, *, project: Optional[str] = None):
+        self._engine = engine
+        self._project = project
+
+    def _call(self, tool: str, params: dict) -> Any:
+        return json.loads(self._engine.call(tool, json.dumps(params)))
+
+    def query(
+        self,
+        *,
+        time_range: Optional[str] = None,
+        format: str = "json",
+        breakdown: Optional[bool] = None,
+        project: Optional[str] = None,
+    ) -> Any:
+        """Query conversation analytics (session stats, tool usage, topics, ROI).
+
+        Returns a dict when format='json' (default) or a str when format='human'.
+        time_range ∈ {'today','this_week','this_month','all_time'} (default: all_time).
+        breakdown=True gives a per-project breakdown instead of a single summary.
+        """
+        p = project or self._project
+        params: dict[str, Any] = {"format": format}
+        if p is not None:
+            params["project"] = p
+        if time_range is not None:
+            params["time_range"] = time_range
+        if breakdown is not None:
+            params["breakdown"] = breakdown
+        raw = self._engine.call("analytics", json.dumps(params))
+        return json.loads(raw) if format == "json" else raw
+
+    def get(
+        self,
+        *,
+        format: str = "json",
+        project: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> Any:
+        """Get token-savings metrics (cumulative, per-project, daily history).
+
+        Returns a dict when format='json' (default) or a str when format='human'.
+        Optionally filter by project and/or date range (YYYY-MM-DD strings).
+        """
+        p = project or self._project
+        params: dict[str, Any] = {"format": format}
+        if p is not None:
+            params["project"] = p
+        if start_date is not None:
+            params["start_date"] = start_date
+        if end_date is not None:
+            params["end_date"] = end_date
+        raw = self._engine.call("metrics", json.dumps(params))
+        return json.loads(raw) if format == "json" else raw
+
+
+# ============================================================================
+# Security — wraps `security_scan` tool
+# ============================================================================
+
+@dataclass
+class DetectedSecret:
+    """One secret detected during a `security_scan`."""
+    type: str
+    start: int
+    end: int
+
+
+@dataclass
+class ScanResult:
+    """Full result of a `security_scan` call."""
+    secrets_found: int
+    action_taken: str
+    policy: str
+    clean_content: str
+    detected_secrets: list = field(default_factory=list)
+
+
+class Security:
+    """Secret-scanning tool wrapper. Borrows an externally-created Engine."""
+
+    def __init__(self, engine: Engine):
+        self._engine = engine
+
+    def _call(self, tool: str, params: dict) -> Any:
+        return json.loads(self._engine.call(tool, json.dumps(params)))
+
+    def scan(self, content: str) -> ScanResult:
+        """Scan content for secrets (API keys, tokens, credentials) without storing it.
+
+        Requires a non-empty content string. Returns a ScanResult with all findings,
+        the action the configured security policy would take, and the redacted content.
+        Raises PhorvecError on engine errors; does NOT catch empty-content errors.
+        """
+        raw = self._call("security_scan", {"content": content})
+        secrets = [
+            DetectedSecret(type=s["type"], start=s["start"], end=s["end"])
+            for s in raw.get("detected_secrets", [])
+        ]
+        return ScanResult(
+            secrets_found=raw["secrets_found"],
+            action_taken=raw["action_taken"],
+            policy=raw["policy"],
+            clean_content=raw["clean_content"],
+            detected_secrets=secrets,
+        )
+
+
+# ============================================================================
+# Anchors — wraps `anchor_manage` tool
+# ============================================================================
+
+@dataclass
+class Anchor:
+    """One semantic anchor returned by `anchor_manage` list."""
+    id: str
+    content: str
+    created_at: int
+    source: str
+    token_count: int
+
+
+class Anchors:
+    """Manage semantic anchors — key facts that persist across context and resist pruning.
+
+    `Anchors` BORROWS an externally-created `Engine` and does NOT own it.
+    Maximum 20 anchors per project (enforced by the engine).
+    """
+
+    def __init__(self, engine: Engine, *, project: Optional[str] = None):
+        self._engine = engine
+        self._project = project
+
+    def _call(self, tool: str, params: dict) -> Any:
+        return json.loads(self._engine.call(tool, json.dumps(params)))
+
+    def _resolve_project(self, project: Optional[str]) -> str:
+        p = project or self._project
+        if p is None:
+            raise ValueError("project is required (pass project= or set it on the wrapper)")
+        return p
+
+    def manage(
+        self,
+        operation: str,
+        *,
+        content: Optional[str] = None,
+        anchor_id: Optional[str] = None,
+        project: Optional[str] = None,
+    ) -> dict:
+        """Generic anchor_manage call. Prefer the list/add/remove/update helpers.
+
+        operation ∈ {'list','add','remove','update'}.
+        content is required for add and update; anchor_id is required for remove and update.
+        Requires project (positional on wrapper, or per-call via project= kwarg).
+        """
+        p = self._resolve_project(project)
+        params: dict[str, Any] = {"project": p, "operation": operation}
+        if content is not None:
+            params["content"] = content
+        if anchor_id is not None:
+            params["anchor_id"] = anchor_id
+        return self._call("anchor_manage", params)
+
+    def list(self, *, project: Optional[str] = None) -> list:
+        """List all anchors for the project. Returns a list of Anchor objects."""
+        out = self.manage("list", project=project)
+        return [
+            Anchor(
+                id=a["id"],
+                content=a["content"],
+                created_at=a.get("created_at", 0),
+                source=a.get("source", "manual"),
+                token_count=a.get("token_count", 0),
+            )
+            for a in out.get("anchors", [])
+        ]
+
+    def add(self, content: str, *, project: Optional[str] = None) -> dict:
+        """Add a new anchor. Returns {id, content, importance, anchor_count, max_anchors}.
+
+        Requires content (non-empty string). Raises if the per-project limit (20) is reached.
+        """
+        return self.manage("add", content=content, project=project)
+
+    def remove(self, anchor_id: str, *, project: Optional[str] = None) -> dict:
+        """Remove the anchor flag from anchor_id. Returns {removed, message}.
+
+        The underlying context item remains; only the anchor designation is cleared.
+        Requires anchor_id.
+        """
+        return self.manage("remove", anchor_id=anchor_id, project=project)
+
+    def update(self, anchor_id: str, content: str, *, project: Optional[str] = None) -> dict:
+        """Update the content of an existing anchor. Returns {updated, content, message}.
+
+        Requires anchor_id (must point to an existing anchor) and new content.
+        """
+        return self.manage("update", content=content, anchor_id=anchor_id, project=project)
+
+
+# ============================================================================
+# Export — wraps `obsidian_export` tool
+# ============================================================================
+
+class Export:
+    """Obsidian vault export for phorvec projects.
+
+    `Export` BORROWS an externally-created `Engine` and does NOT own it.
+    The generated vault is a read-only projection; edits do not flow back.
+    """
+
+    def __init__(self, engine: Engine, *, project: Optional[str] = None):
+        self._engine = engine
+        self._project = project
+
+    def _call(self, tool: str, params: dict) -> Any:
+        return json.loads(self._engine.call(tool, json.dumps(params)))
+
+    def _resolve_project(self, project: Optional[str]) -> str:
+        p = project or self._project
+        if p is None:
+            raise ValueError("project is required (pass project= or set it on the wrapper)")
+        return p
+
+    def obsidian(
+        self,
+        *,
+        vault_root: Optional[str] = None,
+        force: Optional[bool] = None,
+        preserve_all: Optional[bool] = None,
+        dry_run: Optional[bool] = None,
+        project: Optional[str] = None,
+    ) -> dict:
+        """Export the project to an Obsidian markdown vault. Returns an export report dict.
+
+        Requires project. vault_root defaults to ~/phorvec/vault/<project>/.
+        force=True overwrites externally-edited vault files (you lose those edits).
+        preserve_all=True silently skips externally-edited files.
+        force and preserve_all are mutually exclusive.
+        dry_run=True previews what would happen without touching the filesystem.
+        """
+        p = self._resolve_project(project)
+        params: dict[str, Any] = {"project": p}
+        if vault_root is not None:
+            params["vault_root"] = vault_root
+        if force is not None:
+            params["force"] = force
+        if preserve_all is not None:
+            params["preserve_all"] = preserve_all
+        if dry_run is not None:
+            params["dry_run"] = dry_run
+        return self._call("obsidian_export", params)