cortexdb-mcp 0.3.3__tar.gz → 0.4.0__tar.gz

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/.gitignore

@@ -77,3 +77,6 @@ blog/
 sales/
 videos/
 local-instance/
+
+# doc-claims verifier scratch output
+tools/verifier_out*/

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-mcp
-Version: 0.3.3
+Version: 0.4.0
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -180,6 +180,16 @@ On Windows, MCP clients sometimes need the absolute path:
 | `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
 | `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |
 
+### Bi-temporal Conflicts & Claim History
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `list_conflicts` | `GET /v1/conflicts` | Queue of contradicting values detected for the same claim. |
+| `resolve_conflict` | `POST /v1/conflicts/{id}/resolve` | Resolve: `pick` / `split` / `new_information` / `dismiss`. |
+| `claim_history` | `GET /v1/claims/history` | Full bi-temporal change-log of one claim (+ its conflicts). |
+
+Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
+
 ### Admin & Observability
 
 | Tool | Maps to | Description |

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/README.md

@@ -167,6 +167,16 @@ On Windows, MCP clients sometimes need the absolute path:
 | `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
 | `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |
 
+### Bi-temporal Conflicts & Claim History
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `list_conflicts` | `GET /v1/conflicts` | Queue of contradicting values detected for the same claim. |
+| `resolve_conflict` | `POST /v1/conflicts/{id}/resolve` | Resolve: `pick` / `split` / `new_information` / `dismiss`. |
+| `claim_history` | `GET /v1/claims/history` | Full bi-temporal change-log of one claim (+ its conflicts). |
+
+Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
+
 ### Admin & Observability
 
 | Tool | Maps to | Description |

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/cortexdb_mcp/render.py

@@ -87,6 +87,68 @@ def fact_text(f: dict[str, Any]) -> str:
     return " ".join(p for p in (subj_text, predicate, obj_text) if p)
 
 
+def _boundary_date(iso: str) -> str:
+    """Trim an RFC3339 boundary to its date part — validity boundaries are
+    day-grained after date grounding; the clock adds noise, not signal."""
+    return (iso or "")[:10]
+
+
+def record_validity_text(r: dict[str, Any]) -> str:
+    """Render a RecordView's valid interval honoring ``BoundaryBasis``.
+
+    THE rendering rule (BITEMPORAL_CONFLICT_DESIGN §2): a boundary whose
+    basis is ``"observed"`` is only a knowledge bound — it must read as
+    "by <date>" (we knew it held/ended by then), NEVER "on/since <date>".
+    Stated boundaries render as "since <date>" / "until <date>".
+    """
+    parts: list[str] = []
+    vf, vt = r.get("valid_from"), r.get("valid_to")
+    if vf:
+        d = _boundary_date(str(vf))
+        parts.append(
+            f"held by {d}" if r.get("valid_from_basis") == "observed" else f"since {d}"
+        )
+    if vt:
+        d = _boundary_date(str(vt))
+        parts.append(
+            f"ended by {d}" if r.get("valid_to_basis") == "observed" else f"until {d}"
+        )
+    return ", ".join(parts) if parts else "undated"
+
+
+def record_text(r: dict[str, Any]) -> str:
+    """Render one bi-temporal RecordView to a readable line:
+    ``<value> (<validity>; recorded <date>[; <status>][; conf NN%])``."""
+    value = "[redacted]" if r.get("redacted") else str(r.get("object") or "?")
+    bits: list[str] = [record_validity_text(r)]
+    recorded = _boundary_date(str(r.get("recorded_from") or ""))
+    if recorded:
+        bits.append(f"recorded {recorded}")
+    status = r.get("status")
+    if status and status != "active":
+        bits.append(str(status))
+    conf = r.get("confidence")
+    if isinstance(conf, (int, float)):
+        bits.append(f"conf {conf:.0%}")
+    return f"{value} ({'; '.join(bits)})"
+
+
+def conflict_lines(c: dict[str, Any]) -> list[str]:
+    """Render a ConflictView as a header line plus one indented line per
+    member record (each honoring the observed→"by" boundary rule)."""
+    header = (
+        f"{c.get('id', '?')} [{c.get('kind', '?')}] "
+        f"{c.get('subject', '?')} {c.get('predicate', '?')} — {c.get('status', '?')}"
+    )
+    lines = [header]
+    for r in c.get("records", []) or []:
+        lines.append(f"    - {record_text(r)}")
+    resolved_by = c.get("resolved_by")
+    if resolved_by:
+        lines.append(f"    resolved by {resolved_by} at {c.get('resolved_at', '?')}")
+    return lines
+
+
 def belief_statement(b: dict[str, Any]) -> str:
     """The human-readable statement a belief asserts (claim.object.value). The
     claim subject is an internal topic key and is deliberately not used."""

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/cortexdb_mcp/server.py

