memoryintelligence 1.0.0__tar.gz

memoryintelligence-1.0.0/LICENSE

@@ -0,0 +1,31 @@
+MIT License with Attribution Requirement
+
+Copyright (c) 2026 Memory Intelligence
+
+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:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. Applications using this SDK MUST display "Powered by Memory Intelligence" 
+   attribution in their user interface or documentation.
+
+3. This SDK may only be used to interact with official Memory Intelligence API 
+   services. No reverse engineering of the API or unauthorized replication of 
+   the service is permitted.
+
+4. API access credentials (API keys) are non-transferable and may not be 
+   resold or sublicensed.
+
+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.

memoryintelligence-1.0.0/PKG-INFO

@@ -0,0 +1,428 @@
+Metadata-Version: 2.4
+Name: memoryintelligence
+Version: 1.0.0
+Summary: Official Python SDK for Memory Intelligence - Verifiable meaning infrastructure for AI
+Author-email: Memory Intelligence Team <sdk@memoryintelligence.dev>
+Maintainer-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,nlp,privacy,compliance,hipaa,gdpr,provenance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+## Memory Intelligence Python SDK
+
+Official Python client for building applications, agents, integrations, and data pipelines on top of the Memory Intelligence OS.
+
+The Python SDK provides a full-featured interface for interacting with the Memory Intelligence Operating System (MemoryOS).
+It is optimized for:
+	•	backend services
+	•	data ingestion pipelines
+	•	ML research & evaluation
+	•	analytics & ETL
+	•	agent development
+	•	enterprise automation workflows
+
+It supports both sync and async usage, enforces all governance + privacy rules, and provides high-level helpers for working with UMOs, search, timelines, clusters, provenance, and agents.
+
+(This README supersedes and expands the minimal starter at:  )
+
+⸻
+
+1. Features
+
+Meaning-First API Surface
+	•	Native UMO creation
+	•	Semantic + hybrid search
+	•	Timeline querying
+	•	Graph neighborhood expansion
+	•	Cluster & drift detection access
+	•	Agent execution (summaries, insights, narratives)
+
+Production-Ready Network Layer
+	•	Sync + Async clients
+	•	Automatic retries with exponential backoff
+	•	Connection pooling
+	•	Circuit-breaking & timeouts
+	•	Request tracing (observability)
+	•	Structured logging helpers
+
+Governance + Privacy Enforcement
+	•	Automatic conversion of external IDs → ULIDs
+	•	Masking of governed fields
+	•	Provenance hashing (SHA-256)
+	•	Tenant isolation
+	•	No raw identity leakage
+
+Developer Ergonomics
+	•	Type hints
+	•	Pydantic models
+	•	Exceptions for precise error handling
+	•	Response validation
+	•	Extensible middleware
+
+Advanced SDK Extensions
+	•	Bulk ingestion helpers
+	•	Batch export helpers
+	•	Local capture queue (offline-first ingestion)
+	•	Evaluation tools for embeddings & search quality
+
+⸻
+
+2. Installation
+
+pip install memory-intelligence
+
+Or install from source for development:
+
+pip install -e .
+
+
+⸻
+
+3. Initialization
+
+from memory_intelligence import MemoryClient
+
+client = MemoryClient(
+    api_key="YOUR_API_KEY",
+    api_url="https://api.memory-intelligence.com"
+)
+
+You may also configure via environment variables:
+
+MI_API_KEY=...
+MI_API_URL=https://api.memory-intelligence.com
+
+
+⸻
+
+4. Core Concepts
+
+Unified Memory Objects (UMOs)
+
+UMOs are the canonical memory format inside MemoryOS.
+
+The SDK automatically validates UMO structure and can create them from:
+	•	text
+	•	audio transcription text
+	•	images (OCR text)
+	•	URLs (browser captures)
+	•	JSON capture envelopes
+	•	Slack/email ingestion payloads
+
+The SDK ensures:
+	•	correct schema
+	•	correct timestamp formats
+	•	correct ULID identity boundaries
+	•	correct provenance hashing
+
+⸻
+
+5. Creating Memories
+
+Simple Text Memory
+
+umo = client.memories.create(
+    content="Had a meeting about Q2 product roadmap.",
+    tags=["meeting", "planning"]
+)
+
+With Additional Metadata
+
+umo = client.memories.create(
+    content="User feedback from onboarding session.",
+    context={"channel": "support", "sentiment": "positive"},
+    source="manual"
+)
+
+With Provenance Hash Override
+
+umo = client.memories.create(
+    content="Draft article notes.",
+    provenance_hash="abc123...",  # optional if you compute your own
+)
+
+
+⸻
+
+6. Searching Memories
+
+Semantic Search
+
+results = client.search.semantic("project planning")
+
+Hybrid Search (semantic + lexical + temporal)
+
+results = client.search.hybrid(
+    query="customer retention initiative",
+    limit=20,
+)
+
+Entity-Based Filtering
+
+results = client.search.by_entity("OpenAI", limit=10)
+
+Graph Neighborhood Expansion
+
+neighbors = client.graph.neighbors(umo_id="01F...")
+
+
+⸻
+
+7. Timeline Queries
+
+timeline = client.timeline.range(
+    start="2025-01-01",
+    end="2025-02-01",
+    sort="chronological"
+)
+
+Or retrieve the significance-ranked resurfacing window:
+
+resurfaced = client.timeline.resurface(limit=15)
+
+
+⸻
+
+8. Inspecting UMOs
+
+umo = client.memories.get("01H...")    # fetch a UMO
+print(umo.meaning.entities)            # inspect meaning
+print(umo.provenance.hash)             # provenance integrity
+
+Diffing UMO Versions
+
+diff = client.memories.diff("01H...", version_a=1, version_b=3)
+
+
+⸻
+
+9. Agents API (Summaries, Insights, Narrative)
+
+Generate a summary
+
+summary = client.agents.summarize(umo_id="01H...")
+
+Generate insights across a collection
+
+insights = client.agents.generate_insights(collection_id="col_123")
+
+Narrative generation
+
+narrative = client.agents.narrative(umo_ids=["01H..", "01H.."])
+
+
+⸻
+
+10. Working With Collections
+
+col = client.collections.create(name="Research Notes")
+
+client.collections.add(
+    collection_id=col.id,
+    umo_id="01H..."
+)
+
+Fetch:
+
+items = client.collections.get(col.id)
+
+
+⸻
+
+11. Async Usage
+
+From the original file expanded:
+
+import asyncio
+from memory_intelligence import MemoryAsyncClient
+
+async def main():
+    async with MemoryAsyncClient(api_key="YOUR_KEY") as client:
+        results = await client.search.semantic("product planning")
+        print(results)
+
+asyncio.run(main())
+
+Async client supports:
+	•	connection pooling
+	•	concurrent searches
+	•	async streaming (roadmap)
+
+⸻
+
+12. Bulk & Batch Operations
+
+Batch Ingestion
+
+batch = [
+    {"content": "Interview notes …"},
+    {"content": "Email summary …"},
+    {"content": "Research excerpt …"},
+]
+
+client.bulk.ingest(batch)
+
+Batch Export
+
+data = client.bulk.export(
+    since="2024-01-01",
+    include_provenance=True
+)
+
+
+⸻
+
+13. Error Handling
+
+from memory_intelligence.errors import (
+    AuthenticationError,
+    ValidationError,
+    GovernanceViolation,
+    RateLimitExceeded,
+    ServerError
+)
+
+try:
+    client.memories.create(content=None)
+except ValidationError as e:
+    print("Invalid memory:", e)
+
+Each exception type includes:
+	•	error code
+	•	human-friendly message
+	•	context metadata
+	•	retry hints (when applicable)
+
+⸻
+
+14. Observability & Logging
+
+Attach middleware:
+
+from memory_intelligence.middlewares import LoggingMiddleware
+
+client = MemoryClient(
+    api_key="...",
+    middlewares=[LoggingMiddleware()]
+)
+
+Each request emits:
+	•	trace_id
+	•	span_id
+	•	duration_ms
+	•	HTTP code
+	•	retry count (if applicable)
+
+Compatible with:
+	•	OpenTelemetry
+	•	Datadog
+	•	New Relic
+
+⸻
+
+15. Governance Compliance in the SDK
+
+The SDK automatically:
+	•	strips forbidden identity fields
+	•	maps external IDs → ULIDs
+	•	masks governed entities
+	•	prevents raw external identifiers from being sent
+	•	computes SHA-256 provenance hashes
+	•	prevents accidental schema violations
+
+This guarantees MemoryOS receives clean, safe, meaning-aligned data.
+
+⸻
+
+16. Local Capture Queue (Optional)
+
+For offline or burst ingestion:
+
+queue = client.capture_queue()
+
+queue.enqueue({"content": "Field note"})
+queue.enqueue({"content": "Another note"})
+
+queue.flush()  # uploads in batches
+
+Provides:
+	•	crash-safe local disk persistence
+	•	idempotent sync
+	•	backpressure control
+
+⸻
+
+17. Development Utilities
+
+Validate a UMO
+
+from memory_intelligence import validate_umo
+
+validate_umo(umo_dict)
+
+Encode/Decode ULIDs
+
+from memory_intelligence import ULID
+
+ulid = ULID.new()
+
+Compute a provenance hash
+
+from memory_intelligence import compute_hash
+
+h = compute_hash("some content")
+
+
+⸻
+
+18. Roadmap
+
+Upcoming Python SDK features:
+	•	streaming search results
+	•	async agent pipelines
+	•	local meaning snapshot cache
+	•	automatic retry queues
+	•	timeline diff utilities
+	•	embedding evaluation toolkit
+
+⸻
+
+19. Summary
+
+The Memory Intelligence Python SDK is the foundation for:
+	•	ingestion pipelines
+	•	application backends
+	•	research tooling
+	•	enterprise workflows
+	•	agent development
+	•	governance-safe meaning retrieval
+
+It abstracts the complexity of MemoryOS, Engines, Identity, Governance, and Platform layers—providing a meaning-first, privacy-first, developer-friendly interface for building the next generation of memory-driven applications.
+
+⸻