memoryintelligence 1.0.1__tar.gz → 2.0.0__tar.gz

memoryintelligence-2.0.0/CHANGELOG.md

@@ -0,0 +1,234 @@
+# Changelog
+
+All notable changes to the Memory Intelligence Python SDK.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-02-27
+
+### Breaking Changes
+
+#### UMO Namespace Pattern
+- **Changed:** All UMO operations moved to `mi.umo.*` namespace
+  - `mi.process()` → `mi.umo.process()`
+  - `mi.search()` → `mi.umo.search()`
+  - `mi.match()` → `mi.umo.match()`
+  - `mi.explain()` → `mi.umo.explain()`
+  - `mi.delete()` → `mi.umo.delete()`
+
+#### Mandatory Encryption
+- **Changed:** Client-side AES-256-GCM encryption is now **mandatory**
+- **Removed:** `enable_encryption` parameter (previously optional in v1)
+- **Added:** Automatic encryption with ephemeral key if `MI_ENCRYPTION_KEY` not set
+- **Added:** Warning logged when using ephemeral keys in production
+
+#### User ID Format
+- **Changed:** `user_id` parameter renamed to `user_ulid`
+- **Changed:** Must use ULID format (26-character string: `01ABC...`)
+- **Migration:** Generate ULIDs: `str(ULID())`
+
+#### Dual Identity Pattern
+- **Changed:** `user_ulid` no longer defaults from client constructor
+- **Added:** `for_user(user_ulid)` method for scoped clients
+- **Usage:**
+  ```python
+  # v2.0
+  mi = MemoryClient()
+  user_client = mi.for_user("01USER12345678901234567890")
+  umo = user_client.umo.process("content")
+  ```
+
+#### Model Serialization
+- **Changed:** Models converted from dataclasses to Pydantic BaseModel
+- **Changed:** `asdict(umo)` → `umo.model_dump()`
+- **Changed:** `json.dumps(asdict(umo))` → `umo.model_dump_json()`
+- **Added:** Full Pydantic validation and serialization support
+
+#### Error Classes
+- **Renamed:** `AuthError` → `AuthenticationError`
+- **Added:** New exception classes:
+  - `LicenseError` - License validation and feature gating
+  - `PIIViolationError` - PII detection violations (HTTP 451)
+  - `PaymentRequiredError` - License required (HTTP 402)
+  - `ConflictError` - Resource conflicts (HTTP 409)
+
+### Added
+
+#### EdgeClient
+- **Added:** `EdgeClient` for on-premises deployment
+- **Features:**
+  - HIPAA mode (`hipaa_mode=True`)
+  - Air-gapped deployment (`air_gapped=True`)
+  - Federated aggregation (`aggregate()`)
+  - PHI handling verification (`verify_phi_handling()`)
+  - Audit log export (`export_audit_log()`)
+- **License Required:** ENTERPRISE tier only
+
+#### Async Support
+- **Added:** `AsyncMemoryClient` for non-blocking operations
+- **Features:**
+  - Full async/await support
+  - Connection pooling with `httpx.AsyncClient`
+  - Same API as sync client
+
+#### License System
+- **Added:** License tier enforcement (TRIAL, STARTER, PROFESSIONAL, ENTERPRISE)
+- **Added:** Feature gating:
+  - STARTER: `process()`, `search()` only
+  - PROFESSIONAL: All cloud features (`match()`, `explain()`)
+  - ENTERPRISE: All features including EdgeClient
+- **Added:** Grace periods:
+  - Cloud: 14 days
+  - Air-gapped: 30 days
+- **Added:** License caching with 24-hour TTL
+- **Added:** Background license revalidation
+
+#### Encryption Enhancements
+- **Added:** AES-256-GCM encryption with PBKDF2 (100,000 iterations)
+- **Added:** User ULID binding via associated data
+- **Added:** Key identification via SHA-256 hash
+- **Added:** `EncryptedPayload` model for inspection
+
+#### HTTP Transport
+- **Added:** `SyncTransport` and `AsyncTransport` with retry logic
+- **Added:** Exponential backoff with jitter
+- **Added:** Retry on: 408, 429, 500, 502, 503, 504
+- **Added:** ULID request IDs for tracing
+- **Added:** Automatic error mapping from HTTP status codes
+
+#### Models
+- **Added:** Pydantic models for all API responses:
+  - `MeaningObject`, `Entity`, `Topic`, `SVOTriple`
+  - `SearchResponse`, `SearchResult`, `MatchResult`
+  - `Explanation`, `HumanExplanation`, `AuditExplanation`
+  - `Provenance`, `PIIInfo`, `DeleteResult`
+- **Added:** Enum types:
+  - `Scope` (USER, CLIENT, ORGANIZATION)
+  - `PIIHandling` (EXTRACT_AND_REDACT, HASH, REJECT)
+  - `RetentionPolicy` (FULL, MEANING_ONLY, NO_STORAGE)
+  - `ProvenanceMode` (MINIMAL, STANDARD, AUDIT)
+  - `LicenseType` (TRIAL, STARTER, PROFESSIONAL, ENTERPRISE)
+  - `LicenseStatus` (ACTIVE, EXPIRED, REVOKED, SUSPENDED)
+
+### Changed
+
+#### Dependencies
+- **Added:** `httpx>=0.27.0` (was `requests` in v1)
+- **Added:** `pydantic>=2.5.0`
+- **Added:** `cryptography>=42.0.0`
+- **Added:** `python-ulid>=2.0.0`
+- **Removed:** `requests` dependency
+
+#### Configuration
+- **Changed:** `MI_API_KEY` environment variable now the primary auth method
+- **Changed:** `MI_ENCRYPTION_KEY` for persistent encryption keys
+- **Added:** Validation for API key format (`mi_sk_` prefix)
+
+#### Error Handling
+- **Changed:** All errors now include `code` attribute
+- **Changed:** `RateLimitError` includes `retry_after` seconds
+- **Changed:** `ServerError` includes `request_id` for debugging
+- **Changed:** `ValidationError` includes `field` for invalid parameters
+- **Changed:** `LicenseError` includes `days_expired` and `renew_url`
+
+### Removed
+
+- **Removed:** Direct method calls on `MemoryClient` (use `mi.umo.*`)
+- **Removed:** `enable_encryption` parameter (always enabled)
+- **Removed:** `user_id` parameter (use `user_ulid`)
+- **Removed:** `AuthError` exception (use `AuthenticationError`)
+
+### Security
+
+- **Added:** Mandatory client-side encryption for all content
+- **Added:** User ULID binding prevents cross-user decryption
+- **Added:** Authentication tags prevent tampering
+- **Added:** PII detection with configurable handling
+- **Added:** HIPAA mode for healthcare compliance
+- **Added:** Audit logging for compliance reviews
+- **Added:** Scope isolation (user/client/organization)
+
+### Documentation
+
+- **Added:** Quickstart guide (`docs/quickstart.md`)
+- **Added:** Authentication guide (`docs/authentication.md`)
+- **Added:** Encryption guide (`docs/encryption.md`)
+- **Added:** Licensing guide (`docs/licensing.md`)
+- **Added:** API reference (`docs/api_reference.md`)
+- **Added:** Enterprise guide (`docs/enterprise.md`)
+- **Added:** Migration guide (`docs/migration_v1_to_v2.md`)
+- **Added:** FAQ (`docs/faq.md`)
+- **Added:** OpenAPI specification (`docs/openapi.yaml`)
+
+### Testing
+
+- **Added:** Comprehensive test suite:
+  - `tests/test_client.py` - UMONamespace methods
+  - `tests/test_crypto.py` - Encryption/decryption
+  - `tests/test_license.py` - License validation
+  - `tests/test_edge_client.py` - EdgeClient functionality
+  - `tests/test_errors.py` - HTTP status mapping
+  - `tests/test_integration.py` - End-to-end workflows
+- **Added:** pytest fixtures with mocked transport
+- **Added:** Test coverage for all license tiers
+
+---
+
+## [1.0.1] - 2026-02-07
+
+### Fixed
+- Corrected `ProvenanceError` in `__all__` exports list (final typo fix)
+
+## [1.0.0] - 2026-02-07 [YANKED]
+
+### Added
+- **MemoryClient** with 6 core operations: process, search, match, explain, delete, verify_provenance
+- **EdgeClient** for on-premises HIPAA-compliant deployments
+- Privacy-first architecture with meaning-only retention (default)
+- Structured semantic extraction (entities, topics, SVO triples, key phrases)
+- Explainable search results with human + audit explanations
+- Cryptographic provenance tracking with hash chain verification
+- ULID-based identity firewall for cryptographic tenant isolation
+- Scope-based access control (user, team, client, organization)
+- PII detection and configurable handling (extract_and_redact, hash, reject)
+- Type-safe API with Pydantic models
+- Comprehensive error handling (7 exception types)
+- 30+ unit and integration tests
+
+### Known Limitations
+- Pagination not yet implemented (coming in v1.1.0)
+- Streaming search results not yet available
+- Temporal intelligence parameter present but not fully validated in tests
+
+### Fixed
+- Corrected `ProvenanceError` exception name (was misspelled as `ProvenenaceError`)
+
+---
+
+## Migration Guide
+
+See [docs/migration_v1_to_v2.md](docs/migration_v1_to_v2.md) for detailed migration instructions.
+
+### Quick Migration Checklist
+
+- [ ] Update imports to use `mi.umo.*` namespace
+- [ ] Rename `user_id` to `user_ulid` (use ULID format)
+- [ ] Set `MI_ENCRYPTION_KEY` environment variable
+- [ ] Update `asdict(umo)` to `umo.model_dump()`
+- [ ] Rename `AuthError` to `AuthenticationError`
+- [ ] Use `for_user()` for multi-user applications
+
+---
+
+## Support
+
+- **Documentation:** [docs.memoryintelligence.dev](https://docs.memoryintelligence.dev)
+- **Migration Help:** migration@memoryintelligence.dev
+- **Issues:** [github.com/memoryintelligence/sdk-python/issues](https://github.com/memoryintelligence/sdk-python/issues)
+- **Changelog:** This file
+
+[2.0.0]: https://github.com/memoryintelligence/sdk-python/releases/tag/v2.0.0
+[1.0.1]: https://github.com/memoryintelligence/sdk-python/releases/tag/v1.0.1
+[1.0.0]: https://github.com/memoryintelligence/sdk-python/releases/tag/v1.0.0
+[Unreleased]: https://github.com/memoryintelligence/sdk-python/compare/v2.0.0...HEAD

memoryintelligence-2.0.0/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: memoryintelligence
+Version: 2.0.0
+Summary: Official Python SDK for Memory Intelligence — Verifiable meaning infrastructure
+Author-email: Memory Intelligence Team <sdk@memoryintelligence.dev>
+License: MIT
+Project-URL: Homepage, https://memoryintelligence.dev
+Project-URL: Documentation, https://docs.memoryintelligence.dev
+Project-URL: Repository, https://github.com/memoryintelligence/sdk-python
+Project-URL: Changelog, https://github.com/memoryintelligence/sdk-python/blob/main/CHANGELOG.md
+Keywords: ai,llm,memory,rag,embeddings,privacy,compliance,hipaa,gdpr,provenance,umo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: python-ulid>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# Memory Intelligence SDK
+
+The official Python SDK for Memory Intelligence - Verifiable meaning infrastructure for AI.
+
+[![PyPI](https://img.shields.io/pypi/v/memoryintelligence.svg)](https://pypi.org/project/memoryintelligence/)
+[![License](https://img.shields.io/pypi/l/memoryintelligence.svg)](https://pypi.org/project/memoryintelligence/)
+
+## Quick Start
+
+```python
+from memoryintelligence import MemoryClient
+
+# Initialize client
+mi = MemoryClient(api_key="mi_sk_...")
+
+# Process content → meaning
+umo = mi.umo.process("Meeting notes from today", user_ulid="01ABC...")
+
+# Search meaning
+results = mi.umo.search("What did we discuss?", user_ulid="01ABC...", explain=True)
+
+# Match for recommendations
+match = mi.umo.match("01ABC...", "01XYZ...", explain=True)
+
+# Get explanation
+explanation = mi.umo.explain("01ABC...")
+
+# Delete for GDPR
+result = mi.umo.delete(user_ulid="01ABC...")
+```
+
+## Key Features
+
+- **Meaning-First Architecture**: Raw content discarded after processing
+- **Five Core Operations**: Process, Search, Match, Explain, Delete
+- **Provenance Tracking**: Cryptographic verification of content lineage
+- **GDPR Compliance**: One-call data deletion with audit proof
+- **Built-in Telemetry**: Debug logs for content processing
+- **Simplified API**: Only 12 essential exports
+
+## Installation
+
+```bash
+pip install memoryintelligence
+```
+
+## Usage Guide
+
+### Initialize the Client
+
+```python
+from memoryintelligence import MemoryClient
+
+# For production (API key required)
+mi = MemoryClient(api_key="mi_sk_prod_...")
+
+# For development
+mi = MemoryClient(api_key="mi_sk_dev_...")
+
+# For specific user (multi-tenant)
+user_mi = mi.for_user("01USER12345678901234567890")
+```
+
+### Process Content
+
+Convert raw content to meaning (discards raw content by default):
+
+```python
+from memoryintelligence import RetentionPolicy, PIIHandling, ProvenanceMode
+
+umo = mi.umo.process(
+    "Budget approved for Q3 initiatives",
+    user_ulid="01ABC...",
+    retention_policy=RetentionPolicy.MEANING_ONLY,
+    pii_handling=PIIHandling.EXTRACT_AND_REDACT,
+    provenance_mode=ProvenanceMode.STANDARD
+)
+
+print(umo.entities)      # [Entity(text="Q3", type="DATE"), ...]
+print(umo.topics)        # ["budget", "initiatives"]
+print(umo.svo_triples)   # [SVOTriple(subject="budget", verb="approved", object="initiatives")]
+print(umo.umo_id)        # "01KGE95Q4P9H89H63T26FNKKBR"
+```
+
+### Search for Meaning
+
+Find relevant memories with explanation:
+
+```python
+from datetime import datetime, timezone
+
+results = mi.umo.search(
+    "Q3 budget decisions",
+    user_ulid="01ABC...",
+    explain=True,
+    limit=5,
+    topics=["budget", "finance"],
+    date_from=datetime(2024, 1, 1, tzinfo=timezone.utc)
+)
+
+for result in results.results:
+    print(f"Score: {result.score:.2f}")
+    print(f"Summary: {result.umo.summary}")
+    if result.explain:
+        print(f"Why: {result.explain.human.summary}")
+```
+
+### Match for Recommendations
+
+Compare two memories for relevance:
+
+```python
+match = mi.umo.match(
+    source_ulid="01ABC...",
+    candidate_ulid="01XYZ...",
+    explain=True
+)
+
+print(f"Match score: {match.score}")
+print(f"Is match: {match.match}")
+if match.explain:
+    print(f"Reason: {match.explain.human.summary}")
+```
+
+### Get Explanations
+
+Understand why content is relevant:
+
+```python
+from memoryintelligence import ExplainLevel
+
+explanation = mi.umo.explain(
+    "01ABC...",
+    level=ExplainLevel.FULL
+)
+
+print(explanation.human.summary)
+print(explanation.human.key_reasons)
+print(explanation.audit.semantic_score)
+```
+
+### Delete Data
+
+GDPR-compliant data removal:
+
+```python
+from memoryintelligence import Scope
+
+result = mi.umo.delete(
+    user_ulid="01ABC...",
+    scope=Scope.USER
+)
+
+print(f"Deleted {result.deleted_count} memories")
+```
+
+## Async Support
+
+For async frameworks:
+
+```python
+from memoryintelligence import AsyncMemoryClient
+
+mi = AsyncMemoryClient(api_key="mi_sk_...")
+
+# Process
+umo = await mi.umo.process("Content", user_ulid="01ABC...")
+
+# Search with iteration
+async for result in mi.umo.search_iter("query", user_ulid="01ABC..."):
+    print(result.umo.summary)
+
+# Batch processing
+contents = ["Note 1", "Note 2", "Note 3"]
+results = await mi.umo.process_batch(contents, user_ulid="01ABC...")
+```
+
+## Edge Deployment (HIPAA/Air-gapped)
+
+For regulated industries:
+
+```python
+from memoryintelligence import EdgeClient
+
+# HIPAA-compliant edge deployment
+edge = EdgeClient(
+    endpoint="https://mi.internal.yourcompany.com",
+    api_key="mi_sk_...",
+    hipaa_mode=True
+)
+
+# Process locally (data never leaves)
+umo = edge.umo.process(clinical_note, user_ulid="01PATIENT...")
+
+# Air-gapped (no external calls)
+air_gapped = EdgeClient(
+    endpoint="https://mi.internal.com",
+    air_gapped=True  # No API key needed
+)
+```
+
+## Error Handling
+
+```python
+from memoryintelligence import (
+    MemoryClient,
+    LicenseError,
+    RateLimitError,
+    ValidationError,
+    AuthenticationError
+)
+
+try:
+    mi = MemoryClient(api_key="mi_sk_...")
+    umo = mi.umo.process("Content", user_ulid="01ABC...")
+except LicenseError as e:
+    print(f"License expired {e.days_expired} days ago")
+    print(f"Renew at: {e.renew_url}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except ValidationError as e:
+    print(f"Validation failed: {e.message}")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Webhook Verification
+
+```python
+from memoryintelligence import verify_webhook_signature
+
+# Verify webhook from Memory Intelligence
+is_valid = verify_webhook_signature(
+    payload=request_body,
+    signature=headers["X-MI-Signature"],
+    secret="whsec_..."
+)
+```
+
+## Monitoring & Telemetry
+
+The SDK provides built-in telemetry for operational visibility:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+### Key Log Events:
+- `DEBUG`: Content processing metrics (size, time)
+- `INFO`: Operation completion with results
+- `WARNING`: PII detection events
+- `ERROR`: API and integration errors
+
+## Configuration
+
+Environment variables:
+
+```bash
+# Required for persistent encryption
+export MI_ENCRYPTION_KEY="$(openssl rand -base64 32)"
+
+# API configuration
+export MI_API_KEY="mi_sk_live_..."
+export MI_BASE_URL="https://api.memoryintelligence.dev"
+```
+
+## Documentation
+
+Full documentation is available at:
+- [API Reference](https://docs.memoryintelligence.dev)
+- [Getting Started Guide](https://memoryintelligence.dev/docs/getting-started)
+
+## Support
+
+For SDK issues, please contact:
+- support@memoryintelligence.dev
+- GitHub Issues: [Create New Issue](https://github.com/memoryintelligence/sdk-python/issues/new)
+
+## License
+
+This SDK is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.