@@ -33,9 +33,11 @@ from cortexdb_mcp.config import CortexMCPConfig
 from cortexdb_mcp.insights import InsightsEngine
 from cortexdb_mcp.render import (
     belief_text as _belief_text,
+    conflict_lines as _conflict_lines,
     fact_text as _fact_text,
     is_synthetic_subject as _is_synthetic_subject,
     memories_from_context as _memories_from_context,
+    record_text as _record_text,
     typed_value_text as _typed_value_text,
 )
 
@@ -722,6 +724,186 @@ async def entity_link(
     )
 
 
+# ===========================================================================
+# TOOLS — Bi-temporal conflicts & claim history
+# ===========================================================================
+#
+# Rendering honors BoundaryBasis (BITEMPORAL_CONFLICT_DESIGN §2): boundaries
+# whose basis is "observed" render as "by <date>" (via render.record_text),
+# never "on/since <date>".
+
+# Per-action argument contract for POST /v1/conflicts/{id}/resolve.
+_RESOLVE_ACTIONS: dict[str, dict[str, tuple[str, ...]]] = {
+    "pick": {"required": ("winner",), "optional": ("reason",)},
+    "split": {"required": ("boundary", "earlier", "later"), "optional": ()},
+    "new_information": {"required": ("record",), "optional": ()},
+    "dismiss": {"required": (), "optional": ("reason",)},
+}
+
+
+def _resolve_body(action: str, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Validate + build the resolve request body; raises ValueError with a
+    message the agent can act on (which field is missing/extraneous)."""
+    spec = _RESOLVE_ACTIONS.get(action)
+    if spec is None:
+        raise ValueError(
+            f"unknown action {action!r}; expected one of {sorted(_RESOLVE_ACTIONS)}"
+        )
+    allowed = set(spec["required"]) | set(spec["optional"])
+    provided = {k for k, v in kwargs.items() if v is not None}
+    missing = [k for k in spec["required"] if k not in provided]
+    if missing:
+        raise ValueError(f"action {action!r} requires {missing}")
+    extraneous = sorted(provided - allowed)
+    if extraneous:
+        raise ValueError(
+            f"action {action!r} does not accept {extraneous} (allowed: {sorted(allowed)})"
+        )
+    body: dict[str, Any] = {"action": action}
+    for k in allowed:
+        if kwargs.get(k) is not None:
+            body[k] = kwargs[k]
+    if action in ("pick", "dismiss"):
+        body.setdefault("reason", "")
+    return body
+
+
+@mcp.tool()
+async def list_conflicts(
+    tenant_id: str | None = None,
+    status: str = "open",
+    limit: int = 20,
+) -> str:
+    """List detected memory conflicts (contradicting values for the same
+    claim). Maps to GET /v1/conflicts.
+
+    Parameters
+    ----------
+    tenant_id:
+        Scope override (defaults to the configured scope).
+    status:
+        "open" (default) for unresolved conflicts only, or "all".
+    limit:
+        Max conflicts to return.
+    """
+    scope = _scope_for(tenant_id)
+    result = await _request(
+        "GET",
+        "/v1/conflicts",
+        params={"scope": scope, "status": status, "limit": str(limit)},
+    )
+    conflicts = result.get("conflicts", [])
+    total = result.get("total", len(conflicts))
+    if not conflicts:
+        qualifier = "open " if status != "all" else ""
+        return f"No {qualifier}conflicts in this scope."
+    parts: list[str] = [f"Showing {len(conflicts)} of {total} conflict(s):\n"]
+    for c in conflicts:
+        parts.extend(_conflict_lines(c))
+        parts.append("")
+    next_cursor = result.get("next_cursor")
+    if next_cursor is not None:
+        parts.append(f"More available (cursor={next_cursor}).")
+    return "\n".join(parts).rstrip()
+
+
+@mcp.tool()
+async def resolve_conflict(
+    conflict_id: str,
+    action: str,
+    winner: str | None = None,
+    reason: str | None = None,
+    boundary: str | None = None,
+    earlier: str | None = None,
+    later: str | None = None,
+    record: str | None = None,
+) -> str:
+    """Resolve a memory conflict. Maps to POST /v1/conflicts/{id}/resolve.
+
+    Parameters
+    ----------
+    conflict_id:
+        The conflict UUID (from list_conflicts).
+    action:
+        One of:
+        - "pick": one record wins outright — requires `winner` (record
+          UUID); `reason` optional.
+        - "split": both values were true at different times — requires
+          `boundary` (absolute date, e.g. "2024-03"), `earlier` and
+          `later` (record UUIDs).
+        - "new_information": the record supersedes the older value —
+          requires `record` (record UUID).
+        - "dismiss": not a real conflict — `reason` optional.
+    """
+    try:
+        body = _resolve_body(
+            action,
+            {
+                "winner": winner,
+                "reason": reason,
+                "boundary": boundary,
+                "earlier": earlier,
+                "later": later,
+                "record": record,
+            },
+        )
+    except ValueError as exc:
+        return f"Invalid resolution: {exc}"
+    result = await _request(
+        "POST", f"/v1/conflicts/{conflict_id}/resolve", json_body=body
+    )
+    if not result.get("id"):
+        return f"Conflict {conflict_id} resolved ({action})."
+    parts = [f"Conflict resolved ({action}):", ""]
+    parts.extend(_conflict_lines(result))
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def claim_history(
+    subject: str,
+    predicate: str,
+    tenant_id: str | None = None,
+) -> str:
+    """Show the full bi-temporal change-log of one claim — every valid
+    interval and every record-time correction, plus any conflicts involving
+    it. Maps to GET /v1/claims/history.
+
+    Parameters
+    ----------
+    subject:
+        The claim's subject entity (e.g. "Alice").
+    predicate:
+        The claim's predicate (e.g. "works_at").
+    tenant_id:
+        Scope override.
+    """
+    scope = _scope_for(tenant_id)
+    result = await _request(
+        "GET",
+        "/v1/claims/history",
+        params={"scope": scope, "subject": subject, "predicate": predicate},
+    )
+    claim = result.get("claim", {}) or {}
+    history = result.get("history", []) or []
+    conflicts = result.get("conflicts", []) or []
+    if not history:
+        return f"No recorded history for claim '{subject} {predicate}'."
+    parts: list[str] = [
+        f"History of {claim.get('subject', subject)} "
+        f"{claim.get('predicate', predicate)} "
+        f"({len(history)} record(s)):\n"
+    ]
+    for r in history:
+        parts.append(f"  {_record_text(r)}")
+    if conflicts:
+        parts.append(f"\n{len(conflicts)} conflict(s) on this claim:")
+        for c in conflicts:
+            for line in _conflict_lines(c):
+                parts.append(f"  {line}")
+    return "\n".join(parts)
+
+
 # ===========================================================================
 # TOOLS — Admin & Observability
 # ===========================================================================

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cortexdb-mcp"
-version = "0.3.3"
+version = "0.4.0"
 description = "MCP Server for CortexDB — expose memory operations to AI agents"
 requires-python = ">=3.10"
 license = "MIT"

{cortexdb_mcp-0.3.3 → cortexdb_mcp-0.4.0}/tests/test_server.py

@@ -15,14 +15,18 @@ import pytest
 
 from cortexdb_mcp.config import CortexMCPConfig
 from cortexdb_mcp.insights import Insight, InsightsEngine, InsightType, Severity
+from cortexdb_mcp.render import record_validity_text
 from cortexdb_mcp.server import (
     _belief_text,
     _config,
+    _conflict_lines,
     _fact_text,
     _is_synthetic_subject,
     _memories_from_context,
+    _record_text,
     _typed_value_text,
     advanced_search,
+    claim_history,
     entity_edges,
     entity_get,
     entity_link,
@@ -30,6 +34,7 @@ from cortexdb_mcp.server import (
     get_context,
     get_insights,
     health_check,
+    list_conflicts,
     memory_bulk_delete,
     memory_delete,
     memory_forget,
@@ -37,6 +42,7 @@ from cortexdb_mcp.server import (
     memory_list,
     memory_search,
     memory_store,
+    resolve_conflict,
 )
 
 
@@ -432,6 +438,252 @@ class TestEntities:
         assert "evt_link" in out
 
 
+# ---------------------------------------------------------------------------
+# Bi-temporal conflicts & claim history
+# ---------------------------------------------------------------------------
+
+
+def _record(
+    obj="Google",
+    *,
+    valid_from="2020-01-01T00:00:00Z",
+    vf_basis="stated",
+    valid_to=None,
+    vt_basis="stated",
+    status="active",
+    rid="0197a3a0-0000-7000-8000-00000000000a",
+):
+    return {
+        "id": rid,
+        "subject": "alice",
+        "predicate": "works_at",
+        "object": obj,
+        "redacted": False,
+        "valid_from": valid_from,
+        "valid_from_basis": vf_basis,
+        "valid_to": valid_to,
+        "valid_to_basis": vt_basis,
+        "recorded_from": "2026-06-15T12:00:00Z",
+        "recorded_to": None,
+        "status": status,
+        "supersedes": None,
+        "source_authority": "extraction",
+        "extractor": "llm",
+        "confidence": 0.9,
+    }
+
+
+def _conflict(status="open", records=None, cid="0197a3a0-0000-7000-8000-0000000000c1"):
+    return {
+        "id": cid,
+        "scope": "org:test/user:test",
+        "subject": "alice",
+        "predicate": "works_at",
+        "kind": "value_disagreement",
+        "status": status,
+        "records": records if records is not None else [
+            _record("Google"),
+            _record("Meta", rid="0197a3a0-0000-7000-8000-00000000000b"),
+        ],
+        "detected_at": "2026-06-15T12:00:00Z",
+        "resolved_at": None,
+        "resolved_by": None,
+        "resolution": None,
+    }
+
+
+class TestRecordRendering:
+    """Lock the BoundaryBasis rule: observed boundaries render as
+    "by <date>", never "on <date>" / "since <date>" (§2)."""
+
+    def test_stated_boundaries_render_since_until(self):
+        r = _record(valid_from="2020-01-01T00:00:00Z",
+                    valid_to="2022-06-01T00:00:00Z")
+        out = record_validity_text(r)
+        assert out == "since 2020-01-01, until 2022-06-01"
+
+    def test_observed_valid_from_renders_by_never_since(self):
+        r = _record(vf_basis="observed")
+        out = record_validity_text(r)
+        assert "held by 2020-01-01" in out
+        assert "since" not in out
+        assert "on 2020" not in out
+
+    def test_observed_valid_to_renders_ended_by_never_until(self):
+        r = _record(valid_to="2022-06-01T00:00:00Z", vt_basis="observed")
+        out = record_validity_text(r)
+        assert "ended by 2022-06-01" in out
+        assert "until" not in out
+
+    def test_unbounded_is_undated(self):
+        assert record_validity_text(_record(valid_from=None)) == "undated"
+
+    def test_record_text_value_and_metadata(self):
+        out = _record_text(_record("Google"))
+        assert out.startswith("Google (")
+        assert "recorded 2026-06-15" in out
+        assert "conf 90%" in out
+        assert "active" not in out  # only non-active statuses shown
+
+    def test_record_text_redacted(self):
+        r = _record("secret")
+        r["redacted"] = True
+        assert _record_text(r).startswith("[redacted]")
+
+    def test_conflict_lines_header_and_members(self):
+        lines = _conflict_lines(_conflict())
+        assert "[value_disagreement] alice works_at — open" in lines[0]
+        assert any("Google" in line for line in lines)
+        assert any("Meta" in line for line in lines)
+
+
+class TestListConflicts:
+    @pytest.mark.asyncio
+    async def test_list_hits_v1_conflicts_with_scope(self):
+        patcher, mock = _mock_request({
+            "conflicts": [_conflict()], "total": 1, "next_cursor": None,
+        })
+        with patcher:
+            out = await list_conflicts()
+        method, path = mock.call_args[0][:2]
+        assert method == "GET"
+        assert path == "/v1/conflicts"
+        params = mock.call_args[1]["params"]
+        assert params["scope"] == "org:test/user:test"
+        assert params["status"] == "open"
+        assert "value_disagreement" in out
+        assert "Google" in out and "Meta" in out
+
+    @pytest.mark.asyncio
+    async def test_observed_basis_renders_by_in_tool_output(self):
+        c = _conflict(records=[_record("Google", vf_basis="observed")])
+        patcher, _ = _mock_request({"conflicts": [c], "total": 1, "next_cursor": None})
+        with patcher:
+            out = await list_conflicts()
+        assert "by 2020-01-01" in out
+        assert "since 2020-01-01" not in out
+
+    @pytest.mark.asyncio
+    async def test_empty_queue(self):
+        patcher, _ = _mock_request({"conflicts": [], "total": 0, "next_cursor": None})
+        with patcher:
+            out = await list_conflicts()
+        assert "No open conflicts" in out
+
+    @pytest.mark.asyncio
+    async def test_pagination_hint(self):
+        patcher, mock = _mock_request({
+            "conflicts": [_conflict()], "total": 5, "next_cursor": 1,
+        })
+        with patcher:
+            out = await list_conflicts(status="all", limit=1)
+        assert mock.call_args[1]["params"]["status"] == "all"
+        assert "cursor=1" in out
+
+
+class TestResolveConflict:
+    @pytest.mark.asyncio
+    async def test_pick_posts_tagged_body(self):
+        patcher, mock = _mock_request(_conflict(status="manually_resolved"))
+        with patcher:
+            out = await resolve_conflict(
+                conflict_id="c1", action="pick",
+                winner="0197a3a0-0000-7000-8000-00000000000b",
+                reason="user confirmed",
+            )
+        method, path = mock.call_args[0][:2]
+        assert method == "POST"
+        assert path == "/v1/conflicts/c1/resolve"
+        body = mock.call_args[1]["json_body"]
+        assert body == {
+            "action": "pick",
+            "winner": "0197a3a0-0000-7000-8000-00000000000b",
+            "reason": "user confirmed",
+        }
+        assert "manually_resolved" in out
+
+    @pytest.mark.asyncio
+    async def test_split_requires_all_fields(self):
+        patcher, mock = _mock_request({})
+        with patcher:
+            out = await resolve_conflict(
+                conflict_id="c1", action="split", boundary="2024-03",
+            )
+        assert "Invalid resolution" in out
+        assert "earlier" in out
+        mock.assert_not_called()  # nothing hit the wire
+
+    @pytest.mark.asyncio
+    async def test_unknown_action_and_extraneous_args(self):
+        patcher, mock = _mock_request({})
+        with patcher:
+            out1 = await resolve_conflict(conflict_id="c1", action="merge")
+            out2 = await resolve_conflict(
+                conflict_id="c1", action="dismiss", winner="r1",
+            )
+        assert "unknown action" in out1
+        assert "does not accept" in out2
+        mock.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_dismiss_defaults_reason(self):
+        patcher, mock = _mock_request(_conflict(status="dismissed"))
+        with patcher:
+            await resolve_conflict(conflict_id="c1", action="dismiss")
+        assert mock.call_args[1]["json_body"] == {"action": "dismiss", "reason": ""}
+
+
+class TestClaimHistory:
+    @pytest.mark.asyncio
+    async def test_history_hits_endpoint_and_renders_records(self):
+        patcher, mock = _mock_request({
+            "claim": {"scope": "org:test/user:test", "subject": "alice",
+                      "predicate": "works_at"},
+            "history": [
+                _record("Google", valid_to="2022-06-01T00:00:00Z",
+                        vt_basis="observed"),
+                _record("Meta", valid_from="2022-06-01T00:00:00Z",
+                        vf_basis="observed",
+                        rid="0197a3a0-0000-7000-8000-00000000000b"),
+            ],
+            "conflicts": [],
+        })
+        with patcher:
+            out = await claim_history(subject="Alice", predicate="works_at")
+        method, path = mock.call_args[0][:2]
+        assert method == "GET"
+        assert path == "/v1/claims/history"
+        params = mock.call_args[1]["params"]
+        assert params == {
+            "scope": "org:test/user:test",
+            "subject": "Alice",
+            "predicate": "works_at",
+        }
+        # Observed boundaries render as "by", never "since"/"until".
+        assert "ended by 2022-06-01" in out
+        assert "held by 2022-06-01" in out
+        assert "2 record(s)" in out
+
+    @pytest.mark.asyncio
+    async def test_history_lists_conflicts(self):
+        patcher, _ = _mock_request({
+            "claim": {"subject": "alice", "predicate": "works_at"},
+            "history": [_record()],
+            "conflicts": [_conflict()],
+        })
+        with patcher:
+            out = await claim_history(subject="alice", predicate="works_at")
+        assert "1 conflict(s)" in out
+        assert "value_disagreement" in out
+
+    @pytest.mark.asyncio
+    async def test_history_empty(self):
+        patcher, _ = _mock_request({"claim": {}, "history": [], "conflicts": []})
+        with patcher:
+            out = await claim_history(subject="nobody", predicate="none")
+        assert "No recorded history" in out
+
+
 # ---------------------------------------------------------------------------
 # Admin tools
 # ---------------------------------------------------------------------------