shellbrain 0.1.38__tar.gz → 0.1.40__tar.gz

{shellbrain-0.1.38 → shellbrain-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.38
+Version: 0.1.40
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -141,6 +141,6 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 ## Docs
 
-- [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
-- [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries
+- [For Humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
+- [For Agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
+- [Technical Docs](https://deepwiki.com/cucupac/shellbrain) — in-depth generated docs and codebase map

{shellbrain-0.1.38 → shellbrain-0.1.40}/README.md

@@ -127,6 +127,6 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 ## Docs
 
-- [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
-- [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries
+- [For Humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
+- [For Agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
+- [Technical Docs](https://deepwiki.com/cucupac/shellbrain) — in-depth generated docs and codebase map

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/entities/concepts.py

@@ -310,6 +310,7 @@ class ConceptEvidence:
     commit_ref: str | None = None
     transcript_ref: str | None = None
     note: str | None = None
+    evidence_id: str | None = None
     created_at: datetime | None = None
 
 

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/entities/evidence.py

@@ -147,6 +147,27 @@ class EvidenceLinkView:
     created_at: datetime | None = None
 
 
+@dataclass(frozen=True, kw_only=True)
+class EvidenceLinkedTarget:
+    """One target linked to a canonical evidence source."""
+
+    link_id: str
+    target: EvidenceTarget
+    role: EvidenceRole
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class EvidenceDetail:
+    """One canonical evidence source plus all linked targets."""
+
+    id: EvidenceId
+    repo_id: RepoId
+    source: EvidenceSource
+    linked_targets: tuple[EvidenceLinkedTarget, ...]
+    created_at: datetime | None = None
+
+
 @dataclass(kw_only=True)
 class MemoryEvidenceLink:
     """This dataclass models a many-to-many link between shellbrain and evidence."""

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/entities/inner_agents.py

@@ -11,7 +11,7 @@ class _StrictModel(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
 
-InnerAgentName = Literal["build_context", "build_knowledge", "teach"]
+InnerAgentName = Literal["build_context", "build_knowledge", "teach", "wiki_summary"]
 InnerAgentProviderName = str
 InnerAgentReasoningLevel = Literal["none", "minimal", "low", "medium", "high", "xhigh"]
 BuildContextStrategy = Literal[
@@ -66,4 +66,19 @@ class TeachKnowledgeSettings(_StrictModel):
     max_write_commands: int = Field(default=12, ge=1, le=200)
 
 
+class WikiSummarySettings(_StrictModel):
+    """Typed model/runtime settings for generated wiki summaries."""
+
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str = Field(min_length=1)
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int = Field(ge=1, le=1200)
+    prompt_version: str = Field(default="wiki-summary.v1", min_length=1)
+    max_summary_chars: int = Field(default=900, ge=100, le=4000)
+    running_refresh_stale_seconds: int = Field(default=3600, ge=60, le=86_400)
+    startup_batch_limit: int = Field(default=20, ge=0, le=200)
+    periodic_batch_limit: int = Field(default=5, ge=0, le=100)
+    periodic_seconds: int = Field(default=300, ge=30, le=86_400)
+
+
 InnerAgentSettings = BuildContextSettings

shellbrain-0.1.40/app/core/entities/repositories.py

@@ -0,0 +1,17 @@
+"""Repository summaries used by cross-repo read surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RepositorySummary:
+    """Compact read-only summary for one Shellbrain repository."""
+
+    repo_id: str
+    repo_root: str | None
+    concept_count: int
+    memory_count: int
+    evidence_count: int
+    last_seen_at: str | None

shellbrain-0.1.40/app/core/entities/wiki_summaries.py

@@ -0,0 +1,114 @@
+"""Core entities for generated Shellbrain Wiki summaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class WikiSummaryTargetType(str, Enum):
+    """Wiki targets that can have generated article prose."""
+
+    REPO = "repo"
+    CONCEPT = "concept"
+
+
+class WikiSummaryLinkTargetType(str, Enum):
+    """Wiki page targets that generated prose can link to deterministically."""
+
+    CONCEPT = "concept"
+    MEMORY = "memory"
+    ANCHOR = "anchor"
+    EVIDENCE = "evidence"
+
+
+class WikiSummaryGenerationStatus(str, Enum):
+    """Durable generation status for one cached wiki summary."""
+
+    PENDING = "pending"
+    OK = "ok"
+    FAILED = "failed"
+
+
+class WikiSummaryFreshness(str, Enum):
+    """Read-time freshness state for a cached wiki summary."""
+
+    MISSING = "missing"
+    FRESH = "fresh"
+    STALE = "stale"
+    EXPIRED = "expired"
+    PENDING = "pending"
+    FAILED = "failed"
+
+
+class WikiSummarySourceVelocity(str, Enum):
+    """How quickly one summary target's source facts are changing."""
+
+    HIGH = "high"
+    NORMAL = "normal"
+    QUIET = "quiet"
+
+
+@dataclass(frozen=True, kw_only=True)
+class WikiSummaryTarget:
+    """One repository-scoped wiki summary target."""
+
+    repo_id: str
+    target_type: WikiSummaryTargetType
+    target_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class WikiSummaryInputSnapshot:
+    """Deterministic source payload used to generate one summary."""
+
+    target: WikiSummaryTarget
+    input_hash: str
+    source_refs: tuple[str, ...]
+    source_payload: dict[str, Any]
+    source_velocity: WikiSummarySourceVelocity
+    popularity_score: int
+    latest_source_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class WikiSummaryRecord:
+    """Cached generated prose for one wiki target."""
+
+    target: WikiSummaryTarget
+    body: str | None
+    input_hash: str | None
+    source_refs: tuple[str, ...]
+    generation_status: WikiSummaryGenerationStatus
+    generated_at: datetime | None
+    model: str | None
+    prompt_version: str | None
+    last_error_code: str | None
+    last_error_message: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass(frozen=True, kw_only=True)
+class WikiSummaryLinkTarget:
+    """One deterministic wiki page target that may be linked from summary prose."""
+
+    target_type: WikiSummaryLinkTargetType
+    target_id: str
+    label: str
+    slug: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class WikiSummaryView:
+    """Summary state attached to a rendered wiki page model."""
+
+    target: WikiSummaryTarget
+    freshness: WikiSummaryFreshness
+    body: str | None
+    generated_at: datetime | None
+    stale_reason: str | None
+    generation_status: WikiSummaryGenerationStatus | None
+    link_targets: tuple[WikiSummaryLinkTarget, ...] = ()

shellbrain-0.1.40/app/core/policies/wiki_summary_freshness.py

@@ -0,0 +1,60 @@
+"""Pure freshness policy for generated wiki summaries."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from app.core.entities.wiki_summaries import (
+    WikiSummaryFreshness,
+    WikiSummaryGenerationStatus,
+    WikiSummaryInputSnapshot,
+    WikiSummaryRecord,
+    WikiSummarySourceVelocity,
+)
+
+
+_EXPIRATION_BY_VELOCITY = {
+    WikiSummarySourceVelocity.HIGH: timedelta(days=3),
+    WikiSummarySourceVelocity.NORMAL: timedelta(days=14),
+    WikiSummarySourceVelocity.QUIET: timedelta(days=60),
+}
+
+
+def determine_wiki_summary_freshness(
+    *,
+    record: WikiSummaryRecord | None,
+    snapshot: WikiSummaryInputSnapshot,
+    now: datetime,
+) -> tuple[WikiSummaryFreshness, str | None]:
+    """Return freshness and a compact reason for one cached summary."""
+
+    if record is None:
+        return WikiSummaryFreshness.MISSING, "summary has not been generated"
+    if record.generation_status == WikiSummaryGenerationStatus.PENDING:
+        return WikiSummaryFreshness.PENDING, "summary generation is running"
+    if record.generation_status == WikiSummaryGenerationStatus.FAILED:
+        reason = record.last_error_code or "generation failed"
+        return WikiSummaryFreshness.FAILED, reason
+    if record.input_hash != snapshot.input_hash:
+        return WikiSummaryFreshness.STALE, "source facts changed"
+    if record.generated_at is None:
+        return WikiSummaryFreshness.STALE, "summary has no generated timestamp"
+
+    ttl = _EXPIRATION_BY_VELOCITY[snapshot.source_velocity]
+    if now - record.generated_at > ttl:
+        return WikiSummaryFreshness.EXPIRED, (
+            f"{snapshot.source_velocity.value} velocity summary exceeded "
+            f"{ttl.days} day freshness window"
+        )
+    return WikiSummaryFreshness.FRESH, None
+
+
+def needs_wiki_summary_refresh(freshness: WikiSummaryFreshness) -> bool:
+    """Return whether this freshness state should enqueue background refresh."""
+
+    return freshness in {
+        WikiSummaryFreshness.MISSING,
+        WikiSummaryFreshness.STALE,
+        WikiSummaryFreshness.EXPIRED,
+        WikiSummaryFreshness.FAILED,
+    }

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/ports/db/concept_repositories.py

@@ -37,6 +37,12 @@ class IConceptsRepo(ABC):
     ) -> Sequence[Concept]:
         """This method returns concepts for the provided ids."""
 
+    @abstractmethod
+    def list_concepts(
+        self, *, repo_id: str, statuses: Sequence[str]
+    ) -> Sequence[Concept]:
+        """This method returns concepts for one repo and status set."""
+
     @abstractmethod
     def list_contains_edges(self, *, repo_id: str) -> Sequence[ConceptRelation]:
         """This method returns active contains edges for cycle validation."""
@@ -104,6 +110,12 @@ class IConceptsRepo(ABC):
     ) -> Sequence[dict[str, Any]]:
         """This method returns concept-link matches for displayed memory ids."""
 
+    @abstractmethod
+    def find_concepts_for_anchor_ids(
+        self, *, repo_id: str, anchor_ids: Sequence[str]
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns concept-grounding matches for displayed anchors."""
+
     @abstractmethod
     def upsert_embedding(
         self,

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/ports/db/memory_repositories.py

@@ -5,6 +5,7 @@ from typing import Sequence
 
 from app.core.entities.associations import AssociationEdge, AssociationObservation
 from app.core.entities.evidence import (
+    EvidenceDetail,
     EvidenceLinkView,
     EvidenceRole,
     EvidenceSource,
@@ -30,6 +31,12 @@ class IMemoriesRepo(ABC):
     def list_by_ids(self, ids: Sequence[str]) -> Sequence[Memory]:
         """This method fetches memories in the input identifier order."""
 
+    @abstractmethod
+    def list_recent(
+        self, *, repo_id: str, statuses: Sequence[str], limit: int
+    ) -> Sequence[Memory]:
+        """Fetch recent memories for one repository in newest-first order."""
+
     @abstractmethod
     def update_lifecycle(self, memory: Memory) -> bool:
         """Update lifecycle fields for one concrete memory."""
@@ -96,3 +103,9 @@ class IEvidenceRepo(ABC):
         self, *, repo_id: str, targets: Sequence[EvidenceTarget]
     ) -> Sequence[EvidenceLinkView]:
         """Resolve evidence links for targets through the unified evidence API."""
+
+    @abstractmethod
+    def get_evidence_detail(
+        self, *, repo_id: str, evidence_id: str
+    ) -> EvidenceDetail | None:
+        """Resolve one canonical evidence source plus linked targets."""

shellbrain-0.1.40/app/core/ports/db/repository_index.py

@@ -0,0 +1,16 @@
+"""Repository index read ports."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+from app.core.entities.repositories import RepositorySummary
+
+
+class IRepositoryIndexRepo(ABC):
+    """Read-only access to repositories known to Shellbrain."""
+
+    @abstractmethod
+    def list_repositories(self) -> Sequence[RepositorySummary]:
+        """Return repositories that have Shellbrain knowledge or telemetry rows."""

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/ports/db/unit_of_work.py

@@ -15,7 +15,9 @@ from app.core.ports.db.memory_repositories import (
     IUtilityRepo,
 )
 from app.core.ports.db.problem_runs import IProblemRunsRepo
+from app.core.ports.db.repository_index import IRepositoryIndexRepo
 from app.core.ports.db.snapshots import ISnapshotsRepo
+from app.core.ports.db.wiki_summaries import IWikiSummaryRepo
 from app.core.ports.embeddings.retrieval import IVectorSearch
 from app.core.ports.db.retrieval_repositories import (
     IConceptKeywordRetrievalRepo,
@@ -44,7 +46,9 @@ class IUnitOfWork(ABC):
     guidance: IPendingUtilityCandidatesRepo
     knowledge_build_runs: IKnowledgeBuildRunsRepo
     problem_runs: IProblemRunsRepo
+    repository_index: IRepositoryIndexRepo
     snapshots: ISnapshotsRepo
+    wiki_summaries: IWikiSummaryRepo
     vector_search: IVectorSearch | None
 
     @abstractmethod

shellbrain-0.1.40/app/core/ports/db/wiki_summaries.py

@@ -0,0 +1,64 @@
+"""Repository port for generated wiki summary cache records."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Sequence
+
+from app.core.entities.wiki_summaries import (
+    WikiSummaryInputSnapshot,
+    WikiSummaryRecord,
+    WikiSummaryTarget,
+)
+
+
+class IWikiSummaryRepo(ABC):
+    """Read and write cached generated wiki summaries."""
+
+    @abstractmethod
+    def get(self, target: WikiSummaryTarget) -> WikiSummaryRecord | None:
+        """Return the cached summary for one target when present."""
+
+    @abstractmethod
+    def acquire_refresh(
+        self,
+        *,
+        snapshot: WikiSummaryInputSnapshot,
+        model: str,
+        prompt_version: str,
+        now: datetime,
+        stale_running_before: datetime,
+    ) -> bool:
+        """Mark one target pending when no fresh refresh is already running."""
+
+    @abstractmethod
+    def record_success(
+        self,
+        *,
+        snapshot: WikiSummaryInputSnapshot,
+        body: str,
+        model: str,
+        prompt_version: str,
+        now: datetime,
+    ) -> None:
+        """Persist generated summary prose for one target."""
+
+    @abstractmethod
+    def record_failure(
+        self,
+        *,
+        snapshot: WikiSummaryInputSnapshot,
+        model: str,
+        prompt_version: str,
+        error_code: str,
+        error_message: str,
+        now: datetime,
+    ) -> None:
+        """Persist a failed refresh attempt without deleting prior prose."""
+
+    @abstractmethod
+    def list_existing_targets(
+        self, *, repo_ids: Sequence[str]
+    ) -> Sequence[WikiSummaryTarget]:
+        """Return summary targets that already have cache rows for these repos."""

{shellbrain-0.1.38 → shellbrain-0.1.40}/app/core/ports/host_apps/inner_agents.py

@@ -106,6 +106,22 @@ class TeachKnowledgeAgentRequest(_StrictModel):
     max_write_commands: int = Field(ge=1, le=200)
 
 
+class WikiSummaryAgentRequest(_StrictModel):
+    """One provider request to generate a cached wiki summary."""
+
+    agent_name: InnerAgentName = "wiki_summary"
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str = Field(min_length=1)
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int = Field(ge=1, le=1200)
+    prompt_version: str = Field(min_length=1)
+    target_type: str = Field(min_length=1)
+    repo_id: str = Field(min_length=1)
+    target_id: str = Field(min_length=1)
+    source_payload: dict[str, Any]
+    max_summary_chars: int = Field(ge=100, le=4000)
+
+
 class BuildKnowledgeAgentResult(_StrictModel):
     """Provider-neutral result from one build_knowledge run."""
 
@@ -131,6 +147,27 @@ class BuildKnowledgeAgentResult(_StrictModel):
     code_trace: dict[str, Any] = Field(default_factory=dict)
 
 
+class WikiSummaryAgentResult(_StrictModel):
+    """Provider-neutral result from one generated wiki summary run."""
+
+    status: InnerAgentRunStatus
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int | None = Field(default=None, ge=1, le=1200)
+    duration_ms: int = Field(default=0, ge=0)
+    input_tokens: int | None = Field(default=None, ge=0)
+    output_tokens: int | None = Field(default=None, ge=0)
+    reasoning_output_tokens: int | None = Field(default=None, ge=0)
+    cached_input_tokens_total: int | None = Field(default=None, ge=0)
+    cache_read_input_tokens: int | None = Field(default=None, ge=0)
+    cache_creation_input_tokens: int | None = Field(default=None, ge=0)
+    capture_quality: TokenCaptureQuality | None = None
+    body: str | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+
+
 class IInnerAgentRunner(Protocol):
     """Behavior protocol for bounded inner-agent synthesis providers."""
 
@@ -154,3 +191,12 @@ class ITeachKnowledgeAgentRunner(Protocol):
         self, request: TeachKnowledgeAgentRequest
     ) -> BuildKnowledgeAgentResult:
         """Run one teach request and return a provider-neutral result."""
+
+
+class IWikiSummaryAgentRunner(Protocol):
+    """Behavior protocol for generated wiki summary providers."""
+
+    def run_wiki_summary(
+        self, request: WikiSummaryAgentRequest
+    ) -> WikiSummaryAgentResult:
+        """Run one wiki summary request and return provider-neutral prose."""

shellbrain-0.1.40/app/core/use_cases/wiki/__init__.py

@@ -0,0 +1,27 @@
+"""Shellbrain Wiki read-only workflows."""
+
+from app.core.use_cases.wiki.execute import (
+    wiki_anchor_page,
+    wiki_concept_facet,
+    wiki_concept_page,
+    wiki_evidence_page,
+    wiki_home,
+    wiki_index,
+    wiki_memory_neighbors,
+    wiki_memory_page,
+    wiki_memory_sources,
+    wiki_search,
+)
+
+__all__ = [
+    "wiki_anchor_page",
+    "wiki_concept_facet",
+    "wiki_concept_page",
+    "wiki_evidence_page",
+    "wiki_home",
+    "wiki_index",
+    "wiki_memory_neighbors",
+    "wiki_memory_page",
+    "wiki_memory_sources",
+    "wiki_search",
+]