codespy-ai 2.0.1__tar.gz → 2.1.0__tar.gz

{codespy_ai-2.0.1 → codespy_ai-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespy-ai
-Version: 2.0.1
+Version: 2.1.0
 Summary: Code review agent powered by DSPy
 License: MIT
 License-File: LICENSE
@@ -23,7 +23,7 @@ Requires-Dist: cloudpickle (>=3.1.2,<4.0.0)
 Requires-Dist: ddgs (>=8.0.0)
 Requires-Dist: dspy[mcp] (>=3.3.0,<4.0.0)
 Requires-Dist: gitpython (>=3.1.42)
-Requires-Dist: hindsight-api-slim (>=0.10.1)
+Requires-Dist: hindsight-api-slim (>=1.0.0,<2)
 Requires-Dist: httpx (>=0.28.0)
 Requires-Dist: json-repair (>=0.60.1)
 Requires-Dist: litellm (>=1.84.0,<2.0.0)

{codespy_ai-2.0.1 → codespy_ai-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "codespy-ai"
-version = "2.0.1"
+version = "2.1.0"
 description = "Code review agent powered by DSPy"
 readme = "README.md"
 license = "MIT"
@@ -53,7 +53,7 @@ beautifulsoup4 = ">=4.12.0"
 markdownify = ">=0.15.0"
 ddgs = ">=8.0.0"
 pg0-embedded = ">=0.15"
-hindsight-api-slim = ">=0.10.1"
+hindsight-api-slim = ">=1.0.0,<2"
 
 [tool.poetry.group.dev.dependencies]
 pytest = ">=8.0.0"

{codespy_ai-2.0.1 → codespy_ai-2.1.0}/src/codespy/__init__.py

@@ -1,3 +1,3 @@
 """codespy - Code review agent powered by DSPy."""
 
-__version__ = "2.0.1"
+__version__ = "2.1.0"

{codespy_ai-2.0.1 → codespy_ai-2.1.0}/src/codespy/agents/memory/cerebral/cerebral.py

@@ -33,7 +33,7 @@ HINDSIGHT_SCHEMA_DEFAULT = "semantic"
 # needs sentence-transformers and emits a misleading startup warning
 # (hindsight_api/config.py _validate). That config is built and cached at IMPORT
 # time — the `from hindsight_api import MemoryEngine` below pulls in
-# engine.llm_wrapper, whose module-level _get_raw_config() calls
+# engine.llm_wrapper, which builds Hindsight's cached config via
 # HindsightConfig.from_env(). So these env vars MUST be set before that import
 # line, not in Cerebral.__init__ (too late). We inject our own LiteLLM-SDK
 # embeddings and an RRF-passthrough cross-encoder in Cerebral.__init__, so the
@@ -61,20 +61,12 @@ from hindsight_api.extensions.builtin.tenant import DefaultTenantExtension
 from hindsight_api.models import RequestContext
 from hindsight_api.worker.exceptions import DeferOperation
 
-# Install delta operations coercion shim for string-encoded operations
-# (see delta_ops_compat.py for details)
-from codespy.agents.memory.cerebral.delta_ops_compat import install_delta_ops_coercion
-
-install_delta_ops_coercion()
-
-# Install native structured output support and Bedrock schema sanitizer
+# Register native structured output for Bedrock models litellm's map lacks the flag for
 from codespy.agents.memory.cerebral.structured_output import (
-    install_bedrock_schema_sanitizer,
     register_native_structured_output_overrides,
 )
 
 register_native_structured_output_overrides()
-install_bedrock_schema_sanitizer()
 
 
 class _SchemaSyncTaskBackend(SyncTaskBackend):
@@ -233,13 +225,14 @@ from codespy.agents.memory.cerebral.cost import (
     MeteredLiteLLMSDKEmbeddings,
     register_cerebral_cost_recorder,
 )
-from codespy.agents.memory.cerebral.routines import ensure_maintenance_routines
 from codespy.agents.memory.prefrontal.reach import (
     TAG_ORG,
     TAG_PROJECT_SCOPE,
     TAG_REPO,
+    is_root_scope,
     mental_model_id,
     repo_tags,
+    root_scope_id,
     scope_tags,
 )
 
@@ -281,17 +274,23 @@ HINDSIGHT_SCHEMA = HINDSIGHT_SCHEMA_DEFAULT
 # - include_chunks=False: Observation text only (no file chunks)
 # - reflect_search_observations_max_tokens=3000: Down from 5000 default
 # - reflect_search_observations_include_entities=False: Exclude entity metadata
+# - budget=low: a refresh gets reflect_max_iterations // 2 iterations, like Prefrontal
+#   reflect (Hindsight treats a null budget as MID for refreshes)
+# - keep_trace=True: store the refresh trace with the briefing
+# Key names must be exact: create_mental_model stores the dict without validating it.
 _BRIEFING_TRIGGER_STATIC = {
     "mode": "delta",
     "exclude_mental_models": True,
     "include_chunks": False,
     "reflect_search_observations_max_tokens": 3000,
     "reflect_search_observations_include_entities": False,
+    "budget": "low",
+    "keep_trace": True,
 }
 
-# Content Hindsight's HTTP API gives a mental model before its first refresh.
-# Prefrontal skips briefings that still hold it.
-MENTAL_MODEL_PLACEHOLDER = "Generating content..."
+# Content pre-1.0 Hindsight gave a mental model before its first refresh.
+# Only used to clear it from upgraded rows (see Cerebral._clear_legacy_placeholders).
+_LEGACY_PLACEHOLDER = "Generating content..."
 
 # Generic (not code-review specific) question each briefing answers.
 MENTAL_MODEL_SOURCE_QUERY = (
@@ -300,6 +299,26 @@ MENTAL_MODEL_SOURCE_QUERY = (
     "dependencies and integrations, pitfalls and recurring problems, facts shown to be wrong."
 )
 
+# Question the repo-root briefing answers. The root scope of a monorepo sees
+# facts from many scopes; this briefing must keep only what holds for all of them.
+ROOT_MENTAL_MODEL_SOURCE_QUERY = (
+    "What should an agent starting work anywhere in this repository know, that holds for "
+    "every scope of it: repository layout and naming conventions, how scopes and manifests "
+    "are organized, shared tooling, build, CI and deployment, cross-scope integrations and "
+    "contracts, and repository-wide pitfalls or facts shown to be wrong. "
+    "Do not describe individual services, packages or libraries, their files, pull requests "
+    "or review findings; omit anything that is true for only one scope."
+)
+
+# A delta refresh only adds content, so briefings grow past max_tokens. Past this
+# factor of max_tokens, consolidate_run forces one full refresh (rewrite from scratch).
+BRIEFING_FULL_REFRESH_FACTOR = 1.5
+
+
+def _estimate_tokens(text: str) -> int:
+    """Cheap token estimate (~4 chars per token), same heuristic as prefrontal.format."""
+    return (len(text or "") + 3) // 4
+
 OBSERVATIONS_MISSION = (
     "Merge facts about the same subject into one observation. Keep details that matter only "
     "to one kind of work (e.g. documentation, security, dependencies) instead of generalizing "
@@ -443,19 +462,19 @@ class Cerebral:
         # Install two-step structured output fallback when extraction model is configured
         if extraction_llm_model:
             try:
-                from hindsight_api.engine.llm_wrapper import LLMConfig
+                from hindsight_api.engine.llm_wrapper import LLMProvider
                 from codespy.agents.memory.cerebral.structured_output import (
                     install_two_step_structured_output,
                 )
 
-                extraction_cfg = LLMConfig(
+                extraction_llm = LLMProvider(
                     provider="litellm",
                     model=extraction_llm_model,
                     api_key=extraction_llm_api_key,
                     base_url=extraction_llm_base_url or "",
                     reasoning_effort=None,
                 )
-                extraction_impl = extraction_cfg._provider_impl
+                extraction_impl = extraction_llm._provider_impl
                 install_two_step_structured_output(self._engine, extraction_impl)
             except Exception:
                 logger.warning(
@@ -466,11 +485,6 @@ class Cerebral:
 
         self._run_async(self._engine.initialize())
 
-        # One-time repair: install maintenance routines if missing.
-        # This is idempotent and only needed for databases that were migrated
-        # before HINDSIGHT_API_DATABASE_SCHEMA was set to "semantic" (upstream #2638).
-        self._run_async(ensure_maintenance_routines(self._engine, HINDSIGHT_SCHEMA))
-
         # Repair orphaned pending operations left by inline SyncTaskBackend
         from codespy.agents.memory.cerebral.orphans import repair_orphaned_operations
 
@@ -574,14 +588,11 @@ class Cerebral:
                 # pending rows from blocking scoped submissions).
                 "enable_auto_consolidation": False,
             }
-            # Per-scope observation cap (not bank-wide; -1 means unlimited)
-            if self._max_observations_per_scope >= 0:
-                updates["observation_scope_limits"] = [
-                    {
-                        "scope": [f"{TAG_ORG}*", f"{TAG_REPO}*", f"{TAG_PROJECT_SCOPE}*"],
-                        "limit": self._max_observations_per_scope,
-                    }
-                ]
+            # Per-scope observation cap (never the bank-wide max_observations_per_scope).
+            # Sent unconditionally so -1 (unlimited) lifts a previously stored cap.
+            updates["consolidation_strategies"] = self._consolidation_strategies()
+            # Tombstone the deprecated key (bank config merges with `config || $1`).
+            updates["observation_scope_limits"] = None
             self._run_async(
                 self._engine.update_bank_config(
                     self._bank_id,
@@ -589,10 +600,58 @@ class Cerebral:
                     request_context=ctx,
                 )
             )
+            self._clear_legacy_placeholders(ctx)
         except Exception:
             logger.warning("cerebral: failed to configure bank %s", self._bank_id, exc_info=True)
         self._bank_ensured = True
 
+    def _consolidation_strategies(self) -> list[dict[str, Any]]:
+        """``consolidation_strategies`` payload carrying the per-scope observation cap."""
+        return [
+            {
+                "scopes": [
+                    {
+                        "tags": [f"{TAG_ORG}*", f"{TAG_REPO}*", f"{TAG_PROJECT_SCOPE}*"],
+                        "tags_match": "exact",
+                    }
+                ],
+                "max_observations_per_scope": self._max_observations_per_scope,
+            }
+        ]
+
+    def _clear_legacy_placeholders(self, ctx: RequestContext) -> int:
+        """Empty briefings that still hold the pre-1.0 placeholder. Returns the count.
+
+        Pages through every mental model of the bank and rewrites legacy rows
+        with ``content=""`` (what Hindsight 1.0 creates pages with).
+        """
+        cleared = 0
+        offset = 0
+        while True:
+            page = self._run_async(
+                self._engine.list_mental_models(
+                    self._bank_id,
+                    detail="full",
+                    limit=100,
+                    offset=offset,
+                    request_context=ctx,
+                )
+            )
+            for item in page.items:
+                if (item.get("content") or "").strip().startswith(_LEGACY_PLACEHOLDER):
+                    self._run_async(
+                        self._engine.update_mental_model(
+                            self._bank_id, item["id"], content="", request_context=ctx
+                        )
+                    )
+                    cleared += 1
+            offset += len(page.items)
+            if not page.items or offset >= page.total:
+                break
+        if cleared:
+            logger.info("cerebral: cleared legacy placeholder from %d briefing(s)", cleared)
+        return cleared
+
     @staticmethod
     def _mutation_lines(episode: Episode) -> list[str]:
         """Build observation lines from episode mutations.
@@ -823,16 +882,21 @@ class Cerebral:
             if topic.type == "project_scope"
         ]
         # Fallback to repo-root project scope instead of bare [org:, repo:]
-        return scopes or [scope_tags(repo_full_name, repo_full_name)]
+        return scopes or [scope_tags(repo_full_name, root_scope_id(repo_full_name))]
 
     @staticmethod
     def _mental_model_scopes(
         scopes: Sequence[Sequence[str]], repo_full_name: str
     ) -> list[list[str]]:
-        """Observation scopes plus the repo scope ``[org:, repo:]`` (always added, deduped)."""
+        """Observation scopes whose briefings are kept (deduped).
+
+        No bare ``[org:, repo:]`` scope: its briefing would read every fact of
+        the repo (all scopes of a monorepo). Repo-wide knowledge lives in the
+        repo-root scope ``[org:, repo:, project_scope:<repo>]`` instead.
+        """
         out: list[list[str]] = []
         seen: set[tuple[str, ...]] = set()
-        for sc in [*scopes, repo_tags(repo_full_name)]:
+        for sc in scopes:
             key = tuple(sorted(sc))
             if key not in seen:
                 seen.add(key)
@@ -840,15 +904,43 @@ class Cerebral:
         return out
 
     @staticmethod
-    def _mental_model_name(tags: Sequence[str]) -> str:
+    def _scope_id_of(tags: Sequence[str]) -> str | None:
         for tag in tags:
             if tag.startswith(TAG_PROJECT_SCOPE):
-                return f"Briefing: {tag[len(TAG_PROJECT_SCOPE):]}"
+                return tag[len(TAG_PROJECT_SCOPE):]
+        return None
+
+    @staticmethod
+    def _repo_of(tags: Sequence[str]) -> str | None:
         for tag in tags:
-            if tag.startswith("repo:"):
-                return f"Briefing: {tag[len('repo:'):]}"
+            if tag.startswith(TAG_REPO):
+                return tag[len(TAG_REPO):]
+        return None
+
+    @classmethod
+    def _is_root_briefing(cls, tags: Sequence[str]) -> bool:
+        scope_id = cls._scope_id_of(tags)
+        repo = cls._repo_of(tags)
+        return bool(scope_id and repo and is_root_scope(repo, scope_id))
+
+    @classmethod
+    def _mental_model_name(cls, tags: Sequence[str]) -> str:
+        scope_id = cls._scope_id_of(tags)
+        if scope_id:
+            if cls._is_root_briefing(tags):
+                return f"Briefing: {scope_id} (repo-wide)"
+            return f"Briefing: {scope_id}"
+        repo = cls._repo_of(tags)
+        if repo:
+            return f"Briefing: {repo}"
         return "Briefing"
 
+    @classmethod
+    def _mental_model_source_query(cls, tags: Sequence[str]) -> str:
+        if cls._is_root_briefing(tags):
+            return ROOT_MENTAL_MODEL_SOURCE_QUERY
+        return MENTAL_MODEL_SOURCE_QUERY
+
     def _sync_briefing_triggers(self, scopes: list[list[str]]) -> None:
         """Sync briefing triggers to match current settings before consolidation.
 
@@ -863,11 +955,7 @@ class Cerebral:
         if not scopes:
             return
 
-        desired_trigger = {
-            **_BRIEFING_TRIGGER_STATIC,
-            "refresh_after_consolidation": self._mental_models,
-            "min_refresh_interval_seconds": self._min_mental_model_refresh_seconds,
-        }
+        desired_trigger = self._desired_trigger()
 
         for tags in scopes:
             mm_id = mental_model_id(tags)
@@ -891,8 +979,8 @@ class Cerebral:
                             self._engine.create_mental_model(
                                 self._bank_id,
                                 self._mental_model_name(tags),
-                                MENTAL_MODEL_SOURCE_QUERY,
-                                MENTAL_MODEL_PLACEHOLDER,
+                                self._mental_model_source_query(tags),
+                                "",
                                 mental_model_id=mm_id,
                                 tags=sorted(tags),
                                 max_tokens=self._max_mental_model_tokens,
@@ -914,11 +1002,12 @@ class Cerebral:
                             self._engine.get_mental_model(self._bank_id, mm_id, request_context=ctx)
                         )
                 else:
-                    # Existing briefing: update trigger if it differs
+                    # Existing briefing: update trigger if it differs. Stored triggers
+                    # are merged supersets (update_mental_model patches), so compare
+                    # only the keys codespy sends.
                     current_trigger = existing.get("trigger") or {}
-                    needs_update = (
-                        current_trigger.get("refresh_after_consolidation") != self._mental_models
-                        or current_trigger.get("exclude_mental_models") is not True
+                    needs_update = any(
+                        current_trigger.get(k) != v for k, v in desired_trigger.items()
                     )
                     if needs_update:
                         self._run_async(
@@ -935,11 +1024,103 @@ class Cerebral:
                             "on" if current_trigger.get("refresh_after_consolidation") else "off",
                             "on" if self._mental_models else "off",
                         )
+                    # Name / source query drift (e.g. the repo-root briefing moved to
+                    # its repo-wide question). A changed source query makes Hindsight's
+                    # next delta refresh fall back to a full rewrite.
+                    desired_name = self._mental_model_name(tags)
+                    desired_query = self._mental_model_source_query(tags)
+                    if (
+                        existing.get("name") != desired_name
+                        or existing.get("source_query") != desired_query
+                    ):
+                        self._run_async(
+                            self._engine.update_mental_model(
+                                self._bank_id,
+                                mm_id,
+                                name=desired_name,
+                                source_query=desired_query,
+                                request_context=ctx,
+                            )
+                        )
+                        logger.info(
+                            "cerebral: briefing %s renamed/re-queried as %r (next refresh is full)",
+                            mm_id,
+                            desired_name,
+                        )
 
                 self._ensured_mental_models.add(mm_id)
             except Exception:
                 logger.warning("cerebral: failed to sync briefing trigger for %s", mm_id, exc_info=True)
 
+    def _desired_trigger(self) -> dict[str, Any]:
+        """Briefing trigger for the current settings (delta mode)."""
+        return {
+            **_BRIEFING_TRIGGER_STATIC,
+            "refresh_after_consolidation": self._mental_models,
+            "min_refresh_interval_seconds": self._min_mental_model_refresh_seconds,
+        }
+
+    def _enforce_briefing_size(self, scopes: Sequence[Sequence[str]]) -> None:
+        """Force a full refresh of briefings grown past the size limit. Never raises.
+
+        Delta refreshes only add content, so a briefing drifts past
+        ``max_mental_model_tokens``. Above ``BRIEFING_FULL_REFRESH_FACTOR`` times
+        that budget, the briefing is rewritten from scratch once: the trigger is
+        switched to ``mode=full``, one explicit refresh runs inline (sync task
+        backend), then the delta trigger is restored. Never deletes anything.
+        """
+        if not self._mental_models or not scopes:
+            return
+        limit = int(self._max_mental_model_tokens * BRIEFING_FULL_REFRESH_FACTOR)
+        for tags in scopes:
+            mm_id = mental_model_id(tags)
+            try:
+                ctx = RequestContext()
+                mm = self._run_async(
+                    self._engine.get_mental_model(self._bank_id, mm_id, request_context=ctx)
+                )
+                if not mm:
+                    continue
+                before = _estimate_tokens((mm.get("content") or "").strip())
+                if before <= limit:
+                    continue
+                desired = self._desired_trigger()
+                self._run_async(
+                    self._engine.update_mental_model(
+                        self._bank_id,
+                        mm_id,
+                        trigger={**desired, "mode": "full"},
+                        request_context=ctx,
+                    )
+                )
+                try:
+                    self._run_async(
+                        self._engine.submit_async_refresh_mental_model(
+                            self._bank_id, mm_id, request_context=ctx
+                        )
+                    )
+                finally:
+                    self._run_async(
+                        self._engine.update_mental_model(
+                            self._bank_id, mm_id, trigger=desired, request_context=ctx
+                        )
+                    )
+                after_mm = self._run_async(
+                    self._engine.get_mental_model(self._bank_id, mm_id, request_context=ctx)
+                )
+                after = _estimate_tokens(((after_mm or {}).get("content") or "").strip())
+                logger.info(
+                    "cerebral: briefing %s (%s) over size (%d > %d tokens); "
+                    "full refresh -> %d tokens",
+                    mm_id,
+                    self._mental_model_name(tags),
+                    before,
+                    limit,
+                    after,
+                )
+            except Exception:
+                logger.warning("cerebral: briefing size guard failed for %s", mm_id, exc_info=True)
+
     def consolidate_run(self, run_id: str) -> None:
         """Trigger one consolidation for all scopes touched during a run.
 
@@ -986,6 +1167,8 @@ class Cerebral:
                         observation_scopes=scopes,
                     )
                 )
+                # Rewrite briefings that delta refreshes grew past their budget
+                self._enforce_briefing_size(scopes)
 
             delta = {b: _calls(b) - baseline[b] for b in buckets}
             logger.info(
@@ -1134,10 +1317,10 @@ class Cerebral:
                     summary.rewrite = True
 
         # Count iterations from agent_<n> scopes (excluding _err variants)
-        # +1 if there's any final scope (map, reduce, or rewrite)
+        # +1 if there's any final scope (map, reduce, rewrite, or Hindsight 1.0's closing_done)
         agent_scopes = {s for s in scope_names if s.startswith("agent_") and not s.endswith("_err")}
         summary.iterations = len(agent_scopes)
-        if any(s.startswith("final") for s in scope_names):
+        if any(s.startswith("final") or s == "closing_done" for s in scope_names):
             summary.iterations += 1
 
         # Tools from tool_trace (list of ToolCallTrace with output dict)
@@ -1218,6 +1401,10 @@ class Cerebral:
             if topic.type == "project_scope":
                 tags.append(f"{topic.type}:{topic.id}")
         if repo_full_name:
+            # No scope topic: tag with the repo-root scope, matching the
+            # _observation_scopes fallback (recall reads project_scope:, not repo:).
+            if not tags:
+                tags.append(f"{TAG_PROJECT_SCOPE}{root_scope_id(repo_full_name)}")
             tags.extend(repo_tags(repo_full_name))
         tags.append(f"task:{episode.task}")
         return tags

{codespy_ai-2.0.1 → codespy_ai-2.1.0}/src/codespy/agents/memory/cerebral/cost.py

@@ -117,6 +117,7 @@ class CerebralCostRecorder:
         scope: str = "",
         input_tokens: int = 0,
         output_tokens: int = 0,
+        thoughts_tokens: int | None = 0,
         error: Exception | None = None,
         duration: float = 0.0,
         **_: Any,
@@ -127,7 +128,10 @@ class CerebralCostRecorder:
             model: Full litellm model string (e.g., "bedrock/converse/moonshotai.kimi-k2.5")
             scope: Hindsight scope (e.g., "retain_extract_facts", "consolidation")
             input_tokens: Input/prompt token count
-            output_tokens: Output/completion token count
+            output_tokens: Visible output/completion token count
+            thoughts_tokens: Reasoning tokens. Hindsight >=0.10.2 reports them apart
+                from ``output_tokens``; they are billed as output, so they are
+                folded into the output count used for pricing and tracking.
             error: Exception if the call failed
             duration: Duration of the call in seconds
             **_: Ignored extra kwargs for forward compatibility
@@ -137,21 +141,23 @@ class CerebralCostRecorder:
             and errored calls that reached the provider (with billed usage).
         """
         try:
+            billed_output = output_tokens + (thoughts_tokens or 0)
+
             # Skip calls with no tokens (includes failed calls that never reached provider)
-            if input_tokens == 0 and output_tokens == 0:
+            if input_tokens == 0 and billed_output == 0:
                 return
 
             # Price the call using litellm
-            prompt_cost, completion_cost = self._price_call_split(model, input_tokens, output_tokens)
+            prompt_cost, completion_cost = self._price_call_split(model, input_tokens, billed_output)
             cost = prompt_cost + completion_cost
-            tokens = input_tokens + output_tokens
+            tokens = input_tokens + billed_output
 
             # Determine bucket: an active recall wins over the scope/task tag,
             # because Hindsight scopes cannot tell a reflect apart
             # from a mental-model refresh.
             usage = current_recall_usage.get()
             if usage is not None:
-                usage.add_llm(model, input_tokens, output_tokens, prompt_cost, completion_cost)
+                usage.add_llm(model, input_tokens, billed_output, prompt_cost, completion_cost)
                 bucket = BUCKET_MEMORY_RECALL
             else:
                 bucket = _llm_bucket(scope)
@@ -166,7 +172,7 @@ class CerebralCostRecorder:
                 tokens=tokens,
                 calls=1,
                 input_tokens=input_tokens,
-                output_tokens=output_tokens,
+                output_tokens=billed_output,
                 input_cost=prompt_cost,
                 output_cost=completion_cost,
                 duration=duration,