devmem-agents 0.1.0__py3-none-any.whl

devmem/live_backend.py

@@ -0,0 +1,344 @@
+"""Live backend connectivity config and helpers.
+
+This module is used by integration tests that probe live Aurora, Neptune,
+and Milvus systems. Values come from DEVMEM_* environment variables and can
+optionally fall back to a TOML reference file (``devmem.toml`` by default).
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterator
+from urllib.parse import quote
+from urllib.parse import urlparse
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _coerce_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _coerce_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _parse_bool(value: Any, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    import tomllib
+
+    with path.open("rb") as handle:
+        parsed = tomllib.load(handle)
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _nested_get(payload: dict[str, Any], *keys: str) -> Any:
+    current: Any = payload
+    for key in keys:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current
+
+
+@dataclass(frozen=True)
+class LiveBackendConfig:
+    """Resolved live-backend test configuration."""
+
+    namespace: str
+    enable_live_connectivity: bool
+    allow_writes: bool
+
+    aurora_dsn: str | None
+
+    neptune_endpoint: str | None
+    neptune_region: str | None
+    neptune_port: int
+    neptune_use_https: bool
+    neptune_iam_auth: bool
+    neptune_query_language: str
+    neptune_timeout: float
+    neptune_use_ssh_tunnel: bool
+    neptune_ssh_host: str | None
+    neptune_ssh_user: str | None
+    neptune_ssh_key_path: str | None
+    neptune_ssh_key_passphrase: str | None
+
+    milvus_uri: str | None
+    milvus_host: str | None
+    milvus_port: int
+    milvus_secure: bool
+    milvus_user: str | None
+    milvus_password: str | None
+    milvus_token: str | None
+    milvus_timeout: float
+
+    tcp_timeout_seconds: float
+
+    @property
+    def has_any_target(self) -> bool:
+        return bool(self.aurora_dsn or self.neptune_endpoint or self.milvus_uri or self.milvus_host)
+
+
+def _normalise_aurora_dsn(raw: str | None) -> str | None:
+    if not raw:
+        return None
+    # Allow SQLAlchemy-style DSNs from reference files.
+    uri = raw.replace("postgresql+psycopg2://", "postgresql://")
+
+    # Some reference files contain unescaped passwords in URI form. This helper
+    # rewrites only the userinfo section to URL-safe encoding.
+    if "://" not in uri or "@" not in uri:
+        return uri
+    try:
+        parsed = urlparse(uri)
+        if parsed.hostname and not (parsed.fragment and "@" in parsed.fragment):
+            return uri
+    except ValueError:
+        pass
+
+    scheme, rest = uri.split("://", 1)
+    userinfo, hostpart = rest.rsplit("@", 1)
+    if ":" in userinfo:
+        user, password = userinfo.split(":", 1)
+        encoded_userinfo = f"{quote(user, safe='')}:{quote(password, safe='')}"
+    else:
+        encoded_userinfo = quote(userinfo, safe="")
+    return f"{scheme}://{encoded_userinfo}@{hostpart}"
+
+
+def _resolve_reference_toml() -> Path | None:
+    raw = _coerce_str(os.getenv("DEVMEM_LIVE_TOML_PATH"))
+    if raw:
+        return Path(raw).expanduser()
+    for candidate in (Path.cwd() / "devmem.toml", Path.home() / ".config" / "devmem" / "devmem.toml"):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_live_backend_config() -> LiveBackendConfig:
+    """Load connectivity config from env with optional TOML fallback."""
+    reference: dict[str, Any] = {}
+    toml_path = _resolve_reference_toml()
+    if toml_path:
+        reference = _load_toml(toml_path)
+
+    namespace = _coerce_str(os.getenv("DEVMEM_NAMESPACE")) or _coerce_str(reference.get("DEVMEM_NAMESPACE")) or "devlib_v1"
+
+    aurora_dsn = _normalise_aurora_dsn(
+        _coerce_str(os.getenv("DEVMEM_AURORA_DSN"))
+        or _coerce_str(reference.get("AURORA_DSN"))
+        or _coerce_str(reference.get("DATABASE_URL"))
+    )
+
+    neptune_endpoint = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_ENDPOINT"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "ENDPOINT"))
+    )
+    neptune_region = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_REGION"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "REGION"))
+        or _coerce_str(os.getenv("AWS_REGION"))
+        or _coerce_str(os.getenv("AWS_DEFAULT_REGION"))
+    )
+    neptune_port = _coerce_int(
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_PORT")) or _nested_get(reference, "NEPTUNE", "PORT"),
+        default=8182,
+    )
+    neptune_use_https = _parse_bool(
+        os.getenv("DEVMEM_NEPTUNE_USE_HTTPS") or _nested_get(reference, "NEPTUNE", "USE_HTTPS"),
+        default=True,
+    )
+    neptune_iam_auth = _parse_bool(
+        os.getenv("DEVMEM_NEPTUNE_IAM_AUTH") or _nested_get(reference, "NEPTUNE", "IAM_AUTH"),
+        default=True,
+    )
+    neptune_query_language = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_QUERY_LANGUAGE"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "QUERY_LANGUAGE"))
+        or "opencypher"
+    )
+    neptune_timeout = float(
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_TIMEOUT"))
+        or _nested_get(reference, "NEPTUNE", "TIMEOUT")
+        or 10.0
+    )
+    neptune_use_ssh_tunnel = _parse_bool(
+        os.getenv("DEVMEM_NEPTUNE_USE_SSH_TUNNEL") or _nested_get(reference, "NEPTUNE", "USE_SSH_TUNNEL"),
+        default=False,
+    )
+    neptune_ssh_host = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_SSH_HOST"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "SSH_HOST"))
+    )
+    neptune_ssh_user = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_SSH_USER"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "SSH_USER"))
+    )
+    neptune_ssh_key_path = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_SSH_KEY_PATH"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "SSH_KEY_PATH"))
+    )
+    neptune_ssh_key_passphrase = (
+        _coerce_str(os.getenv("DEVMEM_NEPTUNE_SSH_KEY_PASSPHRASE"))
+        or _coerce_str(_nested_get(reference, "NEPTUNE", "SSH_KEY_PASSPHRASE"))
+    )
+
+    milvus_uri = (
+        _coerce_str(os.getenv("DEVMEM_MILVUS_URI"))
+        or _coerce_str(_nested_get(reference, "MILVUS", "URI"))
+    )
+    milvus_host = (
+        _coerce_str(os.getenv("DEVMEM_MILVUS_HOST"))
+        or _coerce_str(_nested_get(reference, "MILVUS", "HOST"))
+    )
+    milvus_port = _coerce_int(
+        _coerce_str(os.getenv("DEVMEM_MILVUS_PORT")) or _nested_get(reference, "MILVUS", "PORT"),
+        default=19530,
+    )
+    milvus_secure = _parse_bool(
+        os.getenv("DEVMEM_MILVUS_SECURE") or _nested_get(reference, "MILVUS", "SECURE"),
+        default=False,
+    )
+    milvus_user = (
+        _coerce_str(os.getenv("DEVMEM_MILVUS_USER"))
+        or _coerce_str(_nested_get(reference, "MILVUS", "USER"))
+    )
+    milvus_password = (
+        _coerce_str(os.getenv("DEVMEM_MILVUS_PASSWORD"))
+        or _coerce_str(_nested_get(reference, "MILVUS", "PASSWORD"))
+    )
+    milvus_token = (
+        _coerce_str(os.getenv("DEVMEM_MILVUS_TOKEN"))
+        or _coerce_str(_nested_get(reference, "MILVUS", "TOKEN"))
+    )
+    milvus_timeout = float(
+        _coerce_str(os.getenv("DEVMEM_MILVUS_TIMEOUT"))
+        or _nested_get(reference, "MILVUS", "TIMEOUT")
+        or 10.0
+    )
+
+    tcp_timeout = float(_coerce_str(os.getenv("DEVMEM_LIVE_TCP_TIMEOUT")) or 5.0)
+
+    return LiveBackendConfig(
+        namespace=namespace,
+        enable_live_connectivity=_env_bool("DEVMEM_LIVE_CONNECTIVITY", default=False),
+        allow_writes=_env_bool("DEVMEM_LIVE_ALLOW_WRITES", default=False),
+        aurora_dsn=aurora_dsn,
+        neptune_endpoint=neptune_endpoint,
+        neptune_region=neptune_region,
+        neptune_port=neptune_port,
+        neptune_use_https=neptune_use_https,
+        neptune_iam_auth=neptune_iam_auth,
+        neptune_query_language=neptune_query_language,
+        neptune_timeout=neptune_timeout,
+        neptune_use_ssh_tunnel=neptune_use_ssh_tunnel,
+        neptune_ssh_host=neptune_ssh_host,
+        neptune_ssh_user=neptune_ssh_user,
+        neptune_ssh_key_path=neptune_ssh_key_path,
+        neptune_ssh_key_passphrase=neptune_ssh_key_passphrase,
+        milvus_uri=milvus_uri,
+        milvus_host=milvus_host,
+        milvus_port=milvus_port,
+        milvus_secure=milvus_secure,
+        milvus_user=milvus_user,
+        milvus_password=milvus_password,
+        milvus_token=milvus_token,
+        milvus_timeout=milvus_timeout,
+        tcp_timeout_seconds=tcp_timeout,
+    )
+
+
+def parse_host_port_from_url(url: str, default_port: int) -> tuple[str, int]:
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    port = parsed.port or default_port
+    return host, port
+
+
+def parse_postgres_host_port(dsn: str) -> tuple[str, int]:
+    normalized = _normalise_aurora_dsn(dsn) or dsn
+    parsed = urlparse(normalized)
+    host = parsed.hostname or ""
+    try:
+        port = parsed.port or 5432
+    except ValueError:
+        port = 5432
+        host = ""
+
+    if host:
+        return host, port
+
+    # Fallback parser for malformed but common DSN patterns.
+    rest = normalized.split("://", 1)[-1]
+    host_part = rest.rsplit("@", 1)[-1]
+    host_port = host_part.split("/", 1)[0]
+    if ":" in host_port:
+        host_value, port_raw = host_port.rsplit(":", 1)
+        return host_value, _coerce_int(port_raw, default=5432)
+    return host_port, 5432
+
+
+def tcp_connect(host: str, port: int, timeout: float) -> None:
+    with socket.create_connection((host, port), timeout=timeout):
+        return None
+
+
+@contextmanager
+def neptune_tunnel(cfg: LiveBackendConfig) -> Iterator[tuple[str, int]]:
+    """Yield (host, port) for Neptune direct or SSH tunnel access."""
+    if not cfg.neptune_use_ssh_tunnel:
+        if not cfg.neptune_endpoint:
+            raise ValueError("Neptune endpoint is not configured")
+        yield cfg.neptune_endpoint, cfg.neptune_port
+        return
+
+    if not cfg.neptune_ssh_host or not cfg.neptune_ssh_user or not cfg.neptune_ssh_key_path:
+        raise ValueError("SSH tunnel enabled but host/user/key path are missing")
+    if not cfg.neptune_endpoint:
+        raise ValueError("Neptune endpoint is required when SSH tunnel is enabled")
+
+    sshtunnel = __import__("sshtunnel")
+    paramiko = __import__("paramiko")
+    if not hasattr(paramiko, "DSSKey"):
+        paramiko.DSSKey = paramiko.RSAKey
+    forwarder = sshtunnel.SSHTunnelForwarder(
+        (cfg.neptune_ssh_host, 22),
+        ssh_username=cfg.neptune_ssh_user,
+        ssh_pkey=str(Path(cfg.neptune_ssh_key_path).expanduser()),
+        ssh_private_key_password=cfg.neptune_ssh_key_passphrase,
+        remote_bind_address=(cfg.neptune_endpoint, cfg.neptune_port),
+        local_bind_address=("127.0.0.1", 0),
+        allow_agent=False,
+        host_pkey_directories=[],
+    )
+    forwarder.start()
+    try:
+        yield "127.0.0.1", int(forwarder.local_bind_port)
+    finally:
+        forwarder.stop()

devmem/main.py

@@ -0,0 +1,11 @@
+"""Application entrypoint for devmem."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from devmem.api import router
+from devmem.config import settings
+
+app = FastAPI(title=settings.service_name, version=settings.service_version)
+app.include_router(router)

devmem/models.py

@@ -0,0 +1,157 @@
+"""API models for devmem."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class ApiResponse(BaseModel):
+    ok: bool = True
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+class NamespaceScoped(BaseModel):
+    namespace: str
+
+
+class SessionStartRequest(NamespaceScoped):
+    project: str
+    repo: str
+    branch: str
+    agent: str
+    task: str
+
+
+class SessionStartResponse(BaseModel):
+    session_id: str = Field(default_factory=lambda: str(uuid4()))
+    started_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class ContextPullRequest(NamespaceScoped):
+    session_id: str
+    project: str
+    repo: str
+    task: str
+    top_k: int = 8
+
+
+class HybridSearchRequest(NamespaceScoped):
+    q: str
+    project: str
+    repo: str
+    top_k: int = 8
+    filters: dict[str, Any] = Field(default_factory=dict)
+
+
+class ArtifactUpsertRequest(NamespaceScoped):
+    session_id: str
+    artifact_type: str
+    title: str
+    content: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class FactUpsertRequest(NamespaceScoped):
+    session_id: str
+    subject: str
+    predicate: str
+    object: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class DecisionUpsertRequest(NamespaceScoped):
+    session_id: str
+    title: str
+    decision: str
+    rationale: str
+    alternatives: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class HandoffCreateRequest(NamespaceScoped):
+    session_id: str
+    from_agent: str
+    to_agent: str
+    summary: str
+    next_steps: list[str] = Field(default_factory=list)
+    blockers: list[str] = Field(default_factory=list)
+
+
+class TaskUpdateRequest(NamespaceScoped):
+    session_id: str
+    status: str
+    note: str = ""
+
+
+class FeedbackRecordRequest(NamespaceScoped):
+    session_id: str
+    outcome: str
+    score: float | None = None
+    notes: str = ""
+
+
+class TaskSimilarRequest(NamespaceScoped):
+    q: str
+    project: str | None = None
+    repo: str | None = None
+    top_k: int = 5
+
+
+# --------------------------------------------------------------------------
+# Session commit (Pass 2 — atomic multi-write finalization)
+# --------------------------------------------------------------------------
+
+
+class CommitArtifact(BaseModel):
+    artifact_type: str
+    title: str
+    content: str
+    project: str | None = None
+    repo: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class CommitDecision(BaseModel):
+    title: str
+    decision: str
+    rationale: str
+    alternatives: list[str] = Field(default_factory=list)
+    project: str | None = None
+    repo: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class CommitHandoff(BaseModel):
+    from_agent: str
+    to_agent: str
+    summary: str
+    next_steps: list[str] = Field(default_factory=list)
+    blockers: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class CommitTaskUpdate(BaseModel):
+    status: str
+    note: str = ""
+
+
+class SessionCommitRequest(NamespaceScoped):
+    """Finalize a session with one atomic multi-write.
+
+    Replaces the 3-call ritual of `/v1/artifacts/upsert` +
+    `/v1/decisions/upsert` + `/v1/tasks/update`.
+
+    `client_commit_id`, when provided, enables safe retries — a second commit
+    with the same id returns the original result without re-inserting rows.
+    """
+
+    session_id: str
+    artifacts: list[CommitArtifact] = Field(default_factory=list)
+    decisions: list[CommitDecision] = Field(default_factory=list)
+    handoff: CommitHandoff | None = None
+    task_update: CommitTaskUpdate | None = None
+    client_commit_id: str | None = None

devmem/retrieval_eval.py

@@ -0,0 +1,145 @@
+"""Evaluate retrieval quality against live ingested project memory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from devmem.live_backend import LiveBackendConfig
+from devmem.storage.milvus_store import MilvusStore
+from devmem.storage.neptune_store import NeptuneStore
+
+
+@dataclass(frozen=True)
+class RetrievalCase:
+    """Expected retrieval behavior for a natural-language query."""
+
+    case_id: str
+    query: str
+    expected_path_contains: tuple[str, ...]
+    expected_terms: tuple[str, ...] = ()
+
+
+def load_cases(path: Path) -> list[RetrievalCase]:
+    """Load retrieval cases from JSON."""
+    import json
+
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, list):
+        raise ValueError("cases file must contain a JSON array")
+
+    cases: list[RetrievalCase] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        case_id = str(item.get("id") or "").strip()
+        query = str(item.get("query") or "").strip()
+        path_contains = item.get("expected_path_contains") or []
+        expected_terms = item.get("expected_terms") or []
+        if not case_id or not query or not isinstance(path_contains, list) or not path_contains:
+            raise ValueError(f"invalid retrieval case: {item}")
+        cases.append(
+            RetrievalCase(
+                case_id=case_id,
+                query=query,
+                expected_path_contains=tuple(str(x) for x in path_contains),
+                expected_terms=tuple(str(x) for x in expected_terms if str(x).strip()),
+            )
+        )
+    return cases
+
+
+def _path_matches(path: str, expected_fragments: Iterable[str]) -> bool:
+    path_lc = path.lower()
+    return any(fragment.lower() in path_lc for fragment in expected_fragments)
+
+
+def _row_has_terms(row: dict[str, Any], expected_terms: tuple[str, ...]) -> bool:
+    if not expected_terms:
+        return True
+    content = str(row.get("content") or "").lower()
+    return all(term.lower() in content for term in expected_terms)
+
+
+def _evaluate_single_case(
+    *,
+    case: RetrievalCase,
+    rows: list[dict[str, Any]],
+    kg_paths: set[str],
+) -> dict[str, Any]:
+    matches: list[dict[str, Any]] = []
+    for row in rows:
+        path = str(row.get("path") or "")
+        if not path:
+            continue
+        if not _path_matches(path, case.expected_path_contains):
+            continue
+        if not _row_has_terms(row, case.expected_terms):
+            continue
+        matches.append(row)
+
+    kg_match = any(_path_matches(path, case.expected_path_contains) for path in kg_paths)
+    return {
+        "case_id": case.case_id,
+        "query": case.query,
+        "passed": bool(matches),
+        "kg_match": kg_match,
+        "matches": [
+            {
+                "path": str(match.get("path") or ""),
+                "chunk_index": match.get("chunk_index"),
+                "score": match.get("score"),
+            }
+            for match in matches[:5]
+        ],
+    }
+
+
+def evaluate_retrieval(
+    *,
+    cfg: LiveBackendConfig,
+    namespace: str,
+    project_id: str,
+    repo_id: str,
+    cases: list[RetrievalCase],
+    top_k: int = 8,
+) -> dict[str, Any]:
+    """Run retrieval evaluation cases against Milvus and Neptune."""
+    milvus = MilvusStore(cfg, namespace=namespace, project_id=project_id, repo_id=repo_id)
+    neptune = NeptuneStore(cfg, namespace=namespace)
+
+    try:
+        milvus.connect()
+        neptune.connect()
+        neptune.health_check()
+
+        kg_paths = set(neptune.list_project_files(project_id=project_id, repo_id=repo_id, limit=100000))
+
+        case_results: list[dict[str, Any]] = []
+        for case in cases:
+            rows = milvus.lexical_search(query_text=case.query, top_k=top_k)
+            case_results.append(_evaluate_single_case(case=case, rows=rows, kg_paths=kg_paths))
+
+        passed = sum(1 for item in case_results if item.get("passed"))
+        kg_covered = sum(1 for item in case_results if item.get("kg_match"))
+        total = len(case_results)
+
+        return {
+            "summary": {
+                "total_cases": total,
+                "passed_cases": passed,
+                "pass_rate": (float(passed) / float(total)) if total else 0.0,
+                "kg_covered_cases": kg_covered,
+                "kg_coverage_rate": (float(kg_covered) / float(total)) if total else 0.0,
+                "namespace": namespace,
+                "project_id": project_id,
+                "repo_id": repo_id,
+                "milvus_collection": milvus.collection_name,
+                "neptune_endpoint": neptune.endpoint_summary(),
+            },
+            "results": case_results,
+        }
+    finally:
+        neptune.close()
+        milvus.close()