shellbrain 0.1.24__tar.gz → 0.1.26__tar.gz

{shellbrain-0.1.24 → shellbrain-0.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.24
+Version: 0.1.26
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

shellbrain-0.1.26/app/core/contracts/concepts.py

@@ -0,0 +1,212 @@
+"""Strict request contracts for the concept-context graph endpoint."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import Field, model_validator
+
+from app.core.contracts.requests import StrictBaseModel
+
+
+ConceptKindValue = Literal["domain", "capability", "process", "entity", "rule", "component"]
+ConceptStatusValue = Literal["active", "deprecated", "archived"]
+ConceptRelationPredicateValue = Literal["contains", "involves", "precedes", "constrains", "depends_on"]
+ConceptClaimTypeValue = Literal["definition", "behavior", "invariant", "failure_mode", "usage_note", "open_question"]
+AnchorKindValue = Literal[
+    "file",
+    "symbol",
+    "line_range",
+    "api_route",
+    "db_table",
+    "schema",
+    "config_key",
+    "test",
+    "metric",
+    "log",
+    "doc",
+    "commit",
+    "memory",
+]
+ConceptGroundingRoleValue = Literal[
+    "implementation",
+    "entrypoint",
+    "storage",
+    "configuration",
+    "test",
+    "observability",
+    "documentation",
+]
+ConceptMemoryLinkRoleValue = Literal[
+    "example_of",
+    "solution_for",
+    "failed_tactic_for",
+    "changed",
+    "validated",
+    "contradicted",
+    "warned_about",
+]
+ConceptEvidenceKindValue = Literal["anchor", "memory", "commit", "transcript", "test", "manual"]
+ConceptSourceKindValue = Literal[
+    "commit",
+    "file_hash",
+    "symbol_hash",
+    "memory",
+    "transcript_event",
+    "manual",
+    "doc",
+    "runtime_trace",
+]
+ConceptCreatedByValue = Literal["worker", "librarian", "manual", "import"]
+ConceptShowIncludeValue = Literal["claims", "relations", "groundings", "memory_links", "preview_concept"]
+
+
+class ConceptEvidencePayload(StrictBaseModel):
+    """Evidence supplied inline with one truth-bearing concept action."""
+
+    kind: ConceptEvidenceKindValue
+    anchor_id: str | None = None
+    memory_id: str | None = None
+    commit_ref: str | None = None
+    transcript_ref: str | None = None
+    note: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_required_reference(self) -> "ConceptEvidencePayload":
+        """Require the reference field implied by the evidence kind."""
+
+        if self.kind == "anchor" and not self.anchor_id:
+            raise ValueError("anchor evidence requires anchor_id")
+        if self.kind == "memory" and not self.memory_id:
+            raise ValueError("memory evidence requires memory_id")
+        if self.kind == "commit" and not self.commit_ref:
+            raise ValueError("commit evidence requires commit_ref")
+        if self.kind == "transcript" and not self.transcript_ref:
+            raise ValueError("transcript evidence requires transcript_ref")
+        if self.kind in {"manual", "test"} and not self.note:
+            raise ValueError(f"{self.kind} evidence requires note")
+        return self
+
+
+class ConceptLifecycleActionFields(StrictBaseModel):
+    """Shared optional lifecycle fields on concept write actions."""
+
+    confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+    observed_at: datetime | None = None
+    validated_at: datetime | None = None
+    source_kind: ConceptSourceKindValue | None = None
+    source_ref: str | None = None
+    created_by: ConceptCreatedByValue = "manual"
+
+
+class UpsertConceptAction(StrictBaseModel):
+    """Create or update a concept container and aliases."""
+
+    type: Literal["upsert_concept"]
+    slug: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    kind: ConceptKindValue
+    status: ConceptStatusValue = "active"
+    scope_note: str | None = None
+    aliases: list[str] = Field(default_factory=list)
+
+
+class AddRelationAction(ConceptLifecycleActionFields):
+    """Create an evidence-backed concept relation."""
+
+    type: Literal["add_relation"]
+    subject: str = Field(min_length=1)
+    predicate: ConceptRelationPredicateValue
+    object: str = Field(min_length=1)
+    evidence: list[ConceptEvidencePayload] = Field(min_length=1)
+
+
+class AddClaimAction(ConceptLifecycleActionFields):
+    """Create an evidence-backed concept claim."""
+
+    type: Literal["add_claim"]
+    concept: str = Field(min_length=1)
+    claim_type: ConceptClaimTypeValue
+    text: str = Field(min_length=1)
+    evidence: list[ConceptEvidencePayload] = Field(min_length=1)
+
+
+class UpsertAnchorAction(StrictBaseModel):
+    """Create or fetch a real-world anchor by canonical locator."""
+
+    type: Literal["upsert_anchor"]
+    kind: AnchorKindValue
+    locator: dict[str, Any] = Field(default_factory=dict)
+
+
+class AnchorSelector(StrictBaseModel):
+    """Reference an existing anchor or define an inline anchor to upsert."""
+
+    id: str | None = None
+    kind: AnchorKindValue | None = None
+    locator: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def _validate_selector(self) -> "AnchorSelector":
+        """Require either an id or a complete inline anchor."""
+
+        has_inline = self.kind is not None and self.locator is not None
+        if not self.id and not has_inline:
+            raise ValueError("anchor requires id or kind+locator")
+        if self.id and (self.kind is not None or self.locator is not None):
+            raise ValueError("anchor selector cannot mix id with kind/locator")
+        return self
+
+
+class AddGroundingAction(ConceptLifecycleActionFields):
+    """Create an evidence-backed concept grounding."""
+
+    type: Literal["add_grounding"]
+    concept: str = Field(min_length=1)
+    role: ConceptGroundingRoleValue
+    anchor: AnchorSelector
+    evidence: list[ConceptEvidencePayload] = Field(min_length=1)
+
+
+class LinkMemoryAction(ConceptLifecycleActionFields):
+    """Create an evidence-backed concept-memory link."""
+
+    type: Literal["link_memory"]
+    concept: str = Field(min_length=1)
+    role: ConceptMemoryLinkRoleValue
+    memory_id: str = Field(min_length=1)
+    evidence: list[ConceptEvidencePayload] = Field(min_length=1)
+
+
+ConceptAction = Annotated[
+    UpsertConceptAction | AddRelationAction | AddClaimAction | UpsertAnchorAction | AddGroundingAction | LinkMemoryAction,
+    Field(discriminator="type"),
+]
+
+
+class ConceptCommandRequest(StrictBaseModel):
+    """Canonical concept endpoint request."""
+
+    schema_version: Literal["concept.v1"]
+    mode: Literal["apply", "show"]
+    repo_id: str
+    actions: list[ConceptAction] | None = None
+    concept: str | None = None
+    include: list[ConceptShowIncludeValue] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_mode_fields(self) -> "ConceptCommandRequest":
+        """Enforce mode-specific request fields."""
+
+        if self.mode == "apply":
+            if not self.actions:
+                raise ValueError("mode=apply requires actions")
+            if self.concept is not None:
+                raise ValueError("mode=apply does not accept concept")
+        if self.mode == "show":
+            if not self.concept:
+                raise ValueError("mode=show requires concept")
+            if self.actions is not None:
+                raise ValueError("mode=show does not accept actions")
+        return self

{shellbrain-0.1.24 → shellbrain-0.1.26}/app/core/contracts/requests.py

@@ -2,11 +2,12 @@
 
 from typing import Annotated, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 MemoryKindValue = Literal["problem", "solution", "failed_tactic", "fact", "preference", "change", "frontier"]
 AssociationRelationValue = Literal["depends_on", "associated_with", "matures_into"]
+ConceptReadFacetValue = Literal["claims", "relations", "groundings", "memory_links", "evidence"]
 
 
 class StrictBaseModel(BaseModel):
@@ -15,6 +16,43 @@ class StrictBaseModel(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
 
+class ReadConceptsExpandRequest(StrictBaseModel):
+    """This model defines concept-context read expansion controls."""
+
+    mode: Literal["auto", "none", "explicit"] = "auto"
+    refs: list[str] = Field(default_factory=list, max_length=5)
+    facets: list[ConceptReadFacetValue] = Field(default_factory=list, max_length=5)
+    max_auto: int = Field(default=2, ge=1, le=5)
+
+    @field_validator("refs")
+    @classmethod
+    def _validate_refs_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique concept refs."""
+
+        if any(not ref.strip() for ref in value):
+            raise ValueError("concept refs must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("concept refs must be unique")
+        return value
+
+    @field_validator("facets")
+    @classmethod
+    def _validate_facets_unique(cls, value: list[ConceptReadFacetValue]) -> list[ConceptReadFacetValue]:
+        """This validator enforces unique concept facets."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("concept facets must be unique")
+        return value
+
+    @model_validator(mode="after")
+    def _validate_explicit_refs(self) -> "ReadConceptsExpandRequest":
+        """Require explicit concept refs when explicit mode is requested."""
+
+        if self.mode == "explicit" and not self.refs:
+            raise ValueError("expand.concepts.mode=explicit requires refs")
+        return self
+
+
 class ReadExpandRequest(StrictBaseModel):
     """This model defines expansion knobs for read requests."""
 
@@ -24,6 +62,7 @@ class ReadExpandRequest(StrictBaseModel):
     include_association_links: bool | None = None
     max_association_depth: int | None = Field(default=None, ge=1, le=4)
     min_association_strength: float | None = Field(default=None, ge=0.0, le=1.0)
+    concepts: ReadConceptsExpandRequest = Field(default_factory=ReadConceptsExpandRequest)
 
 
 class MemoryReadRequest(StrictBaseModel):

shellbrain-0.1.26/app/core/entities/concepts.py

@@ -0,0 +1,302 @@
+"""Core entities and enums for the typed concept-context graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class ConceptKind(str, Enum):
+    """Allowed high-level concept kinds."""
+
+    DOMAIN = "domain"
+    CAPABILITY = "capability"
+    PROCESS = "process"
+    ENTITY = "entity"
+    RULE = "rule"
+    COMPONENT = "component"
+
+
+class ConceptStatus(str, Enum):
+    """Lifecycle state for concept containers."""
+
+    ACTIVE = "active"
+    DEPRECATED = "deprecated"
+    ARCHIVED = "archived"
+
+
+class ConceptLifecycleStatus(str, Enum):
+    """Lifecycle state for truth-bearing concept records."""
+
+    ACTIVE = "active"
+    MAYBE_STALE = "maybe_stale"
+    STALE = "stale"
+    SUPERSEDED = "superseded"
+    WRONG = "wrong"
+
+
+class ConceptRelationPredicate(str, Enum):
+    """Allowed concept-to-concept predicates."""
+
+    CONTAINS = "contains"
+    INVOLVES = "involves"
+    PRECEDES = "precedes"
+    CONSTRAINS = "constrains"
+    DEPENDS_ON = "depends_on"
+
+
+class ConceptClaimType(str, Enum):
+    """Allowed concept claim types."""
+
+    DEFINITION = "definition"
+    BEHAVIOR = "behavior"
+    INVARIANT = "invariant"
+    FAILURE_MODE = "failure_mode"
+    USAGE_NOTE = "usage_note"
+    OPEN_QUESTION = "open_question"
+
+
+class AnchorKind(str, Enum):
+    """Allowed real-world locator kinds."""
+
+    FILE = "file"
+    SYMBOL = "symbol"
+    LINE_RANGE = "line_range"
+    API_ROUTE = "api_route"
+    DB_TABLE = "db_table"
+    SCHEMA = "schema"
+    CONFIG_KEY = "config_key"
+    TEST = "test"
+    METRIC = "metric"
+    LOG = "log"
+    DOC = "doc"
+    COMMIT = "commit"
+    MEMORY = "memory"
+
+
+class AnchorStatus(str, Enum):
+    """Lifecycle state for real-world locators."""
+
+    ACTIVE = "active"
+    MAYBE_STALE = "maybe_stale"
+    STALE = "stale"
+    DEPRECATED = "deprecated"
+
+
+class ConceptGroundingRole(str, Enum):
+    """Allowed concept-to-anchor grounding roles."""
+
+    IMPLEMENTATION = "implementation"
+    ENTRYPOINT = "entrypoint"
+    STORAGE = "storage"
+    CONFIGURATION = "configuration"
+    TEST = "test"
+    OBSERVABILITY = "observability"
+    DOCUMENTATION = "documentation"
+
+
+class ConceptMemoryLinkRole(str, Enum):
+    """Allowed concept-to-memory link roles."""
+
+    EXAMPLE_OF = "example_of"
+    SOLUTION_FOR = "solution_for"
+    FAILED_TACTIC_FOR = "failed_tactic_for"
+    CHANGED = "changed"
+    VALIDATED = "validated"
+    CONTRADICTED = "contradicted"
+    WARNED_ABOUT = "warned_about"
+
+
+class ConceptEvidenceTargetType(str, Enum):
+    """Truth-bearing concept record types that evidence may target."""
+
+    RELATION = "relation"
+    CLAIM = "claim"
+    GROUNDING = "grounding"
+    MEMORY_LINK = "memory_link"
+
+
+class ConceptEvidenceKind(str, Enum):
+    """Allowed evidence source kinds for concept records."""
+
+    ANCHOR = "anchor"
+    MEMORY = "memory"
+    COMMIT = "commit"
+    TRANSCRIPT = "transcript"
+    TEST = "test"
+    MANUAL = "manual"
+
+
+class ConceptSourceKind(str, Enum):
+    """Allowed source refs on concept lifecycle records."""
+
+    COMMIT = "commit"
+    FILE_HASH = "file_hash"
+    SYMBOL_HASH = "symbol_hash"
+    MEMORY = "memory"
+    TRANSCRIPT_EVENT = "transcript_event"
+    MANUAL = "manual"
+    DOC = "doc"
+    RUNTIME_TRACE = "runtime_trace"
+
+
+class ConceptCreatedBy(str, Enum):
+    """Allowed authorship channels for concept records."""
+
+    WORKER = "worker"
+    LIBRARIAN = "librarian"
+    MANUAL = "manual"
+    IMPORT = "import"
+
+
+class GraphPatchStatus(str, Enum):
+    """Allowed graph patch lifecycle states."""
+
+    PENDING = "pending"
+    APPLIED = "applied"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Concept:
+    """One durable concept container."""
+
+    id: str
+    repo_id: str
+    slug: str
+    name: str
+    kind: ConceptKind
+    status: ConceptStatus = ConceptStatus.ACTIVE
+    scope_note: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptAlias:
+    """One alternate label for a concept."""
+
+    concept_id: str
+    repo_id: str
+    alias: str
+    normalized_alias: str
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptLifecycle:
+    """Shared lifecycle fields for truth-bearing concept records."""
+
+    status: ConceptLifecycleStatus = ConceptLifecycleStatus.ACTIVE
+    confidence: float = 0.5
+    observed_at: datetime | None = None
+    validated_at: datetime | None = None
+    source_kind: ConceptSourceKind | None = None
+    source_ref: str | None = None
+    superseded_by_id: str | None = None
+    created_by: ConceptCreatedBy = ConceptCreatedBy.MANUAL
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptRelation:
+    """One typed concept-to-concept relation."""
+
+    id: str
+    repo_id: str
+    subject_concept_id: str
+    predicate: ConceptRelationPredicate
+    object_concept_id: str
+    lifecycle: ConceptLifecycle = field(default_factory=ConceptLifecycle)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptClaim:
+    """One typed statement Shellbrain believes about a concept."""
+
+    id: str
+    repo_id: str
+    concept_id: str
+    claim_type: ConceptClaimType
+    text: str
+    normalized_text: str
+    lifecycle: ConceptLifecycle = field(default_factory=ConceptLifecycle)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class Anchor:
+    """One real-world locator that grounds a concept."""
+
+    id: str
+    repo_id: str
+    kind: AnchorKind
+    locator_json: dict[str, Any]
+    canonical_locator_hash: str
+    status: AnchorStatus = AnchorStatus.ACTIVE
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptGrounding:
+    """One typed link from concept space to a real-world anchor."""
+
+    id: str
+    repo_id: str
+    concept_id: str
+    role: ConceptGroundingRole
+    anchor_id: str
+    lifecycle: ConceptLifecycle = field(default_factory=ConceptLifecycle)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptMemoryLink:
+    """One typed link from an existing Shellbrain memory to a concept."""
+
+    id: str
+    repo_id: str
+    concept_id: str
+    role: ConceptMemoryLinkRole
+    memory_id: str
+    lifecycle: ConceptLifecycle = field(default_factory=ConceptLifecycle)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptEvidence:
+    """One evidence pointer attached to a truth-bearing concept record."""
+
+    id: str
+    repo_id: str
+    target_type: ConceptEvidenceTargetType
+    target_id: str
+    evidence_kind: ConceptEvidenceKind
+    anchor_id: str | None = None
+    memory_id: str | None = None
+    commit_ref: str | None = None
+    transcript_ref: str | None = None
+    note: str | None = None
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class GraphPatch:
+    """Minimal reserved future graph-patch proposal record."""
+
+    id: str
+    repo_id: str
+    schema_version: str
+    status: GraphPatchStatus
+    proposed_by: ConceptCreatedBy
+    operations_json: list[dict[str, Any]]
+    evidence_summary: str | None = None
+    created_at: datetime | None = None
+    applied_at: datetime | None = None

{shellbrain-0.1.24 → shellbrain-0.1.26}/app/core/entities/telemetry.py

@@ -72,6 +72,10 @@ class ReadSummaryRecord:
     direct_token_estimate: int | None
     explicit_related_token_estimate: int | None
     implicit_related_token_estimate: int | None
+    concept_count: int | None
+    concept_token_estimate: int | None
+    concept_refs_returned: list[str] | None
+    concept_facets_returned: list[str] | None
     created_at: datetime
 
 

{shellbrain-0.1.24 → shellbrain-0.1.26}/app/core/interfaces/repos.py

@@ -5,6 +5,17 @@ from datetime import datetime
 from typing import Any, Sequence
 
 from app.core.entities.associations import AssociationEdge, AssociationObservation
+from app.core.entities.concepts import (
+    Anchor,
+    Concept,
+    ConceptAlias,
+    ConceptClaim,
+    ConceptEvidence,
+    ConceptGrounding,
+    ConceptMemoryLink,
+    ConceptRelation,
+    GraphPatch,
+)
 from app.core.entities.evidence import EvidenceRef
 from app.core.entities.episodes import Episode, EpisodeEvent, SessionTransfer
 from app.core.entities.facts import FactUpdate, ProblemAttempt
@@ -79,6 +90,70 @@ class IUtilityRepo(ABC):
         """This method appends a utility observation entry."""
 
 
+class IConceptsRepo(ABC):
+    """This interface defines persistence operations for the concept-context graph."""
+
+    @abstractmethod
+    def upsert_concept(self, concept: Concept, aliases: Sequence[str]) -> Concept:
+        """This method inserts or updates a concept and its aliases."""
+
+    @abstractmethod
+    def get_concept_by_ref(self, *, repo_id: str, concept_ref: str) -> Concept | None:
+        """This method resolves a concept by id or slug."""
+
+    @abstractmethod
+    def list_concepts_by_ids(self, *, repo_id: str, concept_ids: Sequence[str]) -> Sequence[Concept]:
+        """This method returns concepts for the provided ids."""
+
+    @abstractmethod
+    def list_contains_edges(self, *, repo_id: str) -> Sequence[ConceptRelation]:
+        """This method returns active contains edges for cycle validation."""
+
+    @abstractmethod
+    def add_relation(self, relation: ConceptRelation) -> ConceptRelation:
+        """This method inserts or returns an active concept relation."""
+
+    @abstractmethod
+    def add_claim(self, claim: ConceptClaim) -> ConceptClaim:
+        """This method inserts or returns a concept claim."""
+
+    @abstractmethod
+    def upsert_anchor(self, anchor: Anchor) -> Anchor:
+        """This method inserts or returns an anchor by canonical locator."""
+
+    @abstractmethod
+    def get_anchor(self, *, repo_id: str, anchor_id: str) -> Anchor | None:
+        """This method fetches one anchor by id."""
+
+    @abstractmethod
+    def add_grounding(self, grounding: ConceptGrounding) -> ConceptGrounding:
+        """This method inserts or returns an active concept grounding."""
+
+    @abstractmethod
+    def add_memory_link(self, memory_link: ConceptMemoryLink) -> ConceptMemoryLink:
+        """This method inserts or returns an active concept-memory link."""
+
+    @abstractmethod
+    def add_evidence(self, evidence: ConceptEvidence) -> ConceptEvidence:
+        """This method appends one evidence pointer for a concept graph record."""
+
+    @abstractmethod
+    def create_graph_patch(self, patch: GraphPatch) -> GraphPatch:
+        """This method stores one future graph-patch proposal record."""
+
+    @abstractmethod
+    def get_concept_bundle(self, *, repo_id: str, concept_ref: str) -> dict[str, Any] | None:
+        """This method returns one concept plus directly related graph records."""
+
+    @abstractmethod
+    def find_concepts_for_memory_ids(self, *, repo_id: str, memory_ids: Sequence[str]) -> Sequence[dict[str, Any]]:
+        """This method returns concept-link matches for displayed memory ids."""
+
+    @abstractmethod
+    def search_concepts_by_text(self, *, repo_id: str, query: str, limit: int) -> Sequence[dict[str, Any]]:
+        """This method returns deterministic concept matches for query text."""
+
+
 class IEpisodesRepo(ABC):
     """This interface defines persistence operations for episodes and events."""