mneme-code 3.1.0__py3-none-any.whl

mneme_code/trajectory.py

@@ -0,0 +1,140 @@
+"""FixTrajectory dataclass and vault-ready markdown serialization.
+
+A fix-trajectory links a :class:`~mneme_code.failure.FailureMemory` to its
+resolution via temporal supersession.  The fix note is rendered with
+``type: claim`` and ``supersedes: <failure_note_id>`` so the mneme-temporal
+layer's ``as_of`` / ``current`` queries automatically treat the failure as
+resolved after ``resolved_at`` — no new infrastructure required.
+
+Provenance invariant: every ``FixTrajectory`` carries:
+    trajectory_id   — deterministic UUID5 derived from failure_id + redacted fix_summary.
+    failure_id      — the ``FailureMemory.failure_id`` being resolved.
+    failure_note_id — the vault note id of the failure note (target of ``supersedes``).
+    fix_summary     — redacted human summary of the fix.
+    resolved_at     — injected by caller; never produced inside this module.
+    trust           — default ``"user"`` (operator-supplied resolution).
+    confidence      — default ``"EXTRACTED"`` (directly observed, no inference).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mneme_core.privacy import redact
+
+from mneme_code.failure import FailureMemory
+
+
+@dataclass(frozen=True)
+class FixTrajectory:
+    """A provenance-labelled, redacted record of one failure resolution.
+
+    Attributes:
+        trajectory_id    Deterministic UUID5 (namespace URL) derived from
+                         ``failure_id`` and the redacted ``fix_summary``.
+        failure_id       The ``FailureMemory.failure_id`` being resolved.
+        failure_note_id  The vault note id of the failure note; used as the
+                         ``supersedes`` target in the temporal claim frontmatter.
+        fix_summary      Redacted human summary of the fix applied.
+        resolved_at      Tz-aware UTC datetime injected by the caller.
+        trust            Provenance tier; default ``"user"``.
+        confidence       Confidence label; default ``"EXTRACTED"``.
+    """
+
+    trajectory_id: str
+    failure_id: str
+    failure_note_id: str
+    fix_summary: str
+    resolved_at: datetime
+    trust: str = field(default="user")
+    confidence: str = field(default="EXTRACTED")
+
+
+def fix_from_failure(
+    failure: FailureMemory,
+    *,
+    fix_summary: str,
+    resolved_at: datetime,
+    failure_note_id: str | None = None,
+) -> FixTrajectory:
+    """Construct a :class:`FixTrajectory` from a :class:`FailureMemory`.
+
+    Args:
+        failure:          The :class:`FailureMemory` being resolved.
+        fix_summary:      Human summary of the fix; redacted via
+                          :func:`mneme_core.privacy.redact` before storage.
+        resolved_at:      Tz-aware UTC datetime for this resolution.
+                          Must be injected by the caller; this function never
+                          calls ``datetime.now()``.
+        failure_note_id:  Vault note id of the failure note.  Defaults to
+                          ``failure.failure_id`` when omitted.
+
+    Returns:
+        A deterministic :class:`FixTrajectory` — same inputs always produce
+        the same ``trajectory_id``.
+    """
+    note_id = failure_note_id if failure_note_id is not None else failure.failure_id
+    redacted_summary = redact(fix_summary)
+
+    # Deterministic UUID5: namespace URL + failure_id + NUL separator + redacted summary.
+    key = f"{failure.failure_id}\x00{redacted_summary}"
+    trajectory_id = str(uuid.uuid5(uuid.NAMESPACE_URL, key))
+
+    return FixTrajectory(
+        trajectory_id=trajectory_id,
+        failure_id=failure.failure_id,
+        failure_note_id=note_id,
+        fix_summary=redacted_summary,
+        resolved_at=resolved_at,
+    )
+
+
+def fix_to_markdown(fix: FixTrajectory) -> str:
+    """Render a :class:`FixTrajectory` as a vault-ready temporal claim note.
+
+    Frontmatter fields:
+        id              fix.trajectory_id
+        type            ``"claim"``  — indexes the note into the temporal layer.
+        created         fix.resolved_at as tz-aware UTC ISO 8601 with microseconds.
+        tags            ``["fix", "trajectory"]``
+        claim_key       ``"failure.<failure_id>"`` — ties fix and failure together.
+        supersedes      fix.failure_note_id — temporal supersession target.
+        valid_from      fix.resolved_at as tz-aware UTC ISO 8601 with microseconds.
+        trust           fix.trust
+        confidence      fix.confidence
+
+    Body: heading ``# Fix for <failure_id>`` followed by the redacted fix_summary.
+
+    All content has already been redacted at construction time; this function
+    does not re-apply redaction.
+    """
+    # Normalise resolved_at to tz-aware UTC (mirrors failure_to_markdown and _to_utc_iso).
+    resolved = fix.resolved_at
+    resolved = resolved.replace(tzinfo=UTC) if resolved.tzinfo is None else resolved.astimezone(UTC)
+    resolved_str = resolved.isoformat(timespec="microseconds")
+
+    fm_lines = [
+        "---",
+        f"id: {fix.trajectory_id}",
+        "type: claim",
+        f"created: {resolved_str}",
+        "tags:",
+        "  - fix",
+        "  - trajectory",
+        f"claim_key: {json.dumps(f'failure.{fix.failure_id}')}",
+        f"supersedes: {json.dumps(fix.failure_note_id)}",
+        f"valid_from: {resolved_str}",
+        f"trust: {fix.trust}",
+        f"confidence: {fix.confidence}",
+        "---",
+    ]
+
+    body_lines: list[str] = []
+    body_lines.append(f"# Fix for {fix.failure_id}")
+    body_lines.append("")
+    body_lines.append(fix.fix_summary)
+
+    return "\n".join(fm_lines) + "\n" + "\n".join(body_lines) + "\n"

mneme_code-3.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: mneme-code
+Version: 3.1.0
+Summary: Deterministic Python code-failure memory layer for mneme: redact-before-store, provenance-labelled FailureMemory, vault-ready markdown output.
+Author: Onour Impram
+License: Apache-2.0
+Keywords: code-failure,memory,mneme,redaction,traceback
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mneme-core<4,>=3.0.0
+Requires-Dist: mneme-graph>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mneme-code
+
+Deterministic Python code-failure memory for mneme. Parses CPython tracebacks
+into structured failures, renders them as vault-ground-truth markdown memories,
+and resolves stack frames to [mneme-graph](../mneme-graph) function nodes.
+
+Part of the [mneme](https://github.com/TheGoatPsy/mneme) memory engine.
+
+## What it does (v1)
+
+- **Traceback parsing.** `parse_traceback` turns a standard CPython traceback
+  into a `ParsedTraceback` (exception type, message, frames). It never raises;
+  unrecognised input returns `None`.
+- **Failure memories.** `failure_from_traceback` + `failure_to_markdown` produce
+  a markdown note the user owns, with provenance (`content_hash`, `observed_at`,
+  `trust`) and a confidence label.
+- **Frame resolution.** `resolve_frames` pairs each frame with a mneme-graph
+  `function` node when one matches, with a clean fallback to `None`.
+
+Redaction (`mneme_core.privacy.redact`) is applied to every user-derived string
+(exception message, code context, file path) before it is stored or rendered.
+No LLM, no network; library functions are pure (the caller injects timestamps).
+
+## Scope and deferrals (v1)
+
+The following are **not** implemented yet and are documented here for honesty:
+
+- Live test-runner integration.
+- Branch-aware failure tracking.
+- `AGENTS.md` procedural-memory parsing and repo runbook generation.
+- Fix-trajectory wiring: a *fix* is modelled as a `mneme-temporal` claim that
+  **supersedes** the failure memory. That lifecycle lives in `mneme-temporal`
+  and is reused, not reinvented here.
+- Non-Python tracebacks.

mneme_code-3.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mneme_code/__init__.py,sha256=UXoCFsJCxAfLWR2FlrM_o3pUNmGuSdJaj0dLsEiorAI,2770
+mneme_code/agents.py,sha256=RxBIZ6mt7uDpRG2L4aDvcNaBlqBBDACiGpp0Ec7i5OQ,9065
+mneme_code/cli.py,sha256=3O0NHi9tXHFZtWqDn4DECeTxylw1Qv6JJeoLMZU9fIQ,5953
+mneme_code/failure.py,sha256=cCarpK-EPyOaYWnHevkLtvZvD6jyxImT_Dhqi_uTIyM,6908
+mneme_code/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mneme_code/resolve.py,sha256=eIE5vZUHEBjCEtElZ4V1bPWls1vuWfFJl7sa-XZI7sI,4487
+mneme_code/stacktrace.py,sha256=r3qCA_3Pjw6iYQXiAA5Jh5JVluydaUCIw1mYIidkEEM,6218
+mneme_code/testrun.py,sha256=zGsSvgwdh6AJ5yI6bPRnLTJZc6c1YkEN_7Cum5C0Ul0,10805
+mneme_code/trajectory.py,sha256=y0BZ8mq4M9-iegnVv6P25DCfi3r_XLJbDwwjM7jNf_Y,5631
+mneme_code-3.1.0.dist-info/METADATA,sha256=APNuMAELyb7jHQVC1eWYGpzQvrLXftOuWuv2lLiboVY,2642
+mneme_code-3.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mneme_code-3.1.0.dist-info/entry_points.txt,sha256=pmHq6U16MqppYske97Ht9_baKKaOEpgAV63ZCF6UKbY,51
+mneme_code-3.1.0.dist-info/RECORD,,

mneme_code-3.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mneme_code-3.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mneme-code = mneme_code.cli:main