apsimo 1.3.0__py3-none-any.whl

apsimo/world_model/causal_maintenance.py

@@ -0,0 +1,131 @@
+"""Causal-edge maintenance primitives (H2.3): contradiction + staleness.
+
+Two fabrication controls for the causal layer, consumed by the
+BeliefEngine's periodic run:
+
+1. CONTRADICTION: a positive causal claim (WM_CAUSES / WM_ENABLES) and a
+   negative one (WM_BLOCKS / WM_INHIBITS) between the SAME ordered entity
+   pair cannot both be right. Opposing pairs become conflict rows + review
+   initiatives and are NEVER auto-resolved — not at any trust stage, not in
+   live mode. Recency/confidence ordering is how belief conflicts are
+   settled, but a causal claim is a model of the world, and silently picking
+   a winner would let one confidently-worded fabrication erase a true edge.
+   A human (or an explicitly owner-approved flow) closes these.
+
+2. STALENESS: a causal edge that has gone COLONY_CAUSAL_TTL_DAYS (default
+   120) without support (creation or corroboration) loses 0.05 confidence
+   per maintenance run, floored at 0.2 — never deleted. Staleness is judged
+   by the ``last_support_at`` property (stamped by the extractor on create/
+   corroborate) so that the decay write itself cannot reset the clock.
+
+This module is pure computation + read-only store access; every WRITE stays
+in the BeliefEngine where it is mode-gated (live/supervised) and journaled.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Tuple
+
+from apsimo.world_model.constants import CAUSAL_RELATIONSHIP_TYPES
+
+logger = logging.getLogger(__name__)
+
+POSITIVE_CAUSAL = frozenset({"WM_CAUSES", "WM_ENABLES"})
+NEGATIVE_CAUSAL = frozenset({"WM_BLOCKS", "WM_INHIBITS"})
+
+CAUSAL_DECAY_STEP = 0.05
+CAUSAL_DECAY_FLOOR = 0.2
+
+# The property the extractor stamps on every create/corroborate; the decay
+# clock reads it (falling back to updated_at/created_at for pre-existing
+# edges) and deliberately never advances it on a decay write.
+LAST_SUPPORT_PROP = "last_support_at"
+
+
+def causal_ttl_days() -> float:
+    """COLONY_CAUSAL_TTL_DAYS (default 120): days without support before a
+    causal edge starts decaying."""
+    try:
+        v = float(os.environ.get("COLONY_CAUSAL_TTL_DAYS", "120"))
+        return v if v > 0 else 120.0
+    except (TypeError, ValueError):
+        return 120.0
+
+
+async def load_causal_edges(store: Any, limit_per_type: int = 500) -> List[Any]:
+    """All causal edges, via explicitly-typed queries (the only sanctioned
+    read path — causal edges are excluded from generic reads by policy)."""
+    out: List[Any] = []
+    for rel_type in sorted(CAUSAL_RELATIONSHIP_TYPES):
+        try:
+            rels = await store.query_relationships(
+                relationship_type=rel_type, min_confidence=0.0,
+                limit=limit_per_type)
+        except Exception:
+            logger.debug("causal edge load failed for %s", rel_type,
+                         exc_info=True)
+            continue
+        out.extend(rels or [])
+    return out
+
+
+def opposing_pairs(edges: List[Any]) -> List[Tuple[Any, Any]]:
+    """(positive_edge, negative_edge) pairs over the same ordered
+    (source_id, target_id) — the causal contradictions. Inactive edges
+    (valid_to set) are ignored: a closed edge no longer claims anything."""
+    by_pair: Dict[Tuple[str, str], Dict[str, List[Any]]] = {}
+    for e in edges:
+        if getattr(e, "valid_to", None) is not None:
+            continue
+        rel = str(getattr(e, "relationship_type", "") or "").upper()
+        if rel in POSITIVE_CAUSAL:
+            polarity = "pos"
+        elif rel in NEGATIVE_CAUSAL:
+            polarity = "neg"
+        else:
+            continue
+        key = (str(e.source_id), str(e.target_id))
+        by_pair.setdefault(key, {"pos": [], "neg": []})[polarity].append(e)
+    pairs: List[Tuple[Any, Any]] = []
+    for buckets in by_pair.values():
+        for pos in buckets["pos"]:
+            for neg in buckets["neg"]:
+                pairs.append((pos, neg))
+    return pairs
+
+
+def support_timestamp(edge: Any) -> str:
+    """The edge's last-support timestamp (ISO8601), preferring the
+    extractor-stamped property over store bookkeeping columns."""
+    props = getattr(edge, "properties", None) or {}
+    return str(props.get(LAST_SUPPORT_PROP)
+               or getattr(edge, "updated_at", None)
+               or getattr(edge, "created_at", None) or "")
+
+
+def support_age_days(edge: Any, now: datetime) -> float:
+    """Days since the edge was last supported; 0.0 when unparseable (an
+    edge we cannot date is never treated as stale — fail toward keeping)."""
+    raw = support_timestamp(edge)
+    if not raw:
+        return 0.0
+    try:
+        ts = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        return max(0.0, (now - ts).total_seconds() / 86400.0)
+    except Exception:
+        return 0.0
+
+
+def stale_causal_edges(edges: List[Any], now: datetime = None) -> List[Any]:
+    """Causal edges past the TTL that still have confidence to lose."""
+    now = now or datetime.now(timezone.utc)
+    ttl = causal_ttl_days()
+    return [e for e in edges
+            if getattr(e, "valid_to", None) is None
+            and float(getattr(e, "confidence", 0.0) or 0.0) > CAUSAL_DECAY_FLOOR
+            and support_age_days(e, now) > ttl]

apsimo/world_model/causal_policy.py

@@ -0,0 +1,43 @@
+"""Causal-edge policy: causal edges are QUERY-ONLY unless explicitly unlocked.
+
+THE INVARIANT
+    A causal edge (WM_CAUSES / WM_ENABLES / WM_BLOCKS / WM_INHIBITS, see
+    ``CAUSAL_RELATIONSHIP_TYPES``) may be stored, corroborated, decayed and
+    read back to answer "why" / "what happens if" questions — but it must
+    NEVER, on its own, cause Colony to take or schedule an action. An
+    inferred "A causes B" is a belief about the world, not an instruction;
+    acting on a fabricated or stale causal edge is exactly the failure mode
+    this module exists to prevent.
+
+Every consumer that reads causal edges and could turn them into behavior
+(planners, initiative generators, directed actions) MUST gate that path on
+``causal_edges_actionable()``. The flag COLONY_CAUSAL_ACT defaults to off,
+so the invariant holds by default; flipping it is an explicit owner
+decision, revertible via env alone.
+
+This module is intentionally tiny and dependency-free so any layer can
+import it without cycles.
+"""
+
+from __future__ import annotations
+
+import os
+
+from apsimo.world_model.constants import CAUSAL_RELATIONSHIP_TYPES
+
+__all__ = ["CAUSAL_RELATIONSHIP_TYPES", "causal_edges_actionable", "is_causal"]
+
+
+def causal_edges_actionable() -> bool:
+    """May causal edges influence ACTIONS (not just answers)? Default no.
+
+    COLONY_CAUSAL_ACT=1 is the only unlock; anything else (unset, 0, junk)
+    keeps causal edges query-only.
+    """
+    return os.environ.get("COLONY_CAUSAL_ACT", "0").strip().lower() in (
+        "1", "true", "yes", "on")
+
+
+def is_causal(rel_type: str) -> bool:
+    """True when ``rel_type`` is one of the causal relationship types."""
+    return str(rel_type or "").strip().upper() in CAUSAL_RELATIONSHIP_TYPES

apsimo/world_model/causal_query.py

@@ -0,0 +1,125 @@
+"""Read-only causal-chain query — the sanctioned way to READ causal edges.
+
+Causal edges are query-only by policy (world_model/causal_policy.py) and are
+excluded from every generic graph read path: the ONLY surfaces that return
+them are the /world/causal/* endpoints (built on this module) and
+explicitly-typed relationship queries. This module answers "why" / "what
+happens if" questions by walking causal edges alone; it never writes and
+never feeds an action path.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from apsimo.world_model.constants import CAUSAL_RELATIONSHIP_TYPES
+
+logger = logging.getLogger(__name__)
+
+_DIRECTIONS = ("downstream", "upstream", "both")
+
+
+def _edge_dict(rel: Any) -> Dict[str, Any]:
+    props = getattr(rel, "properties", None) or {}
+    return {
+        "id": rel.id,
+        "source_id": rel.source_id,
+        "target_id": rel.target_id,
+        "relationship_type": rel.relationship_type,
+        "confidence": rel.confidence,
+        "is_active": bool(getattr(rel, "is_active", rel.valid_to is None)),
+        "evidence": props.get("evidence"),
+    }
+
+
+async def causal_chain(
+    store: Any,
+    entity_id: str,
+    direction: str = "downstream",
+    max_hops: int = 3,
+    min_confidence: float = 0.0,
+    max_edges: int = 100,
+) -> Dict[str, Any]:
+    """BFS over causal edges only (explicitly typed queries, so the generic
+    read-path exclusion does not apply here — by construction).
+
+    direction: downstream = effects of entity_id; upstream = its causes;
+    both = the full causal neighborhood.
+    """
+    if direction not in _DIRECTIONS:
+        direction = "downstream"
+    max_hops = max(1, min(int(max_hops), 5))
+
+    edges: Dict[str, Dict[str, Any]] = {}
+    visited: Dict[str, int] = {entity_id: 0}
+    frontier = [entity_id]
+    truncated = False
+
+    for hop in range(max_hops):
+        next_frontier: List[str] = []
+        for eid in frontier:
+            for rel_type in sorted(CAUSAL_RELATIONSHIP_TYPES):
+                queries = []
+                if direction in ("downstream", "both"):
+                    queries.append({"source_id": eid})
+                if direction in ("upstream", "both"):
+                    queries.append({"target_id": eid})
+                for q in queries:
+                    rels = await store.query_relationships(
+                        relationship_type=rel_type,
+                        min_confidence=min_confidence, limit=50, **q)
+                    for rel in rels:
+                        if rel.id in edges:
+                            continue
+                        if len(edges) >= max_edges:
+                            truncated = True
+                            break
+                        edges[rel.id] = _edge_dict(rel)
+                        other = (rel.target_id if rel.source_id == eid
+                                 else rel.source_id)
+                        if other not in visited:
+                            visited[other] = hop + 1
+                            next_frontier.append(other)
+                    if truncated:
+                        break
+                if truncated:
+                    break
+            if truncated:
+                break
+        if truncated or not next_frontier:
+            break
+        frontier = next_frontier
+
+    nodes: Dict[str, Dict[str, Any]] = {}
+    for eid in visited:
+        try:
+            ent = await store.get_entity(eid, min_confidence=0.0)
+        except Exception:
+            ent = None
+        if ent is not None:
+            nodes[eid] = {"name": ent.name, "entity_type": ent.entity_type,
+                          "hops": visited[eid]}
+
+    return {
+        "entity_id": entity_id,
+        "direction": direction,
+        "max_hops": max_hops,
+        "edges": list(edges.values()),
+        "nodes": nodes,
+        "truncated": truncated,
+    }
+
+
+async def causal_edges(store: Any, min_confidence: float = 0.0,
+                       limit: int = 100) -> List[Dict[str, Any]]:
+    """Flat list of causal edges (explicitly typed queries per causal type)."""
+    out: List[Dict[str, Any]] = []
+    for rel_type in sorted(CAUSAL_RELATIONSHIP_TYPES):
+        rels = await store.query_relationships(
+            relationship_type=rel_type, min_confidence=min_confidence,
+            limit=limit)
+        out.extend(_edge_dict(r) for r in rels)
+        if len(out) >= limit:
+            break
+    return out[:limit]

apsimo/world_model/confidence.py

@@ -0,0 +1,54 @@
+"""Confidence scoring for World Model entities and properties."""
+
+# Confidence initialization rules (entity-level)
+CONFIDENCE_BY_SOURCE = {
+    "structured_import": 0.95,   # calendar sync, contact import — highly reliable
+    "document_extraction": 0.70, # named entity from PDF, email body
+    "conversation_ner": 0.55,    # NER from message text
+    "inferred": 0.30,            # deduced from context, not explicitly stated
+    "unverified_mention": 0.20,  # single passing mention
+}
+
+# Confidence boost per corroborating observation
+CORROBORATION_BOOST = 0.05
+
+# Confidence ceiling
+MAX_CONFIDENCE = 0.98
+
+# Minimum confidence for an entity to appear in query results by default
+DEFAULT_CONFIDENCE_THRESHOLD = 0.30
+
+# Minimum confidence for storage
+MIN_CONFIDENCE_FOR_STORAGE = 0.20
+
+
+def compute_property_confidence(
+    extraction_source: str,
+    corroboration_count: int = 0,
+) -> float:
+    """Compute property-level confidence from source and corroboration.
+
+    Args:
+        extraction_source: Source type key from CONFIDENCE_BY_SOURCE.
+        corroboration_count: Number of additional observations corroborating this value.
+
+    Returns:
+        Confidence in [0.0, MAX_CONFIDENCE].
+    """
+    base = CONFIDENCE_BY_SOURCE.get(extraction_source, 0.30)
+    boosted = base + corroboration_count * CORROBORATION_BOOST
+    return min(boosted, MAX_CONFIDENCE)
+
+
+def boost_confidence(current: float, amount: float = CORROBORATION_BOOST) -> float:
+    """Boost confidence by amount, capped at MAX_CONFIDENCE."""
+    return min(current + amount, MAX_CONFIDENCE)
+
+
+def apply_extraction_adjustments(base_confidence: float, adjustments: list[float]) -> float:
+    """Apply a list of signed confidence adjustments to a base value.
+
+    Clamps result to [0.0, MAX_CONFIDENCE].
+    """
+    result = base_confidence + sum(adjustments)
+    return max(0.0, min(result, MAX_CONFIDENCE))

apsimo/world_model/config.py

@@ -0,0 +1,64 @@
+"""World Model configuration dataclass."""
+
+import os
+from dataclasses import dataclass, field
+from typing import List
+
+
+def _default_sqlite_path() -> str:
+    """State-dir-anchored default (env-overridable via
+    WORLD_MODEL_SQLITE_PATH). A bare cwd-relative filename made the store
+    land wherever the process happened to start (a git checkout, on the
+    reference deployment), which is fragile across restarts and updates."""
+    explicit = os.environ.get("WORLD_MODEL_SQLITE_PATH", "").strip()
+    if explicit:
+        return explicit
+    state_dir = os.environ.get("COLONY_STATE_DIR", "").strip()
+    if state_dir:
+        return os.path.join(state_dir, "colony_world_model.db")
+    return "colony_world_model.db"
+
+
+@dataclass
+class WorldModelConfig:
+    # ── Feature flags ──────────────────────────────────────────────────
+    enabled: bool = True
+    auto_extract_conversations: bool = True
+    auto_extract_documents: bool = True
+    structured_import_enabled: bool = True
+    entity_resolution_enabled: bool = True
+
+    # ── Backend ────────────────────────────────────────────────────────
+    # SQLite supports canonical typed observations. Alternate backends retain
+    # only the legacy entity/relationship graph, not observation parity.
+    backend: str = "sqlite"         # "sqlite" | "neo4j" | "postgres"
+    neo4j_uri: str = "bolt://localhost:7687"
+    neo4j_database: str = "neo4j"
+    sqlite_path: str = field(default_factory=_default_sqlite_path)
+
+    # ── Confidence thresholds ──────────────────────────────────────────
+    min_confidence_for_storage: float = 0.20
+    min_confidence_for_query: float = 0.30
+    auto_merge_confidence_threshold: float = 0.85
+    propose_merge_confidence_threshold: float = 0.70
+
+    # ── Resolution ─────────────────────────────────────────────────────
+    string_similarity_auto_merge: float = 0.92
+    string_similarity_propose: float = 0.75
+
+    # ── Extraction ─────────────────────────────────────────────────────
+    max_extraction_ms: int = 50     # per-message budget
+    min_message_length_for_extraction: int = 20
+    extraction_spacy_model: str = "en_core_web_sm"
+
+    # ── Graph traversal ────────────────────────────────────────────────
+    max_graph_hops: int = 5
+    default_graph_hops: int = 2
+    max_traversal_nodes: int = 200
+
+    # ── Retention ─────────────────────────────────────────────────────
+    low_confidence_entity_ttl_days: int = 90
+    merge_proposal_expiry_days: int = 30
+
+    # ── Briefing limits ────────────────────────────────────────────────
+    max_world_model_briefing_items_per_day: int = 3

apsimo/world_model/constants.py

@@ -0,0 +1,97 @@
+"""World Model constants: entity types, relationship types, external ID keys."""
+
+# ── Entity Types ──────────────────────────────────────────────────────────────
+
+ENTITY_TYPES = frozenset({
+    "person",
+    "company",
+    "project",
+    "product",
+    "location",
+    "event",
+    "concept",
+})
+
+# ── Relationship Types (WM_ prefixed for Neo4j namespace safety) ──────────────
+
+RELATIONSHIP_TYPES = frozenset({
+    "WM_WORKS_AT",
+    "WM_FOUNDED",
+    "WM_OWNS",
+    "WM_INVESTED_IN",
+    "WM_ADVISES",
+    "WM_MANAGES",
+    "WM_REPORTS_TO",
+    "WM_KNOWS",
+    "WM_INTRODUCED_BY",  # provenance: who introduced this person to the agent's graph
+    "WM_PARTNER_OF",
+    "WM_ACQUIRED",
+    "WM_PART_OF",
+    "WM_LOCATED_IN",
+    "WM_MEMBER_OF",
+    "WM_ATTENDED",
+    "WM_ORGANIZED",
+    "WM_PRODUCED",
+    "WM_USES",
+    "WM_RELATED_TO",
+    "WM_TAGGED_WITH",
+    "WM_MENTIONS",
+    "WM_PREDECESSOR_OF",
+    "WM_SUCCESSOR_OF",
+    "WM_DEPENDS_ON",
+    # Causal vocabulary (query-only; see world_model/causal_policy.py)
+    "WM_CAUSES",
+    "WM_ENABLES",
+    "WM_BLOCKS",
+    "WM_INHIBITS",
+})
+
+# ── Causal Relationship Types ─────────────────────────────────────────────────
+# The causal subset of RELATIONSHIP_TYPES. Causal edges are QUERY-ONLY by
+# policy: they may inform answers to "why"/"what happens if" questions but
+# must never trigger actions unless world_model.causal_policy explicitly
+# says otherwise (COLONY_CAUSAL_ACT, default off).
+
+CAUSAL_RELATIONSHIP_TYPES = frozenset({
+    "WM_CAUSES",     # A brings about B
+    "WM_ENABLES",    # A makes B possible (necessary-ish precondition)
+    "WM_BLOCKS",     # A prevents B outright
+    "WM_INHIBITS",   # A makes B less likely / weaker
+})
+
+# ── External ID Keys ──────────────────────────────────────────────────────────
+
+EXTERNAL_ID_KEYS = {
+    # People
+    "linkedin": "LinkedIn profile URL or ID",
+    "email": "Primary email address",
+    "phone": "E.164 phone number",
+    "twitter": "Twitter/X handle",
+
+    # Companies
+    "crunchbase": "Crunchbase organization slug",
+    "linkedin_company": "LinkedIn company ID",
+    "ticker": "Stock ticker symbol",
+    "domain": "Primary web domain",
+    "lei": "Legal Entity Identifier (ISO 17442)",
+
+    # Events
+    "calendar_uid": "iCal UID from calendar source",
+    "eventbrite": "Eventbrite event ID",
+
+    # Products
+    "app_store_id": "Apple App Store bundle ID",
+    "play_store_id": "Google Play package name",
+
+    # Locations
+    "geonames_id": "GeoNames feature ID",
+    "osm_id": "OpenStreetMap node/way/relation ID",
+}
+
+# ── ID Prefixes ───────────────────────────────────────────────────────────────
+
+ENTITY_ID_PREFIX = "we"         # world entity
+RELATIONSHIP_ID_PREFIX = "wr"   # world relationship
+OBSERVATION_ID_PREFIX = "wo"    # world observation
+MERGE_PROPOSAL_ID_PREFIX = "mp" # merge proposal
+MERGE_AUDIT_ID_PREFIX = "ma"    # merge audit record

apsimo/world_model/entities.py

@@ -0,0 +1,145 @@
+"""World Model entity dataclasses.
+
+Seven entity types form Colony's world model:
+  Person, Company, Project, Product, Location, Event, Concept
+
+All share BaseEntity fields. Each adds domain-specific properties.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+from datetime import datetime
+
+
+@dataclass
+class BaseEntity:
+    """Common properties for all world model entities."""
+    id: str                          # we-<timestamp>-<random7>
+    name: str                        # canonical display name
+    entity_type: str                 # EntityType literal
+    aliases: List[str] = field(default_factory=list)
+    external_ids: Dict[str, str] = field(default_factory=dict)
+    confidence: float = 0.5          # 0.0–1.0 overall entity confidence
+    properties: Dict[str, Any] = field(default_factory=dict)
+    first_seen: Optional[datetime] = None
+    last_seen: Optional[datetime] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+@dataclass
+class PersonEntity(BaseEntity):
+    """A person Colony has encountered or knows about."""
+    entity_type: str = "person"
+    email: Optional[str] = None
+    phone: Optional[str] = None
+    title: Optional[str] = None       # "CTO", "Engineer"
+    bio_summary: Optional[str] = None
+    linkedin_url: Optional[str] = None
+    twitter_handle: Optional[str] = None
+    location_id: Optional[str] = None  # FK to LocationEntity
+
+
+@dataclass
+class CompanyEntity(BaseEntity):
+    """An organization of any kind."""
+    entity_type: str = "company"
+    domain: Optional[str] = None       # "acme.com"
+    industry: Optional[str] = None     # "SaaS", "Healthcare"
+    size_range: Optional[str] = None   # "1-10", "11-50", "51-200", "201-1000", "1000+"
+    founded_year: Optional[int] = None
+    headquarters_id: Optional[str] = None  # FK to LocationEntity
+    linkedin_url: Optional[str] = None
+    crunchbase_url: Optional[str] = None
+    ticker: Optional[str] = None       # "AAPL", "GOOG"
+    description: Optional[str] = None
+
+
+@dataclass
+class ProjectEntity(BaseEntity):
+    """A bounded initiative with participants and a goal."""
+    entity_type: str = "project"
+    description: Optional[str] = None
+    status: Optional[str] = None       # "active", "completed", "paused", "cancelled"
+    start_date: Optional[str] = None   # ISO8601
+    end_date: Optional[str] = None     # ISO8601; None = ongoing
+    owner_id: Optional[str] = None     # FK to PersonEntity
+    company_id: Optional[str] = None   # FK to CompanyEntity
+
+
+@dataclass
+class ProductEntity(BaseEntity):
+    """A product, service, or software artifact."""
+    entity_type: str = "product"
+    category: Optional[str] = None     # "SaaS", "hardware", "API"
+    version: Optional[str] = None
+    url: Optional[str] = None
+    company_id: Optional[str] = None   # FK to CompanyEntity
+    description: Optional[str] = None
+
+
+@dataclass
+class LocationEntity(BaseEntity):
+    """A geographic or virtual place."""
+    entity_type: str = "location"
+    location_type: Optional[str] = None  # "city", "country", "office", "virtual"
+    city: Optional[str] = None
+    country: Optional[str] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    timezone: Optional[str] = None      # "America/Los_Angeles"
+
+
+@dataclass
+class EventEntity(BaseEntity):
+    """A time-bounded occurrence."""
+    entity_type: str = "event"
+    event_type: Optional[str] = None    # "meeting", "conference", "deadline", "launch"
+    start_time: Optional[str] = None    # ISO8601
+    end_time: Optional[str] = None      # ISO8601
+    location_id: Optional[str] = None
+    organizer_id: Optional[str] = None  # FK to PersonEntity or CompanyEntity
+    url: Optional[str] = None
+    description: Optional[str] = None
+
+
+@dataclass
+class ConceptEntity(BaseEntity):
+    """An abstract topic, technology, or category."""
+    entity_type: str = "concept"
+    concept_type: Optional[str] = None   # "technology", "methodology", "regulation", "topic"
+    description: Optional[str] = None
+    parent_concept_id: Optional[str] = None  # for hierarchical concepts
+
+
+# Type union for all entity types
+EntityType = (
+    Union[PersonEntity, CompanyEntity, ProjectEntity,
+    ProductEntity, LocationEntity, EventEntity, ConceptEntity]
+)
+
+# Map from entity_type string to dataclass
+ENTITY_CLASS_MAP: Dict[str, type] = {
+    "person": PersonEntity,
+    "company": CompanyEntity,
+    "project": ProjectEntity,
+    "product": ProductEntity,
+    "location": LocationEntity,
+    "event": EventEntity,
+    "concept": ConceptEntity,
+}
+
+
+def entity_from_dict(data: Dict[str, Any]) -> BaseEntity:
+    """Reconstruct an entity from a flat dict (e.g., from SQLite row).
+
+    Maps 'entity_type' to the appropriate subclass and constructs it.
+    Unknown types fall back to BaseEntity.
+    """
+    entity_type = data.get("entity_type", "")
+    cls = ENTITY_CLASS_MAP.get(entity_type, BaseEntity)
+    # Filter data keys to only those accepted by the dataclass
+    import dataclasses
+    valid_fields = {f.name for f in dataclasses.fields(cls)}
+    filtered = {k: v for k, v in data.items() if k in valid_fields}
+    return cls(**filtered)