hga 0.1.0__tar.gz

hga-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HGA Authors
+
+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.

hga-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include hga *.py

hga-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: hga
+Version: 0.1.0
+Summary: Hybrid Governance Architecture — Multi-layer agent memory system with vector quantization, deterministic vault, and semantic neuron routing
+Author-email: Ahmet <ahmet@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ahmet/hga
+Project-URL: Repository, https://github.com/ahmet/hga
+Project-URL: Issues, https://github.com/ahmet/hga/issues
+Project-URL: Documentation, https://github.com/ahmet/hga#readme
+Keywords: llm,agent,memory,vector-quantization,semantic-routing,governance,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: sentence-transformers>=2.2
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: groq
+Requires-Dist: groq>=0.4; extra == "groq"
+Requires-Dist: langchain-groq; extra == "groq"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: groq>=0.4; extra == "all"
+Requires-Dist: langchain-groq; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: seaborn; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: tqdm; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# HGA — Hybrid Governance Architecture
+
+[![PyPI version](https://badge.fury.io/py/hga-memory.svg)](https://pypi.org/project/hga-memory/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A multi-layer agent memory system that provides intelligent query routing, exact recall, and semantic neuron maturation for LLM-based agents.
+
+## Features
+
+- **L1 — RM (Routing Memory: A Vector-Quantization-Based Retrieval Primitive):** Vector quantization with K-means centroids, multi-probe retrieval, online EMA adaptation, and drift detection
+- **L2 — Deterministic Vault:** Exact key-value recall with SHA-256 integrity verification, policy tagging (Public/Internal/Sensitive/Restricted), and full audit trails
+- **L3 — Semantic Neuron Layer:** 4-stage neuron maturation (Stage 0→3), causal reasoning chains, structural similarity transfer, and safe Stage 3 replay
+- **Governance Gate:** Intelligent routing across 5 execution paths based on confidence, margin, neuron maturity, and sensitivity
+- **Consolidation:** Active trace writing + passive LLM-free capability growth (co-occurrence mining, edge finalization, RM reshaping)
+- **Real Embeddings:** Uses `all-MiniLM-L6-v2` (384-dimensional) — no mock or synthetic embeddings
+
+## Installation
+
+```bash
+pip install hga-memory
+```
+
+With LLM provider support:
+
+```bash
+# Groq
+pip install hga-memory[groq]
+
+# OpenAI
+pip install hga-memory[openai]
+
+# Everything
+pip install hga-memory[all]
+```
+
+## Quick Start
+
+```python
+from hga import AgentMemory
+
+# Initialize memory system
+memory = AgentMemory()
+
+# Store information
+memory.store("Project deadline is March 15, 2026", policy_tag="Internal")
+memory.store("API key format: sk-xxxx", policy_tag="Sensitive")
+
+# Query with automatic routing
+result = memory.recall("When is the project deadline?")
+print(result.answer)
+print(f"Path: {result.path}, Tokens: {result.tokens_used}")
+
+# The gate automatically routes:
+# - Exact facts → Deterministic Vault (0 tokens)
+# - Semantic queries → RM retrieval
+# - Mature patterns → Stage 3 replay (0 tokens)
+# - Sensitive queries → Deterministic path (safe)
+```
+
+## Architecture
+
+```
+Query → Governance Gate → Route Decision
+              │
+              ├── Stage0Path    → Full LLM call (new pattern)
+              ├── FastSemantic  → L1 retrieval + LLM
+              ├── VerifyPath    → L1 + L3 verify + LLM
+              ├── Stage3Path    → Causal replay (no LLM)
+              └── Deterministic → L2 exact lookup (no LLM)
+```
+
+## Gate Decision Logic
+
+| Condition | Path |
+|---|---|
+| Sensitivity=High OR edge weight < -1 | DeterministicPath |
+| Stage 3 + confidence >= 0.6 | Stage3Path |
+| Stage 2 + confidence >= 0.6 + margin >= 0.1 | VerifyPath |
+| Stage >= 1 + confidence >= 0.6 | FastSemanticPath |
+| No matching neuron | Stage0Path |
+
+## Neuron Maturation
+
+Neurons progress through 4 stages based on successful executions:
+
+- **Stage 0→1:** weight > 0, 3+ successful hits
+- **Stage 1→2:** weight > +2, 8+ hits
+- **Stage 2→3:** weight > +2.5, 5 consecutive clean executions
+
+Edge weights update: `w += source_weight × outcome` (clipped to [-3, +3])
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `K` | 64 | Number of RM centroids |
+| `ALPHA` | 0.6 | Confidence threshold |
+| `DELTA_MIN` | 0.1 | Margin threshold |
+| `eta` | 0.01 | EMA learning rate |
+| `embedding_dim` | 384 | Embedding dimensionality |
+
+## License
+
+MIT

hga-0.1.0/README.md

@@ -0,0 +1,105 @@
+# HGA — Hybrid Governance Architecture
+
+[![PyPI version](https://badge.fury.io/py/hga-memory.svg)](https://pypi.org/project/hga-memory/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A multi-layer agent memory system that provides intelligent query routing, exact recall, and semantic neuron maturation for LLM-based agents.
+
+## Features
+
+- **L1 — RM (Routing Memory: A Vector-Quantization-Based Retrieval Primitive):** Vector quantization with K-means centroids, multi-probe retrieval, online EMA adaptation, and drift detection
+- **L2 — Deterministic Vault:** Exact key-value recall with SHA-256 integrity verification, policy tagging (Public/Internal/Sensitive/Restricted), and full audit trails
+- **L3 — Semantic Neuron Layer:** 4-stage neuron maturation (Stage 0→3), causal reasoning chains, structural similarity transfer, and safe Stage 3 replay
+- **Governance Gate:** Intelligent routing across 5 execution paths based on confidence, margin, neuron maturity, and sensitivity
+- **Consolidation:** Active trace writing + passive LLM-free capability growth (co-occurrence mining, edge finalization, RM reshaping)
+- **Real Embeddings:** Uses `all-MiniLM-L6-v2` (384-dimensional) — no mock or synthetic embeddings
+
+## Installation
+
+```bash
+pip install hga-memory
+```
+
+With LLM provider support:
+
+```bash
+# Groq
+pip install hga-memory[groq]
+
+# OpenAI
+pip install hga-memory[openai]
+
+# Everything
+pip install hga-memory[all]
+```
+
+## Quick Start
+
+```python
+from hga import AgentMemory
+
+# Initialize memory system
+memory = AgentMemory()
+
+# Store information
+memory.store("Project deadline is March 15, 2026", policy_tag="Internal")
+memory.store("API key format: sk-xxxx", policy_tag="Sensitive")
+
+# Query with automatic routing
+result = memory.recall("When is the project deadline?")
+print(result.answer)
+print(f"Path: {result.path}, Tokens: {result.tokens_used}")
+
+# The gate automatically routes:
+# - Exact facts → Deterministic Vault (0 tokens)
+# - Semantic queries → RM retrieval
+# - Mature patterns → Stage 3 replay (0 tokens)
+# - Sensitive queries → Deterministic path (safe)
+```
+
+## Architecture
+
+```
+Query → Governance Gate → Route Decision
+              │
+              ├── Stage0Path    → Full LLM call (new pattern)
+              ├── FastSemantic  → L1 retrieval + LLM
+              ├── VerifyPath    → L1 + L3 verify + LLM
+              ├── Stage3Path    → Causal replay (no LLM)
+              └── Deterministic → L2 exact lookup (no LLM)
+```
+
+## Gate Decision Logic
+
+| Condition | Path |
+|---|---|
+| Sensitivity=High OR edge weight < -1 | DeterministicPath |
+| Stage 3 + confidence >= 0.6 | Stage3Path |
+| Stage 2 + confidence >= 0.6 + margin >= 0.1 | VerifyPath |
+| Stage >= 1 + confidence >= 0.6 | FastSemanticPath |
+| No matching neuron | Stage0Path |
+
+## Neuron Maturation
+
+Neurons progress through 4 stages based on successful executions:
+
+- **Stage 0→1:** weight > 0, 3+ successful hits
+- **Stage 1→2:** weight > +2, 8+ hits
+- **Stage 2→3:** weight > +2.5, 5 consecutive clean executions
+
+Edge weights update: `w += source_weight × outcome` (clipped to [-3, +3])
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `K` | 64 | Number of RM centroids |
+| `ALPHA` | 0.6 | Confidence threshold |
+| `DELTA_MIN` | 0.1 | Margin threshold |
+| `eta` | 0.01 | EMA learning rate |
+| `embedding_dim` | 384 | Embedding dimensionality |
+
+## License
+
+MIT

hga-0.1.0/hga/__init__.py

@@ -0,0 +1,8 @@
+"""HGA — Hybrid Governance Architecture for Agent Memory."""
+
+from .memory import AgentMemory, RecallResult
+from .gate.governance import ExecutionPath, GateDecision
+from .l3.replay import ReplayResult
+
+__all__ = ["AgentMemory", "RecallResult", "ExecutionPath", "GateDecision", "ReplayResult"]
+__version__ = "0.1.0"

hga-0.1.0/hga/consolidation.py

@@ -0,0 +1,328 @@
+"""Passive Consolidation — LLM-free structural learning between sessions.
+
+Runs when no active LLM call is in progress. Operations:
+1. Edge finalization: confirm/decay provisional neuron weights
+2. DV compaction: deduplicate by hash, clean dangling pointers
+3. Drift alarm reset: finalize session statistics
+4. Co-occurrence mining: centroid pairs probed together → L3 edges
+5. RM reshaping: stable L3 routes trigger codebook splits
+6. Salience-guided forgetting: lifecycle management + neuron pruning/demotion
+
+All operations are strictly LLM-free.
+"""
+
+import logging
+import time
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .l1.codebook import Codebook
+    from .l1.drift import DriftMonitor
+    from .l2.vault import DeterministicVault
+    from .l3.matcher import NeuronMatcher
+    from .storage.sqlite_backend import SQLiteBackend
+
+logger = logging.getLogger("hga.consolidation")
+
+
+# ─── Co-occurrence Edge ────────────────────────────────────────────────────
+
+@dataclass
+class CooccurrenceEdge:
+    """Edge between two neurons that are frequently co-probed."""
+    neuron_a_id: str
+    neuron_b_id: str
+    count: int = 0
+    weight: float = 0.0
+
+
+# ─── Passive Consolidation Result ──────────────────────────────────────────
+
+@dataclass
+class ConsolidationResult:
+    """Summary of a passive consolidation cycle."""
+    edges_finalized: int = 0
+    edges_decayed: int = 0
+    edges_removed: int = 0
+    provisional_confirmed: int = 0
+    provisional_removed: int = 0
+    dv_before: int = 0
+    dv_after: int = 0
+    dv_removed: int = 0
+    drift_reset: bool = False
+    cooccurrence_edges_created: int = 0
+    reshaping_splits: int = 0
+    forgetting_kept: int = 0
+    forgetting_summarized: int = 0
+    forgetting_migrated: int = 0
+    forgetting_deleted: int = 0
+    neurons_pruned: int = 0
+    neurons_demoted: int = 0
+    privacy_protected: int = 0
+    duration_ms: float = 0.0
+
+
+class PassiveConsolidation:
+    """Runs LLM-free consolidation operations on the HGA memory system.
+
+    Must be called explicitly (e.g., between sessions or during idle time).
+    Guarantees zero LLM calls — all operations are structural/statistical.
+    """
+
+    # Co-occurrence threshold: minimum co-probes to create an edge
+    COOCCURRENCE_THRESHOLD = 3
+
+    # Edge decay factor for old provisional neurons
+    EDGE_DECAY_FACTOR = 0.8
+    EDGE_REMOVE_THRESHOLD = 0.1
+
+    # Minimum neuron age (hits) before edge finalization applies
+    EDGE_MIN_AGE = 5
+
+    # Reshaping: minimum bucket size to trigger split consideration
+    RESHAPE_BUCKET_SIZE_THRESHOLD = 10
+
+    def __init__(self, forgetting_enabled: bool = False):
+        self._probe_history: List[Tuple[str, float]] = []  # (neuron_id, timestamp)
+        self._cooccurrence_edges: Dict[Tuple[str, str], CooccurrenceEdge] = {}
+        self._forgetting_enabled = forgetting_enabled
+        self._forgetting: Optional["MemoryForgetting"] = None
+
+    @property
+    def cooccurrence_edges(self) -> List[CooccurrenceEdge]:
+        return list(self._cooccurrence_edges.values())
+
+    def record_probe(self, neuron_id: str) -> None:
+        """Record that a neuron was probed during active phase."""
+        self._probe_history.append((neuron_id, time.time()))
+
+    def run_passive_cycle(
+        self,
+        matcher: "NeuronMatcher",
+        vault: "DeterministicVault",
+        codebook: "Codebook",
+        drift: "DriftMonitor",
+        storage: "SQLiteBackend" = None,
+    ) -> ConsolidationResult:
+        """Run a full passive consolidation cycle.
+
+        Args:
+            matcher: L3 neuron matcher
+            vault: L2 deterministic vault
+            codebook: L1 codebook
+            drift: Drift monitor
+            storage: SQLite backend (needed for forgetting, optional)
+
+        Returns:
+            ConsolidationResult with operation counts.
+        """
+        start = time.time()
+        result = ConsolidationResult()
+
+        # 1. Edge finalization (always run, cheap)
+        self._finalize_edges(matcher, result)
+
+        # 2. DV compaction (always run, cheap)
+        self._compact_dv(vault, result)
+
+        # 3. Drift alarm reset (always run, cheap)
+        self._reset_drift(drift, result)
+
+        # 4. Co-occurrence mining (needs probe history)
+        if self._probe_history:
+            self._mine_cooccurrence(matcher, result)
+
+        # 5. RM reshaping (needs mature neurons)
+        has_mature = any(n.stage >= 2 for n in matcher.get_all_neurons())
+        if has_mature:
+            self._reshape_codebook(matcher, codebook, result)
+
+        # 6. Salience-guided forgetting (needs storage)
+        if storage is not None and self._forgetting_enabled:
+            self._run_forgetting(storage, vault, matcher, result)
+
+        result.duration_ms = (time.time() - start) * 1000
+        logger.info(f"Passive cycle complete: {result.duration_ms:.1f}ms, "
+                     f"edges_finalized={result.edges_finalized}, "
+                     f"cooccurrence={result.cooccurrence_edges_created}, "
+                     f"splits={result.reshaping_splits}, "
+                     f"forgetting_deleted={result.forgetting_deleted}")
+        return result
+
+    # ─── Operation 1: Edge Finalization ──────────────────────────────────
+
+    def _finalize_edges(self, matcher: "NeuronMatcher",
+                        result: ConsolidationResult) -> None:
+        """Confirm or decay neuron edge weights."""
+        neurons_to_remove = []
+
+        for neuron in matcher.get_all_neurons():
+            # Handle provisional neurons
+            if neuron.provisional:
+                if neuron.hit_count >= self.EDGE_MIN_AGE:
+                    if neuron.success_rate >= 0.8:
+                        neuron.provisional = False
+                        result.provisional_confirmed += 1
+                    else:
+                        neurons_to_remove.append(neuron.id)
+                        result.provisional_removed += 1
+                continue
+
+            # For confirmed neurons: decay low-performing weights
+            if neuron.hit_count >= self.EDGE_MIN_AGE:
+                if neuron.success_rate >= 0.8:
+                    result.edges_finalized += 1
+                elif neuron.edge_weight > 0 and neuron.success_rate < 0.5:
+                    neuron.edge_weight *= self.EDGE_DECAY_FACTOR
+                    result.edges_decayed += 1
+                    if abs(neuron.edge_weight) < self.EDGE_REMOVE_THRESHOLD:
+                        result.edges_removed += 1
+
+        # Remove failed provisionals
+        for nid in neurons_to_remove:
+            matcher.remove_neuron(nid)
+
+    # ─── Operation 2: DV Compaction ──────────────────────────────────────
+
+    def _compact_dv(self, vault: "DeterministicVault",
+                    result: ConsolidationResult) -> None:
+        """Deduplicate DV records by hash."""
+        result.dv_before = vault.count
+
+        seen_hashes = {}
+        duplicates = []
+
+        for key, record in list(vault._local.items()):
+            if record.hash in seen_hashes:
+                duplicates.append(key)
+            else:
+                seen_hashes[record.hash] = key
+
+        for key in duplicates:
+            del vault._local[key]
+
+        result.dv_after = vault.count
+        result.dv_removed = len(duplicates)
+
+    # ─── Operation 3: Drift Reset ───────────────────────────────────────
+
+    def _reset_drift(self, drift: "DriftMonitor",
+                     result: ConsolidationResult) -> None:
+        """Reset drift baseline using recent data."""
+        if drift.in_drift or drift.episode_count > 0:
+            drift.reset_baseline()
+            result.drift_reset = True
+
+    # ─── Operation 4: Co-occurrence Mining ──────────────────────────────
+
+    def _mine_cooccurrence(self, matcher: "NeuronMatcher",
+                           result: ConsolidationResult) -> None:
+        """Analyze probe history for co-occurring neuron pairs.
+
+        Two neurons probed within a short time window → co-occurrence.
+        Threshold co-occurrences → create an edge.
+        """
+        WINDOW_SECONDS = 60.0  # probes within 60s are considered co-occurring
+
+        # Count co-occurrences
+        pair_counts: Counter = Counter()
+        history = self._probe_history
+
+        for i in range(len(history)):
+            nid_i, ts_i = history[i]
+            for j in range(i + 1, len(history)):
+                nid_j, ts_j = history[j]
+                if ts_j - ts_i > WINDOW_SECONDS:
+                    break
+                if nid_i != nid_j:
+                    pair = tuple(sorted([nid_i, nid_j]))
+                    pair_counts[pair] += 1
+
+        # Create edges for frequent pairs
+        for pair, count in pair_counts.items():
+            if count >= self.COOCCURRENCE_THRESHOLD:
+                if pair not in self._cooccurrence_edges:
+                    # Verify both neurons still exist
+                    n_a = matcher.get_neuron(pair[0])
+                    n_b = matcher.get_neuron(pair[1])
+                    if n_a and n_b:
+                        self._cooccurrence_edges[pair] = CooccurrenceEdge(
+                            neuron_a_id=pair[0],
+                            neuron_b_id=pair[1],
+                            count=count,
+                            weight=float(count),
+                        )
+                        result.cooccurrence_edges_created += 1
+                else:
+                    # Update existing edge
+                    self._cooccurrence_edges[pair].count += count
+                    self._cooccurrence_edges[pair].weight = float(
+                        self._cooccurrence_edges[pair].count
+                    )
+
+        # Clear probe history after mining
+        self._probe_history.clear()
+
+    # ─── Operation 5: RM Reshaping ─────────────────────────────────────
+
+    def _reshape_codebook(self, matcher: "NeuronMatcher",
+                          codebook: "Codebook",
+                          result: ConsolidationResult) -> None:
+        """L3→L1 feedback: split hot centroids used by mature neurons."""
+        if not codebook.fitted:
+            return
+
+        # Find centroids frequently used by mature neurons
+        hot_centroids: Counter = Counter()
+        for neuron in matcher.get_all_neurons():
+            if neuron.stage < 2:
+                continue
+            # Encode neuron centroid to find its primary codebook centroid
+            cid, _ = codebook.encode(neuron.pattern_embedding)
+            hot_centroids[cid] += 1
+
+        # Split large hot buckets
+        for cid, neuron_count in hot_centroids.most_common():
+            if cid >= codebook.K:
+                continue
+            bucket = codebook.buckets.get(cid)
+            if not bucket:
+                continue
+            bucket_size = len(bucket.item_ids)
+            if bucket_size >= self.RESHAPE_BUCKET_SIZE_THRESHOLD:
+                if codebook.maybe_split(cid):
+                    result.reshaping_splits += 1
+
+    # ─── Operation 6: Salience-Guided Forgetting ─────────────────────
+
+    @property
+    def forgetting_enabled(self) -> bool:
+        return self._forgetting_enabled
+
+    @forgetting_enabled.setter
+    def forgetting_enabled(self, value: bool) -> None:
+        self._forgetting_enabled = value
+
+    def _run_forgetting(
+        self,
+        storage: "SQLiteBackend",
+        vault: "DeterministicVault",
+        matcher: "NeuronMatcher",
+        result: ConsolidationResult,
+    ) -> None:
+        """Run salience-guided forgetting as part of passive cycle."""
+        from .forgetting import MemoryForgetting
+
+        if self._forgetting is None:
+            self._forgetting = MemoryForgetting()
+
+        fr = self._forgetting.run_forgetting_cycle(storage, vault, matcher)
+        result.forgetting_kept = fr.items_kept
+        result.forgetting_summarized = fr.items_summarized
+        result.forgetting_migrated = fr.items_migrated
+        result.forgetting_deleted = fr.items_deleted
+        result.neurons_pruned = fr.neurons_pruned
+        result.neurons_demoted = fr.neurons_demoted
+        result.privacy_protected = fr.privacy_protected

hga-0.1.0/hga/embeddings/__init__.py

@@ -0,0 +1,3 @@
+from .local import LocalEmbeddings
+
+__all__ = ["LocalEmbeddings"]

hga-0.1.0/hga/embeddings/base.py

@@ -0,0 +1,22 @@
+"""Abstract embedding backend interface."""
+
+from abc import ABC, abstractmethod
+from typing import List
+import numpy as np
+
+
+class EmbeddingBackend(ABC):
+    """Abstract base for embedding providers."""
+
+    @property
+    @abstractmethod
+    def dim(self) -> int:
+        """Embedding dimensionality."""
+
+    @abstractmethod
+    def encode(self, text: str) -> np.ndarray:
+        """Encode a single text to a normalized vector."""
+
+    @abstractmethod
+    def encode_batch(self, texts: List[str]) -> np.ndarray:
+        """Encode a batch of texts. Returns (N, dim) matrix."""