confluence-knowledge 0.5.3__tar.gz → 0.5.4__tar.gz

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluence-knowledge
-Version: 0.5.3
+Version: 0.5.4
 Summary: Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service
 License: MIT
 Project-URL: Repository, https://github.com/nkunal1992/agents

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "confluence-knowledge"
-version = "0.5.3"
+version = "0.5.4"
 description = "Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service"
 readme = "README.md"
 requires-python = ">=3.11"

confluence_knowledge-0.5.4/src/confluence_knowledge/feedback.py

@@ -0,0 +1,91 @@
+"""Per-scope human-feedback store — colleague corrections keyed by query
+embedding. Local-first: one JSON file per scope under the index dir;
+`clean` removes them along with the index (documented semantics).
+
+Design rules (from issue #107): corrections are disclosed ALONGSIDE
+documentation — "the docs say X, but a colleague correction says Y" —
+never silently override, never silently dropped.
+"""
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+
+# measured on real bge-m3: identical question 1.00, close paraphrase ~0.77,
+# same-topic different-intent ~0.68, unrelated ~0.39 → 0.75 catches natural
+# rephrases without leaking across topics
+DEFAULT_MIN_SIM = 0.75
+
+
+class FeedbackStore:
+    """JSON list under the index dir; same integrity discipline as Index
+    (tolerant load, atomic writes)."""
+
+    def __init__(self, index_root: Path, scope_key: str, cli: str):
+        self.path = index_root / f"{scope_key}.feedback.json"
+        env_key = cli.upper().replace("-", "_") + "_FEEDBACK_MIN_SIM"
+        self.min_sim = float(os.environ.get(
+            env_key, os.environ.get("KNOWLEDGE_FEEDBACK_MIN_SIM",
+                                    DEFAULT_MIN_SIM)))
+        self._entries = self._load()
+
+    def _load(self) -> list[dict]:
+        if not self.path.exists():
+            return []
+        try:
+            data = json.loads(self.path.read_text())
+            return data if isinstance(data, list) else []
+        except (json.JSONDecodeError, OSError):
+            return []  # corrupt file → start fresh, don't crash the server
+
+    def _save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.path.parent, suffix=".tmp")
+        with os.fdopen(fd, "w") as f:
+            json.dump(self._entries, f)
+        os.replace(tmp, self.path)  # atomic — a crash mid-write can't corrupt
+
+    def add(self, question: str, qvec: np.ndarray, correction: str,
+            note: str = "") -> dict:
+        entry = {"id": f"fb{len(self._entries):04d}",
+                 "question": question,
+                 "qvec": qvec.astype(np.float32).tolist(),
+                 "correction": correction, "note": note,
+                 "ts": int(time.time())}
+        self._entries.append(entry)
+        self._save()
+        return entry
+
+    def match(self, qvec: np.ndarray, k: int = 3) -> list[dict]:
+        """Cosine-similar corrections ≥ min_sim (default 0.75 — catches
+        paraphrases without leaking across topics), best first."""
+        if not self._entries:
+            return []
+        mat = np.array([e["qvec"] for e in self._entries], dtype=np.float32)
+        q = qvec / (np.linalg.norm(qvec) + 1e-9)
+        m = mat / (np.linalg.norm(mat, axis=1, keepdims=True) + 1e-9)
+        sims = m @ q
+        out = []
+        for i in np.argsort(-sims):
+            if sims[i] < self.min_sim or len(out) >= k:
+                break
+            e = dict(self._entries[int(i)])
+            e.pop("qvec", None)
+            e["similarity"] = float(sims[i])
+            e["age_days"] = int((time.time() - e["ts"]) / 86400)
+            out.append(e)
+        return out
+
+    def report(self) -> dict:
+        """Aggregate view for 'which pages keep getting corrected' — the
+        agent summarizes these as outdated/confusing doc candidates."""
+        out = []
+        for e in self._entries:
+            out.append({"question": e["question"], "correction": e["correction"],
+                        "note": e["note"], "age_days":
+                        int((time.time() - e["ts"]) / 86400)})
+        return {"count": len(out), "corrections": out}

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/src/confluence_knowledge/server.py

@@ -16,6 +16,7 @@ from mcp.server.fastmcp import FastMCP
 from .auth import get_credential
 from .client import AccessError, ConfluenceClient, SecurityException, make_client
 from .crawl import Crawler
