semvec 0.1.0a2__cp310-abi3-win_amd64.whl

semvec/__init__.py

@@ -0,0 +1,82 @@
+"""Semvec — patent-pending persistent semantic state engine.
+
+The public surface is PEP-8 compliant PascalCase. Legacy PSS-prefixed
+names (``PSS_State_V4``, ``PSSConfig``, ``PSSError``) remain importable
+as deprecated aliases — accessing them raises :class:`DeprecationWarning`.
+Aliases are scheduled for removal in semvec 0.2.0.
+"""
+
+from __future__ import annotations
+
+import warnings as _warnings
+from typing import Any as _Any
+
+from semvec._core import (
+    AdaptiveParameters,
+    CodeEntity,
+    ConfigurationError,
+    EmbeddingError,
+    EmbeddingService,
+    LicenseError,
+    LicenseExpiredError,
+    LiteralCache,
+    MemoryUnit,
+    MultiResolutionMemory,
+    PhaseDetector,
+    RateLimitError,
+    SemvecConfig,
+    SemvecError,
+    SemvecState,
+    StateCorruptionError,
+    safe_cosine_similarity,
+)
+from semvec.literal_cache import EntityKind
+
+__version__ = "0.1.0a2"
+__author__ = "Michael Neuberger"
+
+__all__ = [
+    "AdaptiveParameters",
+    "CodeEntity",
+    "ConfigurationError",
+    "EmbeddingError",
+    "EmbeddingService",
+    "EntityKind",
+    "LicenseError",
+    "LicenseExpiredError",
+    "LiteralCache",
+    "MemoryUnit",
+    "MultiResolutionMemory",
+    "PhaseDetector",
+    "RateLimitError",
+    "SemvecConfig",
+    "SemvecError",
+    "SemvecState",
+    "StateCorruptionError",
+    "safe_cosine_similarity",
+]
+
+
+# ---------------------------------------------------------------------------
+# Deprecated aliases — emit a DeprecationWarning on access, resolve to the
+# current PEP-8 names. Scheduled for removal in 0.2.0.
+
+_DEPRECATED_ALIASES: dict[str, tuple[str, _Any]] = {
+    "PSS_State_V4": ("SemvecState", SemvecState),
+    "PSSConfig": ("SemvecConfig", SemvecConfig),
+    "PSSError": ("SemvecError", SemvecError),
+}
+
+
+def __getattr__(name: str) -> _Any:
+    alias = _DEPRECATED_ALIASES.get(name)
+    if alias is not None:
+        replacement_name, obj = alias
+        _warnings.warn(
+            f"{name} is deprecated and will be removed in semvec 0.2.0. "
+            f"Use {replacement_name} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    raise AttributeError(f"module 'semvec' has no attribute {name!r}")

semvec/_core.pyi

@@ -0,0 +1,415 @@
+"""Type stubs for the Rust-backed `semvec._core` extension.
+
+Covers the public surface used by typed consumers (mypy, pyright, IDE
+auto-complete). Kept at the level of published shapes — implementation
+details live in the Rust source.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping
+
+import numpy as np
+from numpy.typing import NDArray
+
+# ---------------------------------------------------------------------------
+# Core
+
+class SemvecConfig:
+    dimension: int
+    short_term_size: int
+    medium_term_size: int
+    long_term_size: int
+    history_length: int
+    model_name: str
+    device: str
+
+    def __init__(
+        self,
+        dimension: int = 384,
+        short_term_size: int = 20,
+        medium_term_size: int = 100,
+        long_term_size: int = 500,
+        history_length: int = 50,
+        model_name: str = ...,
+        device: str = "cpu",
+        **kwargs: Any,
+    ) -> None: ...
+
+class AdaptiveParameters:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+class SemvecState:
+    semantic_state: NDArray[np.float64]
+    interaction_count: int
+    alpha_hit_count: int
+    timestamp: int
+    memory: "MultiResolutionMemory"
+    phase_detector: "PhaseDetector"
+    literal_cache: "LiteralCache"
+    similarity_history: list[float]
+    beta_history: list[float]
+    fsm_history: list[float]
+    phase_history: list[str]
+
+    def __init__(self, config: SemvecConfig | None = None) -> None: ...
+    def update(self, embedding: NDArray[np.float64], text: str) -> dict[str, Any]: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "SemvecState": ...
+    def set_retrieval_projection_weights(
+        self, matrix: list[list[float]] | NDArray[np.float64]
+    ) -> None: ...
+    def get_retrieval_projection_weights(self) -> list[list[float]]: ...
+    def get_retrieval_projection_w_up(self) -> list[list[float]]: ...
+
+# ---------------------------------------------------------------------------
+# Memory
+
+class MemoryUnit:
+    embedding: NDArray[np.float64]
+    text: str
+    importance: float
+    access_count: int
+    timestamp: float
+    semantic_hash: str
+    protection_score: float
+
+    def __init__(self, embedding: NDArray[np.float64], weight: float, promote: bool) -> None: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "MemoryUnit": ...
+
+class MultiResolutionMemory:
+    short_term: list[MemoryUnit]
+    medium_term: list[MemoryUnit]
+    long_term: list[MemoryUnit]
+
+    def get_relevant_memories(
+        self, query: NDArray[np.float64], top_k: int = 10
+    ) -> list[MemoryUnit]: ...
+
+# ---------------------------------------------------------------------------
+# Phase + attention + cache
+
+class PhaseDetector:
+    current_phase: str
+    phase_transitions: list[dict[str, Any]]
+
+    def __init__(self, window_size: int, switch_cost: float, min_dwell: int) -> None: ...
+    def update(self, metrics: Mapping[str, float], timestamp: int) -> str | None: ...
+    def signal_topic_switch(self, magnitude: float) -> None: ...
+
+# ---------------------------------------------------------------------------
+# Literal cache
+
+class CodeEntity:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+class EntityKind:
+    FUNCTION: "EntityKind"
+    CLASS: "EntityKind"
+    METHOD: "EntityKind"
+    MODULE: "EntityKind"
+
+class LiteralCache:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+# ---------------------------------------------------------------------------
+# Cortex — aggregation
+
+class WeightedAverageAggregation:
+    def __init__(self, dimension: int = 384) -> None: ...
+    def aggregate(
+        self,
+        local_states: list[NDArray[np.float64]],
+        weights: NDArray[np.float64] | None = None,
+    ) -> NDArray[np.float64]: ...
+
+class AttentionAggregation:
+    def __init__(self, attention_dim: int = 64, dimension: int = 384) -> None: ...
+    def aggregate(
+        self,
+        local_states: list[NDArray[np.float64]],
+        weights: NDArray[np.float64] | None = None,
+    ) -> NDArray[np.float64]: ...
+
+# ---------------------------------------------------------------------------
+# Cortex — consensus + packets
+
+class ConsensusLevel:
+    SIMPLE_MAJORITY: "ConsensusLevel"
+    QUALIFIED_MAJORITY: "ConsensusLevel"
+    UNANIMOUS: "ConsensusLevel"
+    WEIGHTED_VOTE: "ConsensusLevel"
+    ADAPTIVE_THRESHOLD: "ConsensusLevel"
+    value: str
+
+class TransferType:
+    FULL_STATE: "TransferType"
+    PARTIAL_STATE: "TransferType"
+    SEMANTIC_DELTA: "TransferType"
+    MEMORY_FRAGMENT: "TransferType"
+    COHERENCE_FIELD: "TransferType"
+    value: str
+
+class StateVectorPacket:
+    packet_id: str
+    source_instance: str
+    target_instance: str
+    transfer_type: TransferType
+    state_vector: NDArray[np.float64]
+    metadata: dict[str, Any]
+    timestamp: float
+    size_bytes: int
+    checksum: str
+
+    def __init__(
+        self,
+        packet_id: str,
+        source_instance: str,
+        target_instance: str,
+        transfer_type: TransferType,
+        state_vector: NDArray[np.float64],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None: ...
+    def verify_integrity(self) -> bool: ...
+    def serialize(self) -> bytes: ...
+    @classmethod
+    def deserialize(cls, data: bytes) -> "StateVectorPacket": ...
+
+class ConsensusProposal:
+    proposal_id: str
+    proposer_instance: str
+    proposal_type: str
+    proposed_state: NDArray[np.float64]
+    rationale: str
+    consensus_level: str
+    voting_deadline: float
+    votes: dict[str, bool]
+    vote_weights: dict[str, float]
+    status: str
+    creation_time: float
+
+    def __init__(
+        self,
+        proposal_id: str,
+        proposer_instance: str,
+        proposal_type: str,
+        proposed_state: NDArray[np.float64],
+        rationale: str,
+        consensus_level: str = "simple_majority",
+        voting_deadline: float = 0.0,
+    ) -> None: ...
+    def add_vote(self, instance_id: str, vote: bool, weight: float = 1.0) -> None: ...
+    def calculate_consensus(self) -> tuple[bool, float]: ...
+    def is_expired(self) -> bool: ...
+
+class ConsensusEngine:
+    local_instance_id: str
+    network_id: str
+    consensus_id: str
+
+    def __init__(self, local_instance_id: str, network_id: str) -> None: ...
+    def register_instance(self, instance_id: str, weight: float = 1.0) -> None: ...
+    def create_proposal(
+        self,
+        proposal_type: str,
+        proposed_state: NDArray[np.float64],
+        rationale: str,
+        consensus_level: str = "simple_majority",
+        voting_timeout: float = 300.0,
+    ) -> ConsensusProposal: ...
+    def vote_on_proposal(
+        self,
+        proposal_id: str,
+        vote: bool,
+        voting_instance: str | None = None,
+    ) -> bool: ...
+    def check_expired_proposals(self) -> None: ...
+    def get_statistics(self) -> dict[str, Any]: ...
+
+# ---------------------------------------------------------------------------
+# Cortex — local/meta
+
+class SemvecAgent:
+    instance_id: str
+    local_coherence: float
+    interaction_count: int
+    global_influence: float
+    last_update_time: float
+    min_coherence_threshold: float
+    pss_state: SemvecState
+
+    def __init__(
+        self,
+        instance_id: str,
+        embedder: object | None = None,
+        dimension: int = 384,
+    ) -> None: ...
+    def process_input(
+        self,
+        text: str,
+        global_feedback: NDArray[np.float64] | None = None,
+    ) -> dict[str, Any]: ...
+    def process_input_embedding(
+        self,
+        embedding: NDArray[np.float64] | list[float],
+        text: str,
+        global_feedback: NDArray[np.float64] | None = None,
+    ) -> dict[str, Any]: ...
+    def get_state_vector(self) -> NDArray[np.float64]: ...
+
+class SemvecCortexObserver:
+    global_state: list[float]
+    global_coherence: float
+    network_resonance: float
+    beta_global: float
+    update_count: int
+
+    def __init__(
+        self,
+        aggregation_strategy: WeightedAverageAggregation | AttentionAggregation | None = None,
+        dimension: int = 384,
+    ) -> None: ...
+    def update_global_state(
+        self, local_instances: Iterable[LocalPSSInstance]
+    ) -> dict[str, Any]: ...
+    def get_feedback_for_instance(self, instance_id: str) -> NDArray[np.float64] | None: ...
+
+class SemvecAgentNetwork:
+    local_instances: dict[str, LocalPSSInstance]
+    meta_pss: MetaPSSInstance
+    enable_feedback: bool
+    feedback_strength: float
+    max_instances: int
+
+    def __init__(
+        self,
+        aggregation_strategy: WeightedAverageAggregation | AttentionAggregation | None = None,
+        enable_feedback: bool = True,
+        feedback_strength: float = 0.3,
+        max_instances: int = 100,
+    ) -> None: ...
+    def add_instance(self, instance_id: str) -> bool: ...
+    def add_local_instance(self, instance_id: str) -> bool: ...
+    def remove_local_instance(self, instance_id: str) -> bool: ...
+    def process_input(self, instance_id: str, text: str) -> dict[str, Any]: ...
+    def get_network_state(self) -> dict[str, Any]: ...
+
+# SemvecCortexService lives in semvec.cortex.service (Python layer).
+
+# ---------------------------------------------------------------------------
+# Coding primitives
+
+class CodePointer:
+    intent_vector: NDArray[np.float64]
+    file_path: str
+    signature: str
+    importance: float
+    access_count: int
+    timestamp: float
+    semantic_hash: str
+
+    def __init__(
+        self,
+        intent_vector: NDArray[np.float64] | list[float],
+        file_path: str,
+        signature: str,
+        importance: float = 1.0,
+        access_count: int = 0,
+        timestamp: float | None = None,
+        semantic_hash: str = "",
+    ) -> None: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "CodePointer": ...
+
+class CodePointerIndex:
+    size: int
+    capacity: int
+    all_pointers: list[CodePointer]
+
+    def __init__(
+        self,
+        capacity: int = 100,
+        w_importance: float = 0.4,
+        w_recency: float = 0.35,
+        w_access: float = 0.25,
+    ) -> None: ...
+    def register(self, pointer: CodePointer) -> None: ...
+    def retrieve(
+        self, query: NDArray[np.float64], top_k: int = 10
+    ) -> list[CodePointer]: ...
+    def retention_score(self, pointer: CodePointer) -> float: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "CodePointerIndex": ...
+
+class NegativeAttractor:
+    error_vector: NDArray[np.float64]
+    description: str
+    source: str
+    severity: float
+    created_at: float
+
+    def __init__(
+        self,
+        error_vector: NDArray[np.float64] | list[float],
+        description: str,
+        source: str,
+        severity: float = 1.0,
+        created_at: float | None = None,
+    ) -> None: ...
+
+class NegativeAttractorSet:
+    size: int
+    capacity: int
+    all_attractors: list[NegativeAttractor]
+
+    def __init__(self, capacity: int = 30, min_severity: float = 0.01) -> None: ...
+    def add(
+        self,
+        error_vector: NDArray[np.float64] | list[float],
+        description: str,
+        source: str,
+        severity: float = 1.0,
+    ) -> None: ...
+    def check(
+        self, proposal: NDArray[np.float64], threshold: float = 0.7
+    ) -> list[NegativeAttractor]: ...
+    def decay(self, factor: float = 0.95) -> None: ...
+
+class PromptBuilder:
+    def __init__(self, budget: int = 6000) -> None: ...
+    def build(
+        self,
+        code_pointers: CodePointerIndex,
+        negative_attractors: NegativeAttractorSet,
+        task_vector: NDArray[np.float64],
+        *,
+        invariants: list[str] | None = None,
+        test_summary: str | None = None,
+        git_diff: str | None = None,
+        pss_memories: list[str] | None = None,
+        phase: str | None = None,
+    ) -> str: ...
+
+class CompactionEngine:
+    """Placeholder for isinstance checks; the real orchestrator is `semvec.coding.CodingEngine`."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+# ---------------------------------------------------------------------------
+# Misc
+
+def safe_cosine_similarity(
+    a: NDArray[np.float64] | list[float],
+    b: NDArray[np.float64] | list[float],
+    eps: float = 1e-8,
+) -> float: ...
+
+class EmbeddingService:
+    """Placeholder stub for isinstance compatibility with pss."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...

semvec/api/__init__.py

@@ -0,0 +1,26 @@
+"""Semvec REST API — framework-agnostic HTTP access to the Rust core.
+
+The API is auth-gated by the bundled Ed25519 JWT licensing system.
+Clients send their license JWT via ``Authorization: Bearer <jwt>`` or
+``X-API-Key: <jwt>``; the server verifies the signature, extracts the
+tier (community/pro/enterprise), and enforces rate limits accordingly.
+
+A SQLite database (``DATABASE_URL``, default ``sqlite:///semvec.db``)
+stores session/cluster/member/audit metadata — no password store, no
+separate API-key table. The license JWT is the single source of truth.
+
+Start with::
+
+    semvec serve --host 0.0.0.0 --port 8080
+
+or programmatically::
+
+    from semvec.api import create_app
+    app = create_app()
+"""
+
+from __future__ import annotations
+
+from semvec.api.app import create_app
+
+__all__ = ["create_app"]

semvec/api/app.py

@@ -0,0 +1,127 @@
+"""FastAPI application factory for the Semvec REST API.
+
+Wires auth + rate limiting + CORS + routers. CORS origins come from the
+``CORS_ORIGINS`` env var (comma-separated); an empty value blocks
+cross-origin requests by default.
+"""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import Depends, FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response
+from slowapi.errors import RateLimitExceeded
+
+from semvec.api.auth import verify_basic_auth
+from semvec.api.metrics_export import get_metrics_response, setup_metrics
+
+from semvec.api.cluster_manager import ClusterManager
+from semvec.api.cluster_routes import cluster_router, set_cluster_manager
+from semvec.api.database import create_tables
+from semvec.api.event_bus import DriftEventBus
+from semvec.api.global_observer import ObserverManager
+from semvec.api.literal_cache_routes import (
+    literal_router,
+    set_literal_session_manager,
+)
+from semvec.api.network_manager import NetworkManager
+from semvec.api.network_routes import network_router, set_network_manager
+from semvec.api.observer_routes import observer_router, set_observer_manager
+from semvec.api.regional_manager import RegionalManager
+from semvec.api.regional_routes import regional_router, set_regional_manager
+from semvec.api.routes import (
+    limiter,
+    router as core_router,
+    set_layer3_managers,
+    set_session_manager,
+)
+from semvec.api.session_delta_routes import (
+    delta_router,
+    set_delta_session_manager,
+)
+from semvec.api.session_manager import SessionManager
+
+
+def _get_cors_origins() -> list[str]:
+    raw = os.environ.get("CORS_ORIGINS", "")
+    if not raw.strip():
+        return []
+    return [origin.strip() for origin in raw.split(",") if origin.strip()]
+
+
+def create_app() -> FastAPI:
+    """Build and return the Semvec REST API FastAPI application."""
+    app = FastAPI(
+        title="Semvec REST API — Persistent Semantic State",
+        description=(
+            "Framework-agnostic semantic memory service. Feed text into "
+            "Semvec sessions and retrieve context-aware memories. Auth "
+            "via Ed25519-signed license JWTs (SEMVEC_LICENSE_KEY)."
+        ),
+        version="1.0.0",
+    )
+
+    app.state.limiter = limiter
+
+    def _rate_limit_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
+        return JSONResponse(
+            status_code=429,
+            content={"detail": "Too many requests"},
+            headers={"Retry-After": "60"},
+        )
+
+    app.add_exception_handler(RateLimitExceeded, _rate_limit_handler)
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=_get_cors_origins(),
+        allow_methods=["GET", "POST", "PATCH", "DELETE", "PUT", "OPTIONS"],
+        allow_headers=["Content-Type", "Authorization", "X-API-Key"],
+    )
+
+    setup_metrics(app)
+
+    @app.get("/metrics")
+    def _metrics(_: bool = Depends(verify_basic_auth)) -> Response:
+        return get_metrics_response()
+
+    create_tables()
+
+    manager = SessionManager()
+    set_session_manager(manager)
+    set_delta_session_manager(manager)
+    set_literal_session_manager(manager)
+    app.state.session_manager = manager
+
+    cluster_manager = ClusterManager(manager)
+    set_cluster_manager(cluster_manager)
+    app.state.cluster_manager = cluster_manager
+
+    event_bus = DriftEventBus()
+    regional_manager = RegionalManager(manager, cluster_manager, event_bus)
+    set_regional_manager(regional_manager)
+    app.state.regional_manager = regional_manager
+    app.state.drift_event_bus = event_bus
+
+    # routes.run() publishes drift events through these managers.
+    set_layer3_managers(cluster_manager, regional_manager)
+
+    observer_manager = ObserverManager(cluster_manager, regional_manager, manager)
+    set_observer_manager(observer_manager)
+    app.state.observer_manager = observer_manager
+
+    network_manager = NetworkManager(manager)
+    set_network_manager(network_manager)
+    app.state.network_manager = network_manager
+
+    app.include_router(core_router)
+    app.include_router(delta_router)
+    app.include_router(literal_router)
+    app.include_router(cluster_router)
+    app.include_router(regional_router)
+    app.include_router(observer_router)
+    app.include_router(network_router)
+
+    return app