bikem 0.1.0__tar.gz

bikem-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv venv --python ${{ matrix.python-version }}
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

bikem-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.bikem/
+*.jsonl
+.env
+.env.*
+!.env.example

bikem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kelchy
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

bikem-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: bikem
+Version: 0.1.0
+Summary: Local-first memory and drift detection for long AI sessions
+Project-URL: Homepage, https://github.com/kelchy/bikem
+Project-URL: Repository, https://github.com/kelchy/bikem
+Project-URL: Issues, https://github.com/kelchy/bikem/issues
+Author: Kelchy
+License: MIT
+License-File: LICENSE
+Keywords: ai,context,llm,memory,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.24
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bikem
+
+Local-first memory and drift detection for long AI sessions.
+
+    import bikem
+
+    with bikem.session("fix-auth-bug"):
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "explain this stack trace"}],
+        )
+    # every call is now recorded to ~/.bikem/sessions/
+
+Long AI sessions forget. They drift. They repeat. When something breaks at
+step 40, you cannot reproduce it because the model is non-deterministic.
+bikem records every LLM and tool call to a local JSONL file, reinjects the
+right context so the session stops degrading, and flags the moment output
+starts drifting from the original task.
+
+No account. No network calls to us. Your traces are files on your disk.
+
+## Install
+
+    pip install bikem
+
+## Status
+
+Alpha. Recorder and store are being built now.
+
+## License
+
+MIT

bikem-0.1.0/README.md

@@ -0,0 +1,32 @@
+# bikem
+
+Local-first memory and drift detection for long AI sessions.
+
+    import bikem
+
+    with bikem.session("fix-auth-bug"):
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "explain this stack trace"}],
+        )
+    # every call is now recorded to ~/.bikem/sessions/
+
+Long AI sessions forget. They drift. They repeat. When something breaks at
+step 40, you cannot reproduce it because the model is non-deterministic.
+bikem records every LLM and tool call to a local JSONL file, reinjects the
+right context so the session stops degrading, and flags the moment output
+starts drifting from the original task.
+
+No account. No network calls to us. Your traces are files on your disk.
+
+## Install
+
+    pip install bikem
+
+## Status
+
+Alpha. Recorder and store are being built now.
+
+## License
+
+MIT

bikem-0.1.0/bikem/__init__.py

@@ -0,0 +1,126 @@
+"""bikem -- local-first memory and drift detection for long AI sessions.
+
+Public API:
+
+    import bikem
+
+    with bikem.session("my-session"):
+        ...  # your existing code, unchanged
+
+    # or manual control:
+    with bikem.session("my-session") as s:
+        print(s.session_id)
+        print(s.trace_path)
+
+Environment:
+
+    BIKEM_HOME      storage root (default: ~/.bikem)
+    BIKEM_DISABLE   set to "1" to make session() a no-op
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from . import recorder
+from .events import GENESIS_HASH, EventType, compute_hash, verify_chain
+from .replay import ReplayContext, ReplayResult, replay
+from .store import DEFAULT_ROOT, SessionStore, list_sessions, load_session
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "session",
+    "Session",
+    "replay",
+    "ReplayContext",
+    "ReplayResult",
+    "SessionStore",
+    "list_sessions",
+    "load_session",
+    "verify_chain",
+    "GENESIS_HASH",
+    "compute_hash",
+    "DEFAULT_ROOT",
+    "__version__",
+]
+
+
+class Session:
+    """A single recording session.
+
+    Returned by bikem.session(). Exposes the session id and the on-disk
+    trace path so callers can point at the file directly.
+    """
+
+    def __init__(self, name: str = "", store: SessionStore | None = None):
+        self.name = name
+        self.store = store or SessionStore()
+        self._entered = False
+
+    @property
+    def session_id(self) -> str:
+        return self.store.session_id
+
+    @property
+    def trace_path(self) -> Path:
+        return self.store.path
+
+    def __enter__(self) -> Session:
+        self._entered = True
+        self.store.append(
+            EventType.SESSION_START,
+            {"name": self.name, "pid": os.getpid()},
+        )
+        recorder.install(self.store)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        try:
+            if exc_type is None:
+                self.store.append(EventType.SESSION_END, {"status": "ok"})
+            else:
+                self.store.append(
+                    EventType.SESSION_END,
+                    {"status": "error", "error": f"{exc_type.__name__}: {exc}"},
+                )
+        except Exception:
+            pass
+        finally:
+            recorder.uninstall()
+        return False
+
+
+def _disabled() -> bool:
+    return os.environ.get("BIKEM_DISABLE", "").strip() in ("1", "true", "yes")
+
+
+@contextlib.contextmanager
+def session(name: str = "", root: Path | str | None = None) -> Iterator[Session]:
+    """Open a bikem session. Everything recorded until exit."""
+    if _disabled():
+        yield Session(name=name, store=_NullStore())
+        return
+
+    store = SessionStore(root=root)
+    sess = Session(name=name, store=store)
+    with sess:
+        yield sess
+
+
+class _NullStore:
+    """A store that does nothing. Used when BIKEM_DISABLE is set."""
+
+    session_id = "sess_disabled"
+    path = Path("/dev/null")
+
+    def append(self, *a, **kw):
+        from .events import Event, now_iso
+
+        return Event(seq=0, type="disabled", session_id="sess_disabled", payload={}, ts=now_iso())
+
+    def read(self):
+        return []