shellbrain 0.1.23__tar.gz → 0.1.25__tar.gz

{shellbrain-0.1.23 → shellbrain-0.1.25}/PKG-INFO

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

shellbrain-0.1.25/app/boot/migrations.py

@@ -0,0 +1,115 @@
+"""Packaged Alembic bootstrap helpers for installed-shellbrain database migrations."""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+import importlib.metadata
+
+from alembic import command
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from alembic.script.revision import ResolutionError
+
+from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
+from app.boot.db import get_optional_db_dsn
+from app.periphery.admin.destructive_guard import backup_and_verify_before_destructive_action
+from app.periphery.admin.instance_guard import ensure_instance_metadata, fetch_instance_metadata
+from app.periphery.admin.privileges import reconcile_app_role_privileges
+
+
+class DatabaseRevisionAheadOfInstalledPackageError(RuntimeError):
+    """Raised when the target database revision is newer than the installed package knows about."""
+
+
+def upgrade_database(revision: str = "head") -> None:
+    """Apply packaged Alembic migrations to the configured database."""
+
+    config = Config()
+    admin_dsn = get_admin_db_dsn()
+    with as_file(files("app").joinpath("migrations")) as migrations_path:
+        config.set_main_option("script_location", str(migrations_path))
+        script = ScriptDirectory.from_config(config)
+        if _database_has_shellbrain_objects(admin_dsn):
+            _assert_database_revision_is_known(admin_dsn=admin_dsn, script=script)
+            backup_and_verify_before_destructive_action(
+                admin_dsn=admin_dsn,
+                backup_root=get_backup_dir(),
+                mirror_root=get_backup_mirror_dir(),
+            )
+        config.set_main_option("sqlalchemy.url", admin_dsn)
+        command.upgrade(config, revision)
+    if fetch_instance_metadata(admin_dsn) is None:
+        ensure_instance_metadata(
+            admin_dsn,
+            instance_mode=get_instance_mode_default(),
+            created_by="app.admin.migrate",
+            notes="Stamped by packaged migration runner.",
+        )
+    app_dsn = get_optional_db_dsn()
+    if app_dsn:
+        reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn)
+
+
+def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
+    """Return whether the target database already contains Shellbrain-managed tables."""
+
+    import psycopg
+
+    with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT EXISTS (
+                  SELECT 1
+                  FROM information_schema.tables
+                  WHERE table_schema = 'public'
+                    AND table_name IN ('memories', 'episodes', 'episode_events', 'operation_invocations')
+                )
+                """
+            )
+            return bool(cur.fetchone()[0])
+
+
+def _assert_database_revision_is_known(*, admin_dsn: str, script: ScriptDirectory) -> None:
+    """Fail early with a user-facing error when the database revision is newer than this package."""
+
+    current_revision = _fetch_database_revision(admin_dsn)
+    if current_revision is None:
+        return
+    try:
+        script.get_revision(current_revision)
+    except ResolutionError as exc:
+        installed_version = _installed_shellbrain_version()
+        raise DatabaseRevisionAheadOfInstalledPackageError(
+            "Installed Shellbrain package "
+            f"({installed_version}) cannot manage database revision {current_revision}. "
+            "This database was likely migrated by a newer Shellbrain release than the one currently installed. "
+            "Upgrade Shellbrain to a build that includes this revision, then rerun `shellbrain init` or "
+            "`shellbrain admin migrate`."
+        ) from exc
+
+
+def _fetch_database_revision(admin_dsn: str) -> str | None:
+    """Return the current alembic revision when present."""
+
+    import psycopg
+
+    try:
+        with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT version_num FROM alembic_version")
+                row = cur.fetchone()
+    except psycopg.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    return str(row[0])
+
+
+def _installed_shellbrain_version() -> str:
+    """Return the installed Shellbrain package version when available."""
+
+    try:
+        return importlib.metadata.version("shellbrain")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"

shellbrain-0.1.25/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.23 → shellbrain-0.1.25}/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.25/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