+from .feedback import FeedbackStore
 from .index import Index
 from .retrieval import (
     MODEL_MARKER as EMBED_MODEL_ID,
@@ -43,6 +44,7 @@ _scopes: dict[str, dict] = {}
 _evidence_sets: dict[str, dict] = {}  # set_id → {scope, ev}
 _indexes: dict[str, Index] = {}  # one connection per DB for the server lifetime
 _clients: dict[str, ConfluenceClient] = {}  # one HTTP pool per credential
+_feedback: dict[str, FeedbackStore] = {}  # per-scope correction stores
 _EMBEDDER = None
 _RERANKER = None
 _SPARSE = None
@@ -85,6 +87,14 @@ def _index_for(scope_key: str) -> Index:
     return idx
 
 
+def _feedback_for(scope_key: str) -> FeedbackStore:
+    st = _feedback.get(scope_key)
+    if st is None:
+        st = _feedback[scope_key] = FeedbackStore(
+            workspace_index_root(_workdir()), scope_key, "confluence-knowledge")
+    return st
+
+
 def _embedder():
     global _EMBEDDER
     with _model_lock:
@@ -331,7 +341,11 @@ def search(scope_handle: str, question: str) -> dict:
         return {"evidence": [], "coverage": "stale_model",
                 "note": "this index was built with an older embedding model "
                         "— run start_crawl once to rebuild it, then search again"}
-    ev = retrieve(idx, question, _embedder(), _reranker(), sparse=_sparse())
+    emb = _embedder()
+    ev = retrieve(idx, question, emb, _reranker(), sparse=_sparse())
+    # colleague corrections matching this question ride along — the agent
+    # must disclose them, so they're part of the response, not a separate call
+    corrections = _feedback_for(s["key"]).match(emb.embed([question])[0])
     set_id = f"ev:{len(_evidence_sets)}:{s['key'][:8]}"
     # bound the session cache — sets are never reused after the turn ends
     while len(_evidence_sets) >= 32:
@@ -341,6 +355,7 @@ def search(scope_handle: str, question: str) -> dict:
         "evidence_set": set_id,
         "coverage": _coverage(idx),
         "as_of": st["as_of"],
+        "user_corrections": corrections,
         "evidence": [
             {"chunk_id": e["chunk_id"], "page_title": e["page_title"],
              "page_url": e["page_url"], "heading": e["heading"],
@@ -369,6 +384,28 @@ def get_evidence(scope_handle: str, chunk_ids: list[str]) -> dict:
     return {"chunks": out}
 
 
+@mcp.tool()
+def submit_feedback(scope_handle: str, question: str, correction: str,
+                    note: str = "") -> dict:
+    """Store a colleague correction — disclosed alongside the docs on
+    similar future questions (never overrides them)."""
+    s = _scope(scope_handle)
+    if not _models_loaded(0):
+        return {"stored": False, "note": LOADING_NOTE}
+    qvec = _embedder().embed([question])[0]
+    entry = _feedback_for(s["key"]).add(question, qvec, correction, note)
+    return {"stored": entry["id"],
+            "note": "will be disclosed on similar questions"}
+
+
+@mcp.tool()
+def feedback_report(scope_handle: str) -> dict:
+    """Aggregated corrections — which topics keep getting corrected points
+    at outdated/confusing documentation."""
+    s = _scope(scope_handle)
+    return _feedback_for(s["key"]).report()
+
+
 @mcp.tool()
 def verify_citations(scope_handle: str, evidence_set: str,
                      mappings: list[dict]) -> dict:

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/src/confluence_knowledge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluence-knowledge
-Version: 0.5.3
+Version: 0.5.4
 Summary: Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service
 License: MIT
 Project-URL: Repository, https://github.com/nkunal1992/agents

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/src/confluence_knowledge.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/confluence_knowledge/client.py
 src/confluence_knowledge/crawl.py
 src/confluence_knowledge/extract.py
 src/confluence_knowledge/extract_files.py
+src/confluence_knowledge/feedback.py
 src/confluence_knowledge/health.py
 src/confluence_knowledge/index.py
 src/confluence_knowledge/models.lock.json
@@ -25,6 +26,7 @@ tests/test_agent_doc_consistency.py
 tests/test_client_get_only.py
 tests/test_crawl.py
 tests/test_extract.py
+tests/test_feedback.py
 tests/test_health_checks.py
 tests/test_index.py
 tests/test_prepare_models.py

{confluence_knowledge-0.5.3 → confluence_knowledge-0.5.4}/tests/test_agent_doc_consistency.py

@@ -32,3 +32,21 @@ def test_agent_references_repo_files_that_exist():
     doc = AGENT.read_text()
     for m in re.findall(r"prompts/([\w.-]+)", doc):
         assert (REPO / "prompts" / m).exists(), f"agent references missing prompts/{m}"
+
+
+def test_agent_frontmatter_tools_exist():
+    """Every tool named in the agent's frontmatter must be a real
+    @mcp.tool() in the server source."""
+    if not AGENT.exists():
+        import pytest
+        pytest.skip("agent file not in this checkout layout")
+    doc = AGENT.read_text()
+    tools_line = re.search(r'tools:\s*\[([^\]]+)\]', doc).group(1)
+    declared = {t.strip().strip('"').split("/")[1]
+                for t in tools_line.split(",")
+                if "confluence-knowledge/" in t}
+    srv = (Path(__file__).parents[1] / "src" /
+           "confluence_knowledge" / "server.py").read_text()
+    real = set(re.findall(r"@mcp\.tool\(\)\s*\ndef\s+(\w+)", srv))
+    missing = declared - real
+    assert not missing, f"agent frontmatter names tools not in server: {missing}"

confluence_knowledge-0.5.4/tests/test_feedback.py

@@ -0,0 +1,106 @@
+"""FeedbackStore: per-scope corrections, threshold matching, integrity."""
+
+import numpy as np
+
+from confluence_knowledge.feedback import FeedbackStore
+
+
+def _v(seed: int) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    v = rng.random(16).astype(np.float32)
+    return v / np.linalg.norm(v)
+
+
+def test_add_and_match(tmp_path):
+    st = FeedbackStore(tmp_path, "scope1", "ck-test")
+    st.add("password policy?", _v(1), "it is actually 16 chars")
+    hits = st.match(_v(1))
+    assert len(hits) == 1 and hits[0]["correction"].startswith("it is")
+    assert "qvec" not in hits[0] and hits[0]["similarity"] >= 0.85
+
+
+def test_threshold_rejects_unrelated(tmp_path):
+    st = FeedbackStore(tmp_path, "scope1", "ck-test")
+    st.add("password policy?", _v(1), "correction")
+    # orthogonal vector — sim 0.0 (16-dim random vectors can collide at >0.75)
+    q = np.zeros(16, dtype=np.float32)
+    q[7] = 1.0
+    stored = np.array([np.array(e["qvec"]) for e in st._entries])
+    assert float(q @ stored[0]) < 0.75
+    assert st.match(q) == []
+
+
+def test_scopes_isolated(tmp_path):
+    a = FeedbackStore(tmp_path, "scopeA", "ck-test")
+    b = FeedbackStore(tmp_path, "scopeB", "ck-test")
+    a.add("q", _v(1), "for A only")
+    assert b.match(_v(1)) == []
+    assert a.path.name != b.path.name
+
+
+def test_corrupt_file_tolerated(tmp_path):
+    (tmp_path / "scope1.feedback.json").write_text("{not json!!")
+    st = FeedbackStore(tmp_path, "scope1", "ck-test")
+    assert st.report()["count"] == 0  # loads empty, doesn't crash
+
+
+def test_persists_across_instances(tmp_path):
+    FeedbackStore(tmp_path, "s", "ck-test").add("q", _v(2), "corr")
+    st = FeedbackStore(tmp_path, "s", "ck-test")
+    assert st.report()["count"] == 1
+
+
+def test_report_shape(tmp_path):
+    st = FeedbackStore(tmp_path, "s", "ck-test")
+    st.add("q1", _v(1), "c1", note="why")
+    r = st.report()
+    assert r["count"] == 1
+    assert r["corrections"][0]["note"] == "why"
+    assert "qvec" not in r["corrections"][0]
+
+
+def test_search_injects_corrections(tmp_path, monkeypatch):
+    """submit_feedback → a similar question's search carries it through."""
+    from confluence_knowledge import server
+    from confluence_knowledge.extract import Chunk
+    from confluence_knowledge.index import Index
+    server._scopes.clear()
+    server._feedback.clear()
+    server._evidence_sets.clear()
+    monkeypatch.setenv("CONF_KNOWLEDGE_WORKDIR", str(tmp_path))
+    monkeypatch.setenv("CONF_KNOWLEDGE_HOME", str(tmp_path / "home"))
+    (tmp_path / "home").mkdir()
+
+    s = {"key": "k123", "profile": None, "root": "r"}
+    server._scopes["scope:k:r"] = s
+
+    # index with one page so search doesn't early-return "empty"
+    idx = Index(tmp_path / ".conf_knowledge_index" / "k123.db")
+    c = Chunk(text="old answer text", heading_path="", kind="text",
+              ordinal=0, chunk_id="p1:0:0")
+    idx.upsert_page({"page_id": "p1", "parent_id": None, "title": "P",
+                     "url": "u", "level": 0, "version": "", "warnings": ""},
+                    [c], vecs=None, sparse=None)
+    idx.publish({"p1"})
+
+    import rag.conftest as rc
+    emb = rc.HashEmbedder()
+    monkeypatch.setattr(server, "_embedder", lambda: emb)
+    monkeypatch.setattr(server, "_reranker", lambda: None)
+    monkeypatch.setattr(server, "_sparse", lambda: None)
+    monkeypatch.setattr(server, "_models_loaded", lambda _w: True)
+    monkeypatch.setattr(server, "_index_for", lambda k: idx)
+    monkeypatch.setattr(server, "_feedback_for",
+                        lambda k: server._feedback.setdefault(
+                            k, server.FeedbackStore(
+                                tmp_path / ".conf_knowledge_index",
+                                k, "confluence-knowledge")))
+
+    server.submit_feedback("scope:k:r", "what is the password policy",
+                           "14 is wrong, it's 16")
+    res = server.search("scope:k:r", "what is the password policy")
+    assert res["user_corrections"] and \
+        res["user_corrections"][0]["correction"] == "14 is wrong, it's 16"
+    # unrelated question → no injection
+    res2 = server.search("scope:k:r", "zebra quantum xyzzy nonsense")
+    assert res2["user_corrections"] == []