lians-sdk 0.1.3__tar.gz

lians_sdk-0.1.3/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.venv/
+venv/
+env/
+.env
+dist/
+build/
+*.whl
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Windows binaries / assemblies
+*.exe
+*.winmd
+*.dll
+*.pdb
+
+# Claude Code local settings
+.claude/
+
+# Internal working documents (not client-facing)
+SCALE.md
+BUILD.md
+MARKET.md
+
+# Personal files
+*.pdf
+
+# Node
+node_modules/

lians_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: lians-sdk
+Version: 0.1.3
+Summary: Financial-grade AI memory — bitemporal facts, SEC 17a-4 audit chain, GDPR crypto-shred
+Project-URL: Homepage, https://github.com/ebeirne/Lians
+Project-URL: Repository, https://github.com/ebeirne/Lians
+Project-URL: Documentation, https://github.com/ebeirne/Lians#readme
+License: Apache-2.0
+Keywords: agents,ai,bitemporal,compliance,crewai,finance,langchain,langgraph,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: all
+Requires-Dist: aiosqlite>=0.19; extra == 'all'
+Requires-Dist: autogen-core>=0.4; extra == 'all'
+Requires-Dist: crewai>=0.28; extra == 'all'
+Requires-Dist: httpx>=0.27.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2; extra == 'all'
+Requires-Dist: langgraph>=0.1; extra == 'all'
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: openai-agents>=0.0.1; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0; extra == 'all'
+Provides-Extra: autogen
+Requires-Dist: autogen-core>=0.4; extra == 'autogen'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.2; extra == 'langgraph'
+Requires-Dist: langgraph>=0.1; extra == 'langgraph'
+Provides-Extra: local
+Requires-Dist: aiosqlite>=0.19; extra == 'local'
+Requires-Dist: sqlalchemy>=2.0; extra == 'local'
+Provides-Extra: mcp
+Requires-Dist: httpx>=0.27.0; extra == 'mcp'
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.1; extra == 'openai-agents'
+Description-Content-Type: text/markdown
+
+# Lians (蓮)
+
+**Financial-grade AI memory** — bitemporal facts, SEC 17a-4 audit chain, GDPR crypto-shred.
+
+## Install
+
+```bash
+pip install lians-sdk          # HTTP client only
+pip install lians-sdk[local]        # + zero-setup SQLite mode (no server needed)
+pip install lians-sdk[langchain]    # + LangChain chat history & tools
+pip install lians-sdk[langgraph]    # + LangGraph node factories
+pip install lians-sdk[crewai]       # + CrewAI BaseTool wrappers
+pip install lians-sdk[openai-agents] # + OpenAI Agents SDK tools
+pip install lians-sdk[autogen]      # + AutoGen v0.4 tools
+pip install lians-sdk[all]          # Everything
+```
+
+## Quickstart
+
+```python
+from lians import LocalLiansClient
+from datetime import datetime, timezone
+
+mem = LocalLiansClient()  # no server, no Docker, no API key
+
+mem.add(
+    agent_id="analyst-1",
+    content="NVDA FY2026 revenue guidance raised to $40B",
+    event_time=datetime(2025, 11, 19, 16, tzinfo=timezone.utc),
+    metadata={"ticker": "NVDA", "metric": "revenue_guidance"},
+    importance=0.9,
+)
+
+# Superseded facts are excluded at the DB layer — LLM never sees stale data
+result = mem.recall(agent_id="analyst-1", query="NVDA revenue guidance")
+
+# Point-in-time: what did we know on March 1?
+result = mem.recall_at(
+    agent_id="analyst-1",
+    query="NVDA revenue guidance",
+    as_of=datetime(2025, 3, 1, tzinfo=timezone.utc),
+)
+
+# Extract memories directly from a conversation (like mem0.add(messages=[...]))
+mem.add_from_messages(
+    agent_id="analyst-1",
+    messages=[
+        {"role": "user",      "content": "What guidance did NVDA give?"},
+        {"role": "assistant", "content": "NVDA raised FY2026 revenue guidance to $40B."},
+    ],
+)
+```
+
+## What makes Lians different
+
+| Feature | Lians | mem0 | Graphiti/Zep |
+|---------|------|------|-------------|
+| Bitemporal model (event + ingestion time) | ✓ | ✗ | ✓ |
+| Supersession (stale facts excluded at DB layer) | ✓ | ✗ | Partial |
+| SEC 17a-4 tamper-evident audit chain | ✓ | ✗ | ✗ |
+| GDPR crypto-shred with audit survival | ✓ | ✗ | ✗ |
+| Information barriers (PostgreSQL RLS) | ✓ | ✗ | ✗ |
+| Backtest contamination detection | ✓ | ✗ | ✗ |
+
+## Framework integrations
+
+```python
+# LangChain
+from lians.langchain_integration import LiansChatHistory, build_tools
+
+# LangGraph
+from lians.langgraph_integration import create_recall_node, create_remember_node
+
+# CrewAI
+from lians.crewai_integration import build_crewai_tools
+
+# OpenAI Agents SDK
+from lians.openai_agents_integration import build_openai_agent_tools
+
+# AutoGen v0.4
+from lians.autogen_integration import build_autogen_tools
+```
+
+## Switching to hosted API
+
+```python
+# Dev (local SQLite, no server)
+from lians import LocalLiansClient
+mem = LocalLiansClient()
+
+# Production (self-hosted or managed)
+from lians import LiansClient
+mem = LiansClient(base_url="https://mem.yourfirm.internal", api_key="...")
+```
+
+Full documentation: [github.com/ebeirne/Lians](https://github.com/ebeirne/Lians)

lians_sdk-0.1.3/README.md

@@ -0,0 +1,96 @@
+# Lians (蓮)
+
+**Financial-grade AI memory** — bitemporal facts, SEC 17a-4 audit chain, GDPR crypto-shred.
+
+## Install
+
+```bash
+pip install lians-sdk          # HTTP client only
+pip install lians-sdk[local]        # + zero-setup SQLite mode (no server needed)
+pip install lians-sdk[langchain]    # + LangChain chat history & tools
+pip install lians-sdk[langgraph]    # + LangGraph node factories
+pip install lians-sdk[crewai]       # + CrewAI BaseTool wrappers
+pip install lians-sdk[openai-agents] # + OpenAI Agents SDK tools
+pip install lians-sdk[autogen]      # + AutoGen v0.4 tools
+pip install lians-sdk[all]          # Everything
+```
+
+## Quickstart
+
+```python
+from lians import LocalLiansClient
+from datetime import datetime, timezone
+
+mem = LocalLiansClient()  # no server, no Docker, no API key
+
+mem.add(
+    agent_id="analyst-1",
+    content="NVDA FY2026 revenue guidance raised to $40B",
+    event_time=datetime(2025, 11, 19, 16, tzinfo=timezone.utc),
+    metadata={"ticker": "NVDA", "metric": "revenue_guidance"},
+    importance=0.9,
+)
+
+# Superseded facts are excluded at the DB layer — LLM never sees stale data
+result = mem.recall(agent_id="analyst-1", query="NVDA revenue guidance")
+
+# Point-in-time: what did we know on March 1?
+result = mem.recall_at(
+    agent_id="analyst-1",
+    query="NVDA revenue guidance",
+    as_of=datetime(2025, 3, 1, tzinfo=timezone.utc),
+)
+
+# Extract memories directly from a conversation (like mem0.add(messages=[...]))
+mem.add_from_messages(
+    agent_id="analyst-1",
+    messages=[
+        {"role": "user",      "content": "What guidance did NVDA give?"},
+        {"role": "assistant", "content": "NVDA raised FY2026 revenue guidance to $40B."},
+    ],
+)
+```
+
+## What makes Lians different
+
+| Feature | Lians | mem0 | Graphiti/Zep |
+|---------|------|------|-------------|
+| Bitemporal model (event + ingestion time) | ✓ | ✗ | ✓ |
+| Supersession (stale facts excluded at DB layer) | ✓ | ✗ | Partial |
+| SEC 17a-4 tamper-evident audit chain | ✓ | ✗ | ✗ |
+| GDPR crypto-shred with audit survival | ✓ | ✗ | ✗ |
+| Information barriers (PostgreSQL RLS) | ✓ | ✗ | ✗ |
+| Backtest contamination detection | ✓ | ✗ | ✗ |
+
+## Framework integrations
+
+```python
+# LangChain
+from lians.langchain_integration import LiansChatHistory, build_tools
+
+# LangGraph
+from lians.langgraph_integration import create_recall_node, create_remember_node
+
+# CrewAI
+from lians.crewai_integration import build_crewai_tools
+
+# OpenAI Agents SDK
+from lians.openai_agents_integration import build_openai_agent_tools
+
+# AutoGen v0.4
+from lians.autogen_integration import build_autogen_tools
+```
+
+## Switching to hosted API
+
+```python
+# Dev (local SQLite, no server)
+from lians import LocalLiansClient
+mem = LocalLiansClient()
+
+# Production (self-hosted or managed)
+from lians import LiansClient
+mem = LiansClient(base_url="https://mem.yourfirm.internal", api_key="...")
+```
+
+Full documentation: [github.com/ebeirne/Lians](https://github.com/ebeirne/Lians)

lians_sdk-0.1.3/lians/__init__.py

@@ -0,0 +1,64 @@
+"""
+Lians Python SDK — financial-grade AI memory with compliance built in.
+
+Three clients, same API surface:
+
+    LiansClient        — synchronous HTTP client (scripts, CLIs)
+    AsyncLiansClient   — async HTTP client (FastAPI, async frameworks)
+    LocalLiansClient   — zero-setup local SQLite mode (prototyping, CI)
+
+Convenience methods on all clients::
+
+    client.add(agent_id, content, event_time, metadata=...)
+    client.add_from_messages(agent_id, messages=[{"role": "assistant", "content": "..."}])
+    client.recall(agent_id, query, k=5)
+    client.recall_at(agent_id, query, as_of=datetime(...))   # point-in-time / compliance
+    client.snapshot(agent_id, as_of=datetime(...))           # full knowledge state at T
+    client.backtest_check(agent_id, simulation_as_of=...)    # lookahead-bias detection
+    client.erase(subject_id, request_ref)                    # GDPR crypto-shred
+
+Framework integrations (optional extras)::
+
+    # LangChain (chat history + StructuredTools)
+    from lians.langchain_integration import LiansChatHistory, build_tools
+
+    # LangGraph (node factory functions)
+    from lians.langgraph_integration import create_recall_node, create_remember_node
+
+    # CrewAI (BaseTool wrappers)
+    from lians.crewai_integration import build_crewai_tools
+
+    # OpenAI Agents SDK (FunctionTool wrappers)
+    from lians.openai_agents_integration import build_openai_agent_tools
+
+    # AutoGen v0.4 (FunctionTool) / v0.2 (ConversableAgent)
+    from lians.autogen_integration import build_autogen_tools, build_autogen_functions
+
+Install with extras::
+
+    pip install lians-sdk[langchain]       # LangChain chat history + tools
+    pip install lians-sdk[langgraph]       # LangGraph node factories
+    pip install lians-sdk[crewai]          # CrewAI BaseTool wrappers
+    pip install lians-sdk[openai-agents]   # OpenAI Agents SDK FunctionTools
+    pip install lians-sdk[autogen]         # AutoGen v0.4 FunctionTools
+    pip install lians-sdk[local]           # LocalLiansClient (SQLite)
+    pip install lians-sdk[all]             # Everything
+"""
+from .sync_client import LiansClient
+from .client import AsyncLiansClient
+from .local_client import LocalLiansClient
+
+# Backward-compatibility aliases
+AgentMemClient = LiansClient
+AsyncAgentMemClient = AsyncLiansClient
+LocalAgentMemClient = LocalLiansClient
+
+__all__ = [
+    "LiansClient",
+    "AsyncLiansClient",
+    "LocalLiansClient",
+    # aliases
+    "AgentMemClient",
+    "AsyncAgentMemClient",
+    "LocalAgentMemClient",
+]

lians_sdk-0.1.3/lians/autogen_integration.py

@@ -0,0 +1,287 @@
+"""
+AutoGen v0.4 integration for Lians.
+
+Provides function tools for AutoGen agents (autogen-agentchat >= 0.4 /
+autogen-core >= 0.4).  Works with both the ConversableAgent and the newer
+AssistantAgent + function_tool pattern.
+
+Install::
+
+    pip install lians[autogen]
+    # or: pip install autogen-agentchat autogen-core
+
+Usage — AssistantAgent with function tools (AutoGen v0.4 async)::
+
+    from autogen_agentchat.agents import AssistantAgent
+    from autogen_ext.models import OpenAIChatCompletionClient
+    from lians import AsyncLiansClient
+    from lians.autogen_integration import build_autogen_tools
+
+    client = AsyncLiansClient(base_url="https://mem.firm.internal", api_key="...")
+    tools  = build_autogen_tools(client, agent_id="equity-desk")
+
+    model_client = OpenAIChatCompletionClient(model="gpt-4o")
+    agent = AssistantAgent(
+        name="EquityAnalyst",
+        model_client=model_client,
+        tools=tools,
+        system_message="You are an equity analyst with persistent compliance-grade memory.",
+    )
+
+Usage — ConversableAgent (AutoGen v0.2 / classic)::
+
+    from autogen import ConversableAgent
+    from lians import LocalLiansClient
+    from lians.autogen_integration import build_autogen_functions
+
+    client = LocalLiansClient()
+    functions, function_map = build_autogen_functions(client, agent_id="analyst")
+
+    agent = ConversableAgent(
+        name="analyst",
+        functions=functions,
+        function_map=function_map,
+    )
+
+Three tools are returned by build_autogen_tools():
+
+- ``agentmem_remember``    — store a fact with event timestamp and metadata
+- ``agentmem_recall``      — retrieve current facts by semantic search
+- ``agentmem_recall_at``   — retrieve facts valid at a specific past date (compliance)
+
+The ``agentmem_recall_at`` tool supports AutoGen multi-agent compliance workflows:
+"What did the risk-assessment agent know before the trade was placed?" — with a
+tamper-evident SHA-256 audit chain, not a probabilistic reconstruction.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime
+from typing import Any
+
+
+def build_autogen_tools(client: Any, agent_id: str) -> list:
+    """
+    Return three AutoGen v0.4 FunctionTool instances for AssistantAgent.
+
+    Parameters
+    ----------
+    client:
+        Any Lians client — ``LocalLiansClient``, ``LiansClient``, or
+        ``AsyncLiansClient``.  Async clients are detected automatically.
+    agent_id:
+        The agent namespace to read/write memories under.
+
+    Returns
+    -------
+    List of three AutoGen ``FunctionTool`` instances.
+
+    Raises
+    ------
+    ImportError
+        If ``autogen-core`` is not installed.
+        Install with: ``pip install lians[autogen]``
+    """
+    try:
+        from autogen_core.tools import FunctionTool  # type: ignore[import]
+    except ImportError:
+        raise ImportError(
+            "autogen-core is required for AutoGen integration.\n"
+            "Install with: pip install lians[autogen]\n"
+            "or: pip install autogen-core"
+        )
+
+    _is_async = asyncio.iscoroutinefunction(getattr(client, "recall", None))
+
+    def _fmt(memories: list[dict]) -> str:
+        if not memories:
+            return "No relevant memories found."
+        return "\n".join(
+            f"[{(m.get('event_time') or '')[:10]}] {m.get('content') or '[erased]'}"
+            for m in memories
+        )
+
+    def _run_maybe_async(coro: Any) -> Any:
+        if _is_async:
+            return asyncio.get_event_loop().run_until_complete(coro)
+        return coro  # already a plain value from sync client
+
+    # ── Tool functions ────────────────────────────────────────────────────────
+
+    async def agentmem_remember(
+        content: str,
+        event_time_iso: str,
+        metadata_json: str = "{}",
+        importance: float = 0.5,
+    ) -> str:
+        """
+        Store a fact in Lians persistent memory.
+
+        Use event_time_iso for when the event occurred (not now). Add structured
+        metadata for precision recall: ticker, metric, entity, source, jurisdiction.
+
+        Facts are AES-256-GCM encrypted at rest, written to a SHA-256 audit chain,
+        and automatically superseded when a newer value for the same entity+attribute
+        arrives — so recall always returns the current truth.
+
+        :param content: The fact or observation to store.
+        :param event_time_iso: ISO 8601 timestamp of when the event occurred.
+            Example: '2026-05-10T00:00:00Z'
+        :param metadata_json: JSON metadata tags.
+            Example: '{"ticker": "NVDA", "metric": "guidance"}'
+        :param importance: Salience 0.0–1.0. Default 0.5.
+        """
+        dt = datetime.fromisoformat(event_time_iso.replace("Z", "+00:00"))
+        meta = json.loads(metadata_json) if isinstance(metadata_json, str) else {}
+        kwargs: dict[str, Any] = dict(
+            agent_id=agent_id,
+            content=content,
+            event_time=dt,
+            metadata=meta,
+            importance=importance,
+            source="autogen",
+        )
+        if _is_async:
+            await client.add(**kwargs)
+        else:
+            client.add(**kwargs)
+        return f"Stored: {content[:120]}{'…' if len(content) > 120 else ''}"
+
+    async def agentmem_recall(query: str, k: int = 5) -> str:
+        """
+        Retrieve current relevant facts from Lians.
+
+        Superseded facts are excluded at the DB layer. Only the most recent
+        valid value for each fact is returned — your agent never sees stale context.
+
+        :param query: Natural-language query. Example: 'NVDA guidance FY2026'
+        :param k: Number of memories to return (1–20). Default 5.
+        """
+        if _is_async:
+            result = await client.recall(agent_id=agent_id, query=query, k=k)
+        else:
+            result = client.recall(agent_id=agent_id, query=query, k=k)
+        return _fmt(result.get("memories", []))
+
+    async def agentmem_recall_at(query: str, as_of_iso: str, k: int = 5) -> str:
+        """
+        Retrieve facts valid at a specific point in time (compliance/audit path).
+
+        Returns the exact knowledge state at the given timestamp — supports
+        out-of-order ingestion correctly. Use in multi-agent workflows where one
+        agent must reconstruct what another agent knew before a decision.
+
+        :param query: Natural-language query.
+        :param as_of_iso: ISO 8601 timestamp. Only facts valid at this moment
+            are returned. Example: '2026-03-01T00:00:00Z'
+        :param k: Number of memories to return (1–20). Default 5.
+        """
+        as_of = datetime.fromisoformat(as_of_iso.replace("Z", "+00:00"))
+        if _is_async:
+            result = await client.recall(agent_id=agent_id, query=query, k=k, as_of=as_of)
+        else:
+            result = client.recall(agent_id=agent_id, query=query, k=k, as_of=as_of)
+        return f"Facts valid as of {as_of_iso[:10]}:\n{_fmt(result.get('memories', []))}"
+
+    return [
+        FunctionTool(agentmem_remember, description=agentmem_remember.__doc__ or ""),
+        FunctionTool(agentmem_recall,   description=agentmem_recall.__doc__ or ""),
+        FunctionTool(agentmem_recall_at, description=agentmem_recall_at.__doc__ or ""),
+    ]
+
+
+def build_autogen_functions(
+    client: Any,
+    agent_id: str,
+) -> tuple[list[dict], dict[str, Any]]:
+    """
+    Return (functions_schema, function_map) for AutoGen v0.2 ConversableAgent.
+
+    The functions_schema list goes into the ``functions`` parameter; the
+    function_map dict goes into ``function_map``.
+
+    Parameters
+    ----------
+    client:
+        Any synchronous Lians client (LocalLiansClient or LiansClient).
+    agent_id:
+        The agent namespace to read/write memories under.
+
+    Returns
+    -------
+    A (list, dict) tuple compatible with ConversableAgent's ``functions`` and
+    ``function_map`` parameters.
+    """
+    def _fmt(memories: list[dict]) -> str:
+        if not memories:
+            return "No relevant memories found."
+        return "\n".join(
+            f"[{(m.get('event_time') or '')[:10]}] {m.get('content') or '[erased]'}"
+            for m in memories
+        )
+
+    def _remember(content: str, event_time_iso: str, metadata_json: str = "{}", importance: float = 0.5) -> str:
+        dt = datetime.fromisoformat(event_time_iso.replace("Z", "+00:00"))
+        meta = json.loads(metadata_json) if isinstance(metadata_json, str) else {}
+        client.add(agent_id=agent_id, content=content, event_time=dt, metadata=meta, importance=importance, source="autogen_v2")
+        return f"Stored: {content[:120]}"
+
+    def _recall(query: str, k: int = 5) -> str:
+        result = client.recall(agent_id=agent_id, query=query, k=k)
+        return _fmt(result.get("memories", []))
+
+    def _recall_at(query: str, as_of_iso: str, k: int = 5) -> str:
+        as_of = datetime.fromisoformat(as_of_iso.replace("Z", "+00:00"))
+        result = client.recall(agent_id=agent_id, query=query, k=k, as_of=as_of)
+        return f"Facts valid as of {as_of_iso[:10]}:\n{_fmt(result.get('memories', []))}"
+
+    functions = [
+        {
+            "name": "agentmem_remember",
+            "description": "Store a fact with its event timestamp in Lians persistent memory.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "content":        {"type": "string", "description": "The fact to remember."},
+                    "event_time_iso": {"type": "string", "description": "ISO 8601 event timestamp."},
+                    "metadata_json":  {"type": "string", "description": "JSON metadata tags.", "default": "{}"},
+                    "importance":     {"type": "number", "description": "Salience 0–1.", "default": 0.5},
+                },
+                "required": ["content", "event_time_iso"],
+            },
+        },
+        {
+            "name": "agentmem_recall",
+            "description": "Retrieve current relevant facts from Lians (superseded facts excluded).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "k":     {"type": "integer", "default": 5},
+                },
+                "required": ["query"],
+            },
+        },
+        {
+            "name": "agentmem_recall_at",
+            "description": "Retrieve facts valid at a specific timestamp (compliance / audit path).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query":       {"type": "string"},
+                    "as_of_iso":   {"type": "string", "description": "ISO 8601 timestamp."},
+                    "k":           {"type": "integer", "default": 5},
+                },
+                "required": ["query", "as_of_iso"],
+            },
+        },
+    ]
+
+    function_map = {
+        "agentmem_remember": _remember,
+        "agentmem_recall":   _recall,
+        "agentmem_recall_at": _recall_at,
+    }
+
+    return functions, function_map