Skip to content

Commit a89a009

Browse files
ethanjethanj
committed
Snapshot python main ce01a4f
0 parents  commit a89a009

124 files changed

Lines changed: 14843 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
jobs:
10+
ci:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
# Mirror pyproject classifiers: ">=3.10" supports 3.10–3.13.
16+
python-version: ['3.10', '3.11', '3.12', '3.13']
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
# `python-version` here pins `UV_PYTHON` for the whole job, so
21+
# subsequent `uv sync` / `uv run` commands actually use the
22+
# matrix Python. Without this, `uv python install X.Y` only
23+
# installs a Python; uv would then pick whichever interpreter
24+
# satisfies `requires-python` (typically the newest cached one),
25+
# and every matrix cell would silently run the same version.
26+
- name: Install uv + pin Python
27+
uses: astral-sh/setup-uv@v4
28+
with:
29+
enable-cache: true
30+
cache-dependency-glob: 'uv.lock'
31+
python-version: ${{ matrix.python-version }}
32+
33+
# `--all-extras` pulls in both the `dev` group (ruff, mypy,
34+
# vulture, pytest, respx) and the `embeddings` group
35+
# (sentence-transformers). Without `embeddings`, mypy --strict
36+
# fails to resolve the optional sentence_transformers import in
37+
# atomicmemory/embeddings/sentence_transformers.py.
38+
- name: Install dependencies
39+
run: uv sync --all-extras
40+
41+
- name: Verify Python version
42+
run: |
43+
uv run python --version
44+
uv run python -c "import sys; assert sys.version_info[:2] == tuple(int(x) for x in '${{ matrix.python-version }}'.split('.')), f'expected ${{ matrix.python-version }} but got {sys.version}'"
45+
46+
- name: Ruff lint
47+
run: uv run ruff check .
48+
49+
- name: Ruff format check
50+
run: uv run ruff format --check .
51+
52+
- name: Mypy strict
53+
run: uv run mypy atomicmemory --strict
54+
55+
# `.vulture_whitelist.py` is required: it allowlists Protocol-method
56+
# parameter names and context-manager dunder args that vulture
57+
# otherwise flags as unused.
58+
- name: Vulture (dead code)
59+
run: uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
60+
61+
# Excludes integration tests (`-m integration` requires a live
62+
# atomicmemory-core via ATOMICMEMORY_TEST_API_URL).
63+
- name: Pytest
64+
run: uv run pytest -m 'not integration'

‎.gitignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
23+
# Virtual environments
24+
.venv/
25+
venv/
26+
env/
27+
ENV/
28+
29+
# uv
30+
.uv-cache/
31+
32+
# Tooling
33+
.mypy_cache/
34+
.ruff_cache/
35+
.pytest_cache/
36+
.coverage
37+
.coverage.*
38+
htmlcov/
39+
.tox/
40+
.hypothesis/
41+
42+
# Editor
43+
.vscode/
44+
.idea/
45+
*.swp
46+
*.swo
47+
48+
# OS
49+
.DS_Store
50+
Thumbs.db
51+
52+
# Local
53+
*.log
54+
.env
55+
.env.local

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.11

‎.vulture_whitelist.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
"""Vulture allowlist for false positives.
2+
3+
Vulture flags every Protocol method parameter as unused because the body
4+
is `...`. The parameter names are part of the Protocol's public
5+
contract (callers may pass them as kwargs), so we silence those flags
6+
here. Provider-implementation modules that actually use these names
7+
will reference them naturally and lift the warning.
8+
"""
9+
10+
# Protocol method parameter names referenced by name in
11+
# atomicmemory/memory/provider.py.
12+
as_of
13+
reason
14+
instructions
15+
inputs
16+
refs
17+
18+
# Context-manager dunder parameters in atomicmemory/client/memory_client.py.
19+
# Required by the Python protocol; never read in our implementations.
20+
exc_type
21+
tb
22+
23+
# `encrypt` was previously allowlisted as protocol-parity-only but is
24+
# now actively checked in MemoryStorageAdapter / SQLiteStorageAdapter.set
25+
# (raises ConfigError when True), so it is no longer a vulture target.

‎AGENTS.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# atomicmemory-python — agent rules
2+
3+
Python client SDK for the AtomicMemory memory layer.
4+
5+
## Contributor Context
6+
7+
Use this file as the repo-local contributor guide. When behavior depends on
8+
another AtomicMemory repo, rely on the published HTTP/package contract and call
9+
out any assumption in the PR.
10+
11+
Before changing code, read the relevant local files first:
12+
13+
- `README.md` for user-facing installation and usage.
14+
- `pyproject.toml` for supported Python versions, dependencies, and tool config.
15+
- `atomicmemory/` for package code and `tests/` for expected behavior.
16+
17+
## Repository Shape
18+
19+
- `atomicmemory/` — typed Python package.
20+
- `tests/` — unit and integration tests.
21+
- `examples/` — public usage examples.
22+
- `pyproject.toml` — package metadata and tool configuration.
23+
24+
## Tooling
25+
26+
- **Package management:** `uv sync` (NOT `uv pip install`).
27+
- **Python interpreter:** `.venv/bin/python`. Never the global `python`.
28+
- **HTTP:** `httpx` (sync `Client`, async `AsyncClient`).
29+
- **Validation:** `pydantic>=2.7`. `jsonschema` only when validating against external JSON schemas.
30+
- **Lint/format:** `ruff` (line=120). `ruff format --check .` is part of pre-commit.
31+
- **Types:** `mypy --strict`.
32+
- **Dead code / static health:** `vulture --min-confidence 90`. The whitelist file `.vulture_whitelist.py` MUST be included in every invocation (it allowlists Protocol-method parameter names and context-manager dunder args). Use the `[tool.vulture]` config (`uv run vulture`) or pass it explicitly: `uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90`. `fallow` is TypeScript-only and is not part of this repo's verification.
33+
- **Tests:** `pytest`, `pytest-asyncio`, `pytest-mock`, `respx`. Integration tests gated behind `-m integration`.
34+
35+
## Code rules
36+
37+
- File ≤400 lines (excl. comments/docstrings); function ≤40 lines (excl. catch/finally and docstrings); test files ≤400 lines; tests ≤40 lines.
38+
- Google-style docstrings (`Args:`, `Returns:`, `Raises:`).
39+
- Module docstring at the top of every file. For modules that port a specific TS file, include the TS source-of-truth path (`"""Port of atomicmemory-sdk/src/.../foo.ts."""`).
40+
- No fallback values; no `os.getenv` in business code (config flows through Pydantic models constructed at startup).
41+
- No silent `except`. No bare `except:`.
42+
- Greenfield code — no backwards-compat hacks, no `_` private renames for "removed" code.
43+
- Snake_case for Python attributes; Pydantic `Field(alias="apiUrl")` aliases preserve TS camelCase wire format.
44+
- Keep public API behavior aligned with `atomicmemory-sdk` where both SDKs expose the same concept.
45+
- Prefer integration tests with a real HTTP path for client behavior; use mocks only for narrow transport errors.
46+
47+
## Pre-commit verification
48+
49+
Run before opening any PR:
50+
51+
```bash
52+
uv sync
53+
uv run ruff check .
54+
uv run ruff format --check .
55+
uv run mypy atomicmemory --strict
56+
uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
57+
uv run pytest
58+
```
59+
60+
All must be green.
61+
62+
## Branching
63+
64+
- `main` is protected; commit only via PR.
65+
- Per-phase work lands on `feat/phase-N-<slug>` branches.

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Changelog
2+
3+
All notable changes to `atomicmemory` will be documented in this file.
4+
5+
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).
6+
7+
## [Unreleased]
8+
9+
## [1.0.0]
10+
11+
Initial public stable release.
12+
13+
### Added
14+
- `AtomicMemoryClient` and `AsyncAtomicMemoryClient` as the primary public client surfaces.
15+
- Memory ingestion, search, package, get, list, and delete support.
16+
- AtomicMemory and Mem0 provider adapters.
17+
- Typed AtomicMemory namespace handles for lifecycle, audit, lessons, agents, and runtime config.
18+
- Direct artifact storage client with pointer and managed artifact workflows.
19+
- Local embedding, semantic search, and KV cache helpers.
20+
- Pydantic models, typed exceptions, and `py.typed` marker for downstream type checkers.

‎CLAUDE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# atomicmemory-python — agent rules
2+
3+
Python client SDK for the AtomicMemory memory layer.
4+
5+
## Contributor Context
6+
7+
Use this file as the repo-local contributor guide. When behavior depends on
8+
another AtomicMemory repo, rely on the published HTTP/package contract and call
9+
out any assumption in the PR.
10+
11+
Before changing code, read the relevant local files first:
12+
13+
- `README.md` for user-facing installation and usage.
14+
- `pyproject.toml` for supported Python versions, dependencies, and tool config.
15+
- `atomicmemory/` for package code and `tests/` for expected behavior.
16+
17+
## Repository Shape
18+
19+
- `atomicmemory/` — typed Python package.
20+
- `tests/` — unit and integration tests.
21+
- `examples/` — public usage examples.
22+
- `pyproject.toml` — package metadata and tool configuration.
23+
24+
## Tooling
25+
26+
- **Package management:** `uv sync` (NOT `uv pip install`).
27+
- **Python interpreter:** `.venv/bin/python`. Never the global `python`.
28+
- **HTTP:** `httpx` (sync `Client`, async `AsyncClient`).
29+
- **Validation:** `pydantic>=2.7`. `jsonschema` only when validating against external JSON schemas.
30+
- **Lint/format:** `ruff` (line=120). `ruff format --check .` is part of pre-commit.
31+
- **Types:** `mypy --strict`.
32+
- **Dead code / static health:** `vulture --min-confidence 90`. The whitelist file `.vulture_whitelist.py` MUST be included in every invocation (it allowlists Protocol-method parameter names and context-manager dunder args). Use the `[tool.vulture]` config (`uv run vulture`) or pass it explicitly: `uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90`. `fallow` is TypeScript-only and is not part of this repo's verification.
33+
- **Tests:** `pytest`, `pytest-asyncio`, `pytest-mock`, `respx`. Integration tests gated behind `-m integration`.
34+
35+
## Code rules
36+
37+
- File ≤400 lines (excl. comments/docstrings); function ≤40 lines (excl. catch/finally and docstrings); test files ≤400 lines; tests ≤40 lines.
38+
- Google-style docstrings (`Args:`, `Returns:`, `Raises:`).
39+
- Module docstring at the top of every file. For modules that port a specific TS file, include the TS source-of-truth path (`"""Port of atomicmemory-sdk/src/.../foo.ts."""`).
40+
- No fallback values; no `os.getenv` in business code (config flows through Pydantic models constructed at startup).
41+
- No silent `except`. No bare `except:`.
42+
- Greenfield code — no backwards-compat hacks, no `_` private renames for "removed" code.
43+
- Snake_case for Python attributes; Pydantic `Field(alias="apiUrl")` aliases preserve TS camelCase wire format.
44+
- Keep public API behavior aligned with `atomicmemory-sdk` where both SDKs expose the same concept.
45+
- Prefer integration tests with a real HTTP path for client behavior; use mocks only for narrow transport errors.
46+
47+
## Pre-commit verification
48+
49+
Run before opening any PR:
50+
51+
```bash
52+
uv sync
53+
uv run ruff check .
54+
uv run ruff format --check .
55+
uv run mypy atomicmemory --strict
56+
uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
57+
uv run pytest
58+
```
59+
60+
All must be green.
61+
62+
## Branching
63+
64+
- `main` is protected; commit only via PR.
65+
- Per-phase work lands on `feat/phase-N-<slug>` branches.

‎GEMINI.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# atomicmemory-python — agent rules
2+
3+
Python client SDK for the AtomicMemory memory layer.
4+
5+
## Contributor Context
6+
7+
Use this file as the repo-local contributor guide. When behavior depends on
8+
another AtomicMemory repo, rely on the published HTTP/package contract and call
9+
out any assumption in the PR.
10+
11+
Before changing code, read the relevant local files first:
12+
13+
- `README.md` for user-facing installation and usage.
14+
- `pyproject.toml` for supported Python versions, dependencies, and tool config.
15+
- `atomicmemory/` for package code and `tests/` for expected behavior.
16+
17+
## Repository Shape
18+
19+
- `atomicmemory/` — typed Python package.
20+
- `tests/` — unit and integration tests.
21+
- `examples/` — public usage examples.
22+
- `pyproject.toml` — package metadata and tool configuration.
23+
24+
## Tooling
25+
26+
- **Package management:** `uv sync` (NOT `uv pip install`).
27+
- **Python interpreter:** `.venv/bin/python`. Never the global `python`.
28+
- **HTTP:** `httpx` (sync `Client`, async `AsyncClient`).
29+
- **Validation:** `pydantic>=2.7`. `jsonschema` only when validating against external JSON schemas.
30+
- **Lint/format:** `ruff` (line=120). `ruff format --check .` is part of pre-commit.
31+
- **Types:** `mypy --strict`.
32+
- **Dead code / static health:** `vulture --min-confidence 90`. The whitelist file `.vulture_whitelist.py` MUST be included in every invocation (it allowlists Protocol-method parameter names and context-manager dunder args). Use the `[tool.vulture]` config (`uv run vulture`) or pass it explicitly: `uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90`. `fallow` is TypeScript-only and is not part of this repo's verification.
33+
- **Tests:** `pytest`, `pytest-asyncio`, `pytest-mock`, `respx`. Integration tests gated behind `-m integration`.
34+
35+
## Code rules
36+
37+
- File ≤400 lines (excl. comments/docstrings); function ≤40 lines (excl. catch/finally and docstrings); test files ≤400 lines; tests ≤40 lines.
38+
- Google-style docstrings (`Args:`, `Returns:`, `Raises:`).
39+
- Module docstring at the top of every file. For modules that port a specific TS file, include the TS source-of-truth path (`"""Port of atomicmemory-sdk/src/.../foo.ts."""`).
40+
- No fallback values; no `os.getenv` in business code (config flows through Pydantic models constructed at startup).
41+
- No silent `except`. No bare `except:`.
42+
- Greenfield code — no backwards-compat hacks, no `_` private renames for "removed" code.
43+
- Snake_case for Python attributes; Pydantic `Field(alias="apiUrl")` aliases preserve TS camelCase wire format.
44+
- Keep public API behavior aligned with `atomicmemory-sdk` where both SDKs expose the same concept.
45+
- Prefer integration tests with a real HTTP path for client behavior; use mocks only for narrow transport errors.
46+
47+
## Pre-commit verification
48+
49+
Run before opening any PR:
50+
51+
```bash
52+
uv sync
53+
uv run ruff check .
54+
uv run ruff format --check .
55+
uv run mypy atomicmemory --strict
56+
uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
57+
uv run pytest
58+
```
59+
60+
All must be green.
61+
62+
## Branching
63+
64+
- `main` is protected; commit only via PR.
65+
- Per-phase work lands on `feat/phase-N-<slug>` branches.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 AtomicMemory
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)