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
