cognitive-memory-layer 0.1.0__tar.gz

cognitive_memory_layer-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

cognitive_memory_layer-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+
+# Caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage

cognitive_memory_layer-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.0, httpx>=0.27]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files

cognitive_memory_layer-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+#### Phase 1: Project setup
+- Initial project structure and build configuration (Hatchling, src layout)
+- Package `cml` with sync and async client classes (`CognitiveMemoryLayer`, `AsyncCognitiveMemoryLayer`)
+- Development tooling: ruff, mypy, pytest, pre-commit, editorconfig
+- CI workflows: py-cml-test (Python 3.11–3.13), py-cml-lint, py-cml-publish (on `py-cml-v*` tags)
+- README, CONTRIBUTING, and CHANGELOG
+
+#### Phase 2: Core client SDK
+- **Configuration:** Pydantic `CMLConfig` with validation; loading from direct params, env vars (`CML_*`), and `.env` (python-dotenv)
+- **Exceptions:** Full hierarchy — `CMLError` (with `status_code`, `response_body`), `AuthenticationError`, `AuthorizationError`, `NotFoundError`, `ValidationError`, `RateLimitError` (with `retry_after`), `ServerError`, `ConnectionError`, `TimeoutError`
+- **Transport:** Sync `HTTPTransport` and async `AsyncHTTPTransport` (httpx), path prefix `/api/v1`, standard headers (API key, tenant ID, User-Agent), status-code mapping to exceptions
+- **Retry:** Exponential backoff with jitter for 5xx, 429, connection, and timeout; `RateLimitError` respects `Retry-After` header; retry integrated in transport `request()`
+- **Models:** Enums `MemoryType`, `MemoryStatus`, `MemorySource`, `OperationType`; request models (`WriteRequest`, `ReadRequest`, `TurnRequest`, `UpdateRequest`, `ForgetRequest`); response models (`HealthResponse`, `WriteResponse`, `ReadResponse`, `TurnResponse`, etc., `MemoryItem`)
+- **Clients:** Context manager support (`with` / `async with`), `close()`, `health()` returning `HealthResponse`
+- Unit tests for config, exceptions, retry, transport (mocked), and client health (29 tests)
+
+#### Phase 3: Memory operations
+- **Memory API:** `write`, `read`, `turn`, `update`, `forget`, `stats` on both sync and async clients
+- **Sessions:** `create_session`, `get_session_context`; request/response models `CreateSessionRequest`, `SessionContextResponse`
+- **Convenience:** `get_context` (read with format=llm_context), `remember` (alias for write), `search` (alias for read)
+- **Admin:** `delete_all(confirm=True)` (requires confirm; server route may be added later)
+- **Validation:** `forget()` requires at least one of `memory_ids`, `query`, or `before`; docstrings with Args, Returns, Raises
+- Unit tests for memory operations (mocked transport): write/read responses, forget/delete_all validation, get_context, remember/search delegation
+
+#### Phase 4: Embedded mode
+- **EmbeddedCognitiveMemoryLayer:** In-process CML engine with same API as HTTP client (write, read, turn, update, forget, stats, get_context, remember, search, create_session, get_session_context, delete_all)
+- **EmbeddedConfig:** Storage mode (lite/standard/full), database, embedding, and LLM config; lite mode uses SQLite + local embeddings
+- **SQLite memory store:** `cml.storage.sqlite_store.SQLiteMemoryStore` implementing engine MemoryStoreBase; in-memory cosine similarity for vector search (~10k records)
+- **Lite mode:** Zero-config `EmbeddedCognitiveMemoryLayer()` uses in-memory SQLite and sentence-transformers; optional `db_path` for persistence
+- **Background workers:** Optional asyncio tasks for consolidation and forgetting when `auto_consolidate` / `auto_forget` are True
+- **Export/import:** `cml.embedded_utils.export_memories_async`, `import_memories_async` (and sync wrappers) for migration between embedded and server
+- **Parent engine:** HippocampalStore accepts MemoryStoreBase; MemoryOrchestrator.create_lite(episodic_store, embedding_client, llm_client); NoOpGraphStore and NoOpFactStore for lite
+- Unit tests for embedded config and mocked orchestrator
+
+#### Phase 5: Advanced features
+- **Admin operations:** `consolidate(tenant_id=..., user_id=...)` and `run_forgetting(tenant_id=..., user_id=..., dry_run=..., max_memories=...)` (dashboard routes; require admin API key)
+- **Batch operations:** `batch_write(items, session_id=..., namespace=...)` (sequential) and `batch_read(queries, max_results=..., format=...)` (concurrent on async, sequential on sync)
+- **Tenant management:** `set_tenant(tenant_id)`, `tenant_id` property, `list_tenants()` (admin only)
+- **Event log:** `get_events(limit=..., page=..., event_type=..., since=...)` (admin only)
+- **Component health:** `component_health()` (admin only)
+- **Namespace isolation:** `with_namespace(namespace)` returning `NamespacedClient` / `AsyncNamespacedClient` that inject namespace into write/update/batch_write
+- **Memory iteration:** `iter_memories(memory_types=..., status=..., batch_size=...)` yielding `MemoryItem` with pagination (admin only)
+- **OpenAI integration:** `cml.integrations.CMLOpenAIHelper(memory_client, openai_client, model=...)` with `chat(user_message, session_id=..., system_prompt=..., extra_messages=...)`; optional `MemoryProvider` protocol
+- Unit tests for Phase 5 (mocked transport)
+
+#### Phase 6: Developer experience
+- **Structured errors:** CMLError and subclasses include optional `suggestion`, `request_id`; `_raise_for_status` passes actionable suggestions per status code
+- **Logging:** `cml.utils.logging` with `configure_logging(level, handler)`, `_redact()`; DEBUG log for request/response timing in transport; DEBUG/WARNING in retry
+- **Graceful degradation:** `read_safe(query, **kwargs)` on sync and async clients returns empty ReadResponse on ConnectionError/TimeoutError
+- **TypedDict:** `ConsolidationResult`, `ForgettingResult` in models for admin return types
+- **Response __str__:** ReadResponse, WriteResponse, StatsResponse have human-readable `__str__`
+- **Serialization:** `CMLJSONEncoder`, `serialize_for_api()` in `cml.utils.serialization`
+- **Session context manager:** `memory.session(name=..., ttl_hours=...)` (sync and async) yielding SessionScope / AsyncSessionScope with write, read, turn, remember
+- **HTTP/2 and limits:** httpx Client/AsyncClient created with `http2=True` and `Limits(max_connections=100, ...)`
+- **Deprecation:** `cml.utils.deprecation.deprecated(alternative, removal_version)` decorator
+- **Thread safety:** Sync client uses `threading.RLock` in `set_tenant()`
+- **Async loop check:** Async client stores creation event loop and raises RuntimeError if used in a different loop
+- Unit tests for Phase 6 (exceptions, logging, read_safe, __str__, serialization, session, deprecation, thread safety, event loop)
+
+#### Phase 8: Documentation and publishing
+- **README:** PyPI and Python version badges, one-line tagline, Documentation links to getting-started, api-reference, configuration, examples
+- **Docs:** getting-started.md, api-reference.md, configuration.md, examples.md in packages/py-cml/docs/
+- **Examples:** quickstart.py, chat_with_memory.py, async_example.py, embedded_mode.py, agent_integration.py in packages/py-cml/examples/
+- **GitHub:** Issue templates (bug_report, feature_request), pull_request_template with Summary, Changes, Testing, Documentation checklists
+- **SECURITY.md:** Supported versions, report via GitHub Security Advisories
+- **CONTRIBUTING:** Releasing py-cml section (version bump, tag py-cml-v*, PyPI publish); fork/venv in dev setup; PR checklist alignment
+- Publish workflow (py-cml-publish.yml on py-cml-v* tag) already in place; no code changes

cognitive_memory_layer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,171 @@
+# Contributing to py-cml
+
+Thanks for your interest in the CognitiveMemoryLayer Python SDK. This guide covers development setup and workflow for the `packages/py-cml` package.
+
+## Development setup
+
+1. Fork and clone the CognitiveMemoryLayer repository (or work in a branch if you have write access).
+2. Create a virtual environment (recommended): `python -m venv .venv` then activate it.
+3. Install the package in editable mode with dev dependencies.
+
+From the **repository root**:
+
+```bash
+pip install -e "packages/py-cml[dev]"
+```
+
+Or from inside the package:
+
+```bash
+cd packages/py-cml
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode with dev dependencies (pytest, ruff, mypy, pre-commit). Run `pre-commit install` to enable hooks.
+
+## Running tests
+
+From `packages/py-cml`:
+
+**Unit tests (default; no server required):**
+
+```bash
+pytest tests/unit/ -v
+pytest tests/unit/ -v --cov=cml --cov-report=term-missing --cov-branch
+```
+
+Unit tests cover config, exceptions, retry logic, transport (including 403/422/429/500 and connection/timeout mapping), models (serialization), client health and memory operations (mocked), serialization, and logging. CI runs only unit tests on every push.
+
+**Integration tests** (require a running CML server):
+
+```bash
+export CML_TEST_URL=http://localhost:8000   # optional
+export CML_TEST_API_KEY=your-key            # optional
+pytest tests/integration/ -v -m integration
+```
+
+**Embedded tests** (require `pip install -e ".[dev,embedded]"` and CML engine):
+
+```bash
+pytest tests/embedded/ -v -m embedded
+```
+
+**E2E tests** (require live server):
+
+```bash
+pytest tests/e2e/ -v -m e2e
+```
+
+**Run everything except integration/embedded/e2e:**
+
+```bash
+pytest -m "not integration and not embedded and not e2e" -v
+```
+
+Shared fixtures live in `tests/conftest.py` (`test_config`, `mock_config`, `sync_client`, `async_client`, and mock response helpers). Integration tests use `live_client` from `tests/integration/conftest.py` and skip if the server is unreachable.
+
+## Code style and type checking
+
+- **Ruff** — linting and formatting:
+  ```bash
+  ruff check src/ tests/
+  ruff format src/ tests/
+  ```
+
+- **mypy** — type checking (strict):
+  ```bash
+  mypy src/cml/
+  ```
+
+Configuration for ruff and mypy lives in `pyproject.toml`.
+
+## Pre-commit hooks
+
+Install and run pre-commit (from `packages/py-cml` or repo root with config path):
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+Hooks run ruff (check + format), mypy, and generic checks (trailing whitespace, YAML/TOML, etc.).
+
+## Pull request process
+
+1. Create a branch from `main`, make changes in `packages/py-cml/`.
+2. Add or update tests; ensure `pytest tests/unit/`, `mypy src/cml/`, and `ruff check src/ tests/` pass.
+3. Update docstrings, README, or CHANGELOG as applicable (see PR template checklist).
+4. Open a PR. CI runs py-cml tests and lint when paths under `packages/py-cml/**` or the workflow file change.
+5. Get review approval and merge.
+
+## Commit message conventions
+
+- `feat(cml): ...` — new feature
+- `fix(cml): ...` — bug fix
+- `docs(cml): ...` — documentation
+- `test(cml): ...` — tests
+- `chore(py-cml): ...` — build, CI, tooling
+
+## Publishing the package to PyPI
+
+Releases are published to PyPI when a tag matching `py-cml-v*` is pushed. The workflow (`.github/workflows/py-cml.yml`) uses **PyPI trusted publishing (OIDC)**; no API tokens are stored in the repo.
+
+### Prerequisites (one-time)
+
+- **PyPI:** Add a [trusted publisher](https://docs.pypi.org/trusted-publishers/) (or pending publisher) for the project `cognitive-memory-layer`:
+  - **Repository:** `owner/CognitiveMemoryLayer`
+  - **Workflow name:** `py-cml.yml`
+  - **Environment name:** `pypi`
+- **GitHub:** Create an environment named **`pypi`** under **Settings → Environments** (no secrets required for trusted publishing).
+
+### Before each release
+
+1. **Bump version** in `packages/py-cml/pyproject.toml` and `packages/py-cml/src/cml/_version.py` (e.g. `0.1.0` → `0.1.1`).
+2. **Update CHANGELOG.md** — add a `## [X.Y.Z] - YYYY-MM-DD` section and move entries from Unreleased.
+3. **Commit and push to `main`:** e.g. `chore(py-cml): prepare release v0.1.1`
+
+### Ways to publish
+
+**Option A — From GitHub Actions (no local tag needed)**
+
+1. Go to **Actions** → **py-cml: CI and release** → **Run workflow**.
+2. Choose branch **main** (or the branch you pushed the version bump to).
+3. Enter **Version to release** (e.g. `0.1.1`). Leave it empty only if you just want to run lint/test/build.
+4. Click **Run workflow**.
+5. **Two runs:** The first run (manual) only runs **Create release tag** and pushes the tag; lint/test/build/publish are skipped. The **tag push triggers a second run** where only **Build and publish to PyPI** runs. In the Actions list, find the run triggered by the tag (e.g. "Tag py-cml-v0.1.1 pushed" or similar) and confirm that job succeeded.
+
+**Option B — From the command line**
+
+1. From your repo root (on `main`, with the version bump already pushed):
+   ```bash
+   git pull origin main
+   git tag py-cml-v0.1.1   # use the same version as in pyproject.toml
+   git push origin py-cml-v0.1.1
+   ```
+2. The push triggers the workflow; the **Build and publish to PyPI** job runs and uploads the package.
+
+**Option C — From GitHub Releases**
+
+1. After pushing the version bump to `main`, go to **Releases** → **Draft a new release**.
+2. Choose **Tag:** create a new tag `py-cml-v0.1.1` from `main`.
+3. Set the release title (e.g. `v0.1.1`) and paste the CHANGELOG section. Publish the release.
+4. Creating the tag (via the release) pushes it; the workflow runs and publishes to PyPI.
+
+### After publishing
+
+- **Optional:** If you used Option B or A, create a **GitHub Release** from the new tag and paste the CHANGELOG section.
+- **Verify:** `pip install cognitive-memory-layer==0.1.1` then `python -c "from cml import CognitiveMemoryLayer; print('OK')"`.
+
+### Troubleshooting
+
+- **PyPI still shows "0 projects"**  
+  Check that the **tag-triggered** run (the second run after you used Option A) exists and that **Build and publish to PyPI** completed successfully. If that run is missing, the tag push may not have triggered the workflow (e.g. path filters); use Option B to push the tag from your machine and confirm the run appears.
+- **Pending publishers:** Use only the publisher for **workflow `py-cml.yml`** and **environment `pypi`**. If you have a pending publisher for `py-cml-publish.yml`, remove it (that workflow was merged into `py-cml.yml`).
+
+### TestPyPI (optional)
+
+To try the release flow without publishing to production PyPI: add a trusted publisher for **TestPyPI** with the same workflow and environment, then push a tag (e.g. `py-cml-v0.1.0a1`) or use **Run workflow** with a pre-release version. Install with `pip install -i https://test.pypi.org/simple/ cognitive-memory-layer==0.1.0a1`.
+
+## General repository guidelines
+
+For broader contribution guidelines (code of conduct, issue templates, repository structure), see the root [CONTRIBUTING.md](../../CONTRIBUTING.md) of the CognitiveMemoryLayer repository.