memmachine-client 0.3.8__tar.gz → 0.4.0__tar.gz

{memmachine_client-0.3.8/src/memmachine_client.egg-info → memmachine_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memmachine-client
-Version: 0.3.8
+Version: 0.4.0
 Summary: MemMachine REST Client - A lightweight Python client library for MemMachine memory system
 Author-email: MemMachine <noreply@memmachine.ai>
 License-Expression: Apache-2.0
@@ -39,11 +39,15 @@ A Python client library for the MemMachine memory system.
 ## Installation
 
 ```bash
-# Install from source (for development)
-pip install -e .
+pip install memmachine-client
+```
+
+### Development installation
+
+If you are working on the package locally inside the MemMachine monorepo, install it from source instead:
 
-# Or install dependencies
-pip install requests urllib3
+```bash
+pip install -e packages/client
 ```
 
 ## Quick Start
@@ -54,17 +58,11 @@ pip install requests urllib3
 from memmachine_client import MemMachineClient
 
 # Initialize client
-client = MemMachineClient(
-    base_url="http://localhost:8080",
-    timeout=30
-)
+client = MemMachineClient(base_url="http://localhost:8080", timeout=30)
 
 # Create a memory instance
 memory = client.memory(
-    group_id="my_group",
-    agent_id="my_agent",
-    user_id="user123",
-    session_id="session456"
+    group_id="my_group", agent_id="my_agent", user_id="user123", session_id="session456"
 )
 
 # Add memories
@@ -123,21 +121,23 @@ memory = client.memory(
     group_id="demo_group",
     agent_id="demo_agent",
     user_id="user123",
-    session_id="demo_session"
+    session_id="demo_session",
 )
 
 # Add memories with metadata
 memory.add("I like pizza", metadata={"type": "preference", "category": "food"})
-memory.add("I work as a software engineer", metadata={"type": "fact", "category": "work"})
+memory.add(
+    "I work as a software engineer", metadata={"type": "fact", "category": "work"}
+)
 
-# Search memories
+# Search memories — Memory.search() returns a SearchResult Pydantic model
 results = memory.search("What do I like to eat?")
-print(f"Episodic memory: {results.get('episodic_memory', [])}")
-print(f"Profile memory: {results.get('profile_memory', [])}")
+print(f"Episodic memory: {results.content.episodic_memory}")
+print(f"Semantic memory: {results.content.semantic_memory}")
 
-# Search with filters
-work_results = memory.search("Tell me about work", filter_dict={"category": "work"})
-print(f"Work results: {work_results}")
+# Search with filters (user metadata fields require the `m.` / `metadata.` prefix)
+work_results = memory.search("Tell me about work", filter_dict={"m.category": "work"})
+print(f"Work results: {work_results.model_dump()}")
 ```
 
 ### Multiple Users
@@ -153,9 +153,7 @@ memories = {}
 
 for user in users:
     memories[user] = client.memory(
-        group_id="team_group",
-        agent_id="team_agent",
-        user_id=user
+        group_id="team_group", agent_id="team_agent", user_id=user
     )
 
 # Add user-specific memories
@@ -183,9 +181,7 @@ try:
 
     # Create memory instance
     memory = client.memory(
-        group_id="demo_group",
-        agent_id="demo_agent",
-        user_id="user123"
+        group_id="demo_group", agent_id="demo_agent", user_id="user123"
     )
 
     # Add memory
@@ -203,9 +199,7 @@ from memmachine_client import MemMachineClient
 # Use client as context manager
 with MemMachineClient(base_url="http://localhost:8080") as client:
     memory = client.memory(
-        group_id="demo_group",
-        agent_id="demo_agent",
-        user_id="user123"
+        group_id="demo_group", agent_id="demo_agent", user_id="user123"
     )
 
     memory.add("This is a test memory")
@@ -229,7 +223,7 @@ client = MemMachineClient(
     api_key="your_api_key",  # Optional
     base_url="http://localhost:8080",
     timeout=30,  # Request timeout in seconds
-    max_retries=3  # Maximum retries for failed requests
+    max_retries=3,  # Maximum retries for failed requests
 )
 ```
 

{memmachine_client-0.3.8 → memmachine_client-0.4.0}/README.md

@@ -13,11 +13,15 @@ A Python client library for the MemMachine memory system.
 ## Installation
 
 ```bash
-# Install from source (for development)
-pip install -e .
+pip install memmachine-client
+```
+
+### Development installation
+
+If you are working on the package locally inside the MemMachine monorepo, install it from source instead:
 
-# Or install dependencies
-pip install requests urllib3
+```bash
+pip install -e packages/client
 ```
 
 ## Quick Start
@@ -28,17 +32,11 @@ pip install requests urllib3
 from memmachine_client import MemMachineClient
 
 # Initialize client
-client = MemMachineClient(
-    base_url="http://localhost:8080",
-    timeout=30
-)
+client = MemMachineClient(base_url="http://localhost:8080", timeout=30)
 
 # Create a memory instance
 memory = client.memory(
-    group_id="my_group",
-    agent_id="my_agent",
-    user_id="user123",
-    session_id="session456"
+    group_id="my_group", agent_id="my_agent", user_id="user123", session_id="session456"
 )
 
 # Add memories
@@ -97,21 +95,23 @@ memory = client.memory(
     group_id="demo_group",
     agent_id="demo_agent",
     user_id="user123",
-    session_id="demo_session"
+    session_id="demo_session",
 )
 
 # Add memories with metadata
 memory.add("I like pizza", metadata={"type": "preference", "category": "food"})
-memory.add("I work as a software engineer", metadata={"type": "fact", "category": "work"})
+memory.add(
+    "I work as a software engineer", metadata={"type": "fact", "category": "work"}
+)
 
-# Search memories
+# Search memories — Memory.search() returns a SearchResult Pydantic model
 results = memory.search("What do I like to eat?")
-print(f"Episodic memory: {results.get('episodic_memory', [])}")
-print(f"Profile memory: {results.get('profile_memory', [])}")
+print(f"Episodic memory: {results.content.episodic_memory}")
+print(f"Semantic memory: {results.content.semantic_memory}")
 
-# Search with filters
-work_results = memory.search("Tell me about work", filter_dict={"category": "work"})
-print(f"Work results: {work_results}")
+# Search with filters (user metadata fields require the `m.` / `metadata.` prefix)
+work_results = memory.search("Tell me about work", filter_dict={"m.category": "work"})
+print(f"Work results: {work_results.model_dump()}")
 ```
 
 ### Multiple Users
@@ -127,9 +127,7 @@ memories = {}
 
 for user in users:
     memories[user] = client.memory(
-        group_id="team_group",
-        agent_id="team_agent",
-        user_id=user
+        group_id="team_group", agent_id="team_agent", user_id=user
     )
 
 # Add user-specific memories
@@ -157,9 +155,7 @@ try:
 
     # Create memory instance
     memory = client.memory(
-        group_id="demo_group",
-        agent_id="demo_agent",
-        user_id="user123"
+        group_id="demo_group", agent_id="demo_agent", user_id="user123"
     )
 
     # Add memory
@@ -177,9 +173,7 @@ from memmachine_client import MemMachineClient
 # Use client as context manager
 with MemMachineClient(base_url="http://localhost:8080") as client:
     memory = client.memory(
-        group_id="demo_group",
-        agent_id="demo_agent",
-        user_id="user123"
+        group_id="demo_group", agent_id="demo_agent", user_id="user123"
     )
 
     memory.add("This is a test memory")
@@ -203,7 +197,7 @@ client = MemMachineClient(
     api_key="your_api_key",  # Optional
     base_url="http://localhost:8080",
     timeout=30,  # Request timeout in seconds
-    max_retries=3  # Maximum retries for failed requests
+    max_retries=3,  # Maximum retries for failed requests
 )
 ```
 

memmachine_client-0.4.0/client_tests/test_cli.py

@@ -0,0 +1,265 @@
+"""Tests for the MemMachine command line client."""
+
+import sys
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+from pydantic import BaseModel
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from memmachine_client import cli
+
+
+class CliResult(BaseModel):
+    """Small Pydantic test result."""
+
+    uid: str
+
+
+def test_pyproject_installs_command_name():
+    """Editable installs should expose the documented mem-cli command."""
+    pyproject = tomllib.loads(
+        (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text()
+    )
+
+    assert pyproject["project"]["scripts"]["mem-cli"] == ("memmachine_client.cli:main")
+
+
+def test_build_client_uses_args_over_environment(monkeypatch):
+    """Command arguments should override environment variables."""
+    monkeypatch.setenv("MEMORY_BACKEND_URL", "http://env:8080")
+    monkeypatch.setenv("MEMMACHINE_API_KEY", "env-key")
+    monkeypatch.setenv("MEMMACHINE_TIMEOUT", "10")
+    monkeypatch.setenv("MEMMACHINE_MAX_RETRIES", "2")
+
+    args = cli.build_parser().parse_args(
+        [
+            "--base-url",
+            "http://arg:8080",
+            "--api-key",
+            "arg-key",
+            "--timeout",
+            "20",
+            "--max-retries",
+            "4",
+            "health",
+        ]
+    )
+
+    client = cli.build_client(args)
+
+    assert client.base_url == "http://arg:8080"
+    assert client.api_key == "arg-key"
+    assert client.timeout == 20
+    assert client.max_retries == 4
+
+
+def test_build_client_requires_base_url(monkeypatch):
+    """The CLI should fail clearly when base_url is unavailable."""
+    monkeypatch.delenv("MEMORY_BACKEND_URL", raising=False)
+
+    args = cli.build_parser().parse_args(["health"])
+
+    with pytest.raises(SystemExit) as exc:
+        cli.build_client(args)
+
+    assert exc.value.code == 2
+
+
+def test_parser_help_uses_installed_command_name(capsys):
+    """Help output should match the documented console script."""
+    with pytest.raises(SystemExit) as exc:
+        cli.build_parser().parse_args(["--help"])
+
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.startswith("usage: mem-cli ")
+
+
+def test_custom_errors_use_parser_program_name(monkeypatch, capsys):
+    """Custom errors should use the same program name as argparse."""
+    monkeypatch.delenv("MEMORY_BACKEND_URL", raising=False)
+
+    args = cli.build_parser().parse_args(["health"])
+
+    with pytest.raises(SystemExit) as exc:
+        cli.build_client(args)
+
+    assert exc.value.code == 2
+    assert capsys.readouterr().err == (
+        "mem-cli: error: --base-url or MEMORY_BACKEND_URL is required\n"
+    )
+
+
+def test_health_command_prints_json(capsys):
+    """The health command should call the underlying client."""
+    client = Mock()
+    client.health_check.return_value = {"status": "healthy"}
+
+    result = cli.run_command(client, cli.build_parser().parse_args(["health"]))
+
+    assert result == 0
+    client.health_check.assert_called_once_with(timeout=None)
+    assert capsys.readouterr().out == '{\n  "status": "healthy"\n}\n'
+
+
+def test_memory_add_uses_env_project_context(monkeypatch, capsys):
+    """Memory commands should accept project context from the environment."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock()
+    memory = Mock()
+    memory.add.return_value = [CliResult(uid="mem-1")]
+    project.memory.return_value = memory
+    client.get_project.return_value = project
+
+    args = cli.build_parser().parse_args(
+        ["memory", "add", "hello", "--metadata", "user_id=user-1"]
+    )
+
+    exit_code = cli.run_command(client, args)
+
+    assert exit_code == 0
+    client.get_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        timeout=None,
+    )
+    project.memory.assert_called_once_with(metadata={"user_id": "user-1"})
+    memory.add.assert_called_once_with(
+        "hello",
+        role="",
+        producer=None,
+        produced_for=None,
+        metadata=None,
+        timeout=None,
+    )
+    assert capsys.readouterr().out == '[\n  {\n    "uid": "mem-1"\n  }\n]\n'
+
+
+@pytest.mark.parametrize(
+    ("argv", "memory_method"),
+    [
+        (["memory", "search", "hello"], "search"),
+        (["memory", "list"], "list"),
+        (["memory", "delete-episodic", "--id", "episode-1"], "delete_episodic"),
+        (["memory", "delete-semantic", "--id", "semantic-1"], "delete_semantic"),
+    ],
+)
+def test_memory_subcommands_use_env_project_context(
+    argv, memory_method, monkeypatch, capsys
+):
+    """Memory subcommands should resolve project context through the shared helper."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock()
+    memory = Mock()
+    getattr(memory, memory_method).return_value = (
+        True if memory_method.startswith("delete_") else []
+    )
+    project.memory.return_value = memory
+    client.get_project.return_value = project
+
+    args = cli.build_parser().parse_args(argv)
+
+    assert cli.run_command(client, args) == 0
+    client.get_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        timeout=None,
+    )
+    project.memory.assert_called_once_with(metadata={})
+    assert capsys.readouterr().out
+
+
+def test_delete_episodic_cli_with_ids_only(monkeypatch, capsys):
+    """Batch-only CLI deletion should omit the single episodic ID."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    memory = client.get_project.return_value.memory.return_value
+    memory.delete_episodic.return_value = True
+    episode_id = "550e8400-e29b-41d4-a716-446655440001"
+    args = cli.build_parser().parse_args(
+        ["memory", "delete-episodic", "--ids", episode_id]
+    )
+
+    assert cli.run_command(client, args) == 0
+    memory.delete_episodic.assert_called_once_with(
+        episodic_id=None, episodic_ids=[episode_id], timeout=None
+    )
+    assert capsys.readouterr().out
+
+
+def test_delete_semantic_cli_with_ids_only(monkeypatch, capsys):
+    """The semantic command should retain its empty single-ID default."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    memory = client.get_project.return_value.memory.return_value
+    memory.delete_semantic.return_value = True
+    args = cli.build_parser().parse_args(
+        ["memory", "delete-semantic", "--ids", "semantic-1"]
+    )
+
+    assert cli.run_command(client, args) == 0
+    memory.delete_semantic.assert_called_once_with(
+        semantic_id="", semantic_ids=["semantic-1"], timeout=None
+    )
+    assert capsys.readouterr().out
+
+
+def test_projects_create_uses_env_project_context(monkeypatch, capsys):
+    """Project create should accept project context from the environment."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock(
+        org_id="env-org",
+        project_id="env-project",
+        description="",
+        config={},
+    )
+    client.create_project.return_value = project
+
+    args = cli.build_parser().parse_args(["projects", "create"])
+
+    exit_code = cli.run_command(client, args)
+
+    assert exit_code == 0
+    client.create_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        description="",
+        embedder="",
+        reranker="",
+        timeout=None,
+    )
+    assert capsys.readouterr().out == (
+        "{\n"
+        '  "config": {},\n'
+        '  "description": "",\n'
+        '  "org_id": "env-org",\n'
+        '  "project_id": "env-project"\n'
+        "}\n"
+    )
+
+
+@patch("memmachine_client.cli.MemMachineClient")
+def test_main_closes_client(mock_client_class, monkeypatch):
+    """The top-level entry point should close the client after command execution."""
+    monkeypatch.setenv("MEMORY_BACKEND_URL", "http://localhost:8080")
+    client = Mock()
+    client.health_check.return_value = {"status": "healthy"}
+    mock_client_class.return_value = client
+
+    exit_code = cli.main(["health"])
+
+    assert exit_code == 0
+    client.close.assert_called_once_with()

{memmachine_client-0.3.8 → memmachine_client-0.4.0}/client_tests/test_client.py

@@ -1,6 +1,7 @@
 """Unit tests for MemMachineClient class (v2 API)."""
 
 from unittest.mock import Mock, patch
+from uuid import UUID
 
 import pytest
 import requests
@@ -8,6 +9,8 @@ from memmachine_common.api import MemoryType
 
 from memmachine_client import MemMachineClient, Memory, Project
 
+EPISODE_UID = "550e8400-e29b-41d4-a716-446655440001"
+
 
 class TestMemMachineClient:
     """Test cases for MemMachineClient."""
@@ -206,6 +209,97 @@ class TestMemMachineClient:
                 project_id="test_project",
             )
 
+    def test_create_project_event_backend_fields_reach_wire(self):
+        """Event-backend fields must reach the wire — without this the SDK
+        has no supported path to event-backed projects."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = Mock()
+        mock_response.json.return_value = {
+            "org_id": "test_org",
+            "project_id": "test_project",
+            "description": "",
+            "config": {
+                "backend": "event",
+                "embedder": "default",
+                "reranker": "default",
+                "vector_store": "qdrant_vs",
+                "segment_store": "sqlite_db",
+                "properties_schema": {"customer_tier": "str"},
+            },
+        }
+        with patch.object(
+            client._session, "post", return_value=mock_response
+        ) as mock_post:
+            client.create_project(
+                org_id="test_org",
+                project_id="test_project",
+                backend="event",
+                vector_store="qdrant_vs",
+                segment_store="sqlite_db",
+                properties_schema={"customer_tier": "str"},
+            )
+            cfg = mock_post.call_args[1]["json"]["config"]
+            assert cfg["backend"] == "event"
+            assert cfg["vector_store"] == "qdrant_vs"
+            assert cfg["segment_store"] == "sqlite_db"
+            assert cfg["properties_schema"] == {"customer_tier": "str"}
+
+    def test_get_project_404_raises_http_error(self):
+        """Test missing project preserves HTTPError semantics."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        mock_response = Mock()
+        mock_response.status_code = 404
+        http_error = requests.HTTPError(response=mock_response)
+        mock_response.raise_for_status.side_effect = http_error
+
+        with (
+            patch.object(client, "request", return_value=mock_response),
+            pytest.raises(requests.HTTPError) as exc_info,
+        ):
+            client.get_project(org_id="test_org", project_id="missing_project")
+
+        assert exc_info.value is http_error
+        assert exc_info.value.response.status_code == 404
+
+    def test_get_or_create_project_creates_after_get_404(self):
+        """Test missing project is created by get_or_create_project."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        get_response = Mock()
+        get_response.status_code = 404
+        get_response.raise_for_status.side_effect = requests.HTTPError(
+            response=get_response
+        )
+
+        create_response = Mock()
+        create_response.status_code = 200
+        create_response.raise_for_status = Mock()
+        create_response.json.return_value = {
+            "org_id": "test_org",
+            "project_id": "new_project",
+            "description": "Created project",
+            "config": {"embedder": "", "reranker": ""},
+        }
+
+        with (
+            patch.object(client, "request", return_value=get_response) as mock_request,
+            patch.object(
+                client._session, "post", return_value=create_response
+            ) as mock_post,
+        ):
+            project = client.get_or_create_project(
+                org_id="test_org",
+                project_id="new_project",
+                description="Created project",
+            )
+
+        assert project.org_id == "test_org"
+        assert project.project_id == "new_project"
+        assert project.description == "Created project"
+        mock_request.assert_called_once()
+        mock_post.assert_called_once()
+
     @patch("requests.Session.get")
     def test_health_check_success(self, mock_get):
         """Test successful health check."""
@@ -360,14 +454,13 @@ class TestMemory:
             "content": {
                 "episodic_memory": [
                     {
-                        "uid": "e1",
+                        "uid": EPISODE_UID,
                         "content": "hello",
                         "session_key": "org1/proj1",
                         "created_at": "2025-01-01T00:00:00Z",
                         "producer_id": "u1",
                         "producer_role": "user",
                         "produced_for_id": None,
-                        "sequence_num": 0,
                         "episode_type": "message",
                         "content_type": "string",
                         "filterable_metadata": None,
@@ -402,7 +495,7 @@ class TestMemory:
 
             assert isinstance(result, ListResult)
             assert result.content.episodic_memory is not None
-            assert result.content.episodic_memory[0].uid == "e1"
+            assert result.content.episodic_memory[0].uid == UUID(EPISODE_UID)
             assert result.content.semantic_memory == []