engrammic-primitives 0.1.0__py3-none-any.whl

engrammic_primitives-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: engrammic-primitives
+Version: 0.1.0
+Summary: EAG schema primitives for epistemic context management
+Author-email: Aliasgar Khimani <aliasgar.khimani@engrammic.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,context-management,graphrag,knowledge-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# Engrammic Primitives
+
+EAG schema primitives for building epistemic context systems.
+
+## Install
+
+```bash
+pip install engrammic-primitives
+```
+
+## Usage
+
+```python
+from primitives.schema import MemoryNode, KnowledgeNode, WisdomNode
+from primitives.eag import CognitiveTier
+
+# Create a memory node
+node = MemoryNode(
+    content="User prefers dark mode",
+    importance=0.7,
+)
+
+# Check cognitive tier
+tier = CognitiveTier.MEMORY
+```
+
+## When to Use
+
+Building your own EAG-compatible system or extending Engrammic.
+
+For using Engrammic directly, see:
+- [engrammic-mcp](https://github.com/engrammic/mcp-client) - hosted service
+- [engrammic-engine](https://github.com/engrammic/engine) - local engine
+
+## Learn More
+
+- [EAG Manifesto](docs/manifesto.md) - the paradigm explained
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `primitives.schema` | Node and edge type definitions |
+| `primitives.eag` | EAG-specific implementations |
+| `primitives.protocols` | Storage and lifecycle interfaces |
+| `primitives.scoring` | Decay and freshness formulas |
+
+## License
+
+Apache 2.0

engrammic_primitives-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+primitives/__init__.py,sha256=nL6wRTqSdfJnkKV_tEf7Pa7M71gTL22Df6r18cbVccc,136
+primitives/protocols.py,sha256=OalpW1jQq3KvWRg8oG2O_JP9Du1oSLdvrqYW2W-ykW0,8383
+primitives/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+primitives/eag/__init__.py,sha256=yIdHFHIdb0bW7CBsBKT-ZN9q1enZNU4WD3bOL_lV2iE,1119
+primitives/eag/lifecycle.py,sha256=qh78xtbQ5UdFF1DzS9JfkT71YK4IHy1rMnKXmO9gtdY,4454
+primitives/eag/store.py,sha256=nLVl4RfxLjN8sIYGjBgGerHbIeR75T5NgTSC6iIaVII,2509
+primitives/eag/agents/__init__.py,sha256=OPTv2TMGrbXBINTgB4lwrzXM6oyy4yHs0cKLMegtusU,712
+primitives/eag/agents/base.py,sha256=FZfQyxRT_OhwgYtddRD9vVAnym-VGFQ14CHwHt_imMk,3223
+primitives/eag/agents/tools.py,sha256=z8QpyMCKRVr_sv1rd9pNwE__xHiMe8FsldWG1yfTvsM,1980
+primitives/eag/epistemology/__init__.py,sha256=5q3C1Gbe-iIRbKltVj9V0D0pAVDIo6sKiNZ6ujkooAc,1071
+primitives/eag/epistemology/confidence.py,sha256=fc5Ye3jMh2LzV6gnAgNhcYa0jOcS84WoiInjOsaY39Q,4177
+primitives/eag/epistemology/promotion.py,sha256=d816t1oPA3DsmCoKuV8glXo4-cQJixF4_T1Ln2ClJzA,3437
+primitives/eag/epistemology/supersession.py,sha256=hPwVSQyJaCfaistSy7BoKo11R1215pBW1QLaeMcqflA,3653
+primitives/eag/queries/__init__.py,sha256=A8UMF_uS8u311WaiyMrwBdlEL7nnVQT9qwEJX4lzJqc,2706
+primitives/eag/queries/cluster.py,sha256=aZRkGmq2Kd614qydtLc5QbwGix8B7XvbQd_HYcodH3U,3301
+primitives/eag/queries/ddl.py,sha256=bavztY-QGWZmOoIITCrjNczC8KiMRxATXaVxtG5QVFU,2512
+primitives/eag/queries/finding.py,sha256=Y5mjKYH0_WmSxcVjAAzWHh1ntidrNNSHCerZ-SBVItg,4948
+primitives/eag/queries/pass_ledger.py,sha256=oereFR-5SNrCR7EjsF-5PraB4l71KhHWz5zOoKz9Kjs,2361
+primitives/eag/queries/silo.py,sha256=yW7hn2eU_941X0b8AP4Ji9_6UTP2S_KAm0VN4uErfbs,1098
+primitives/eag/transitions/__init__.py,sha256=EUWoZxpvZAyX9WKAy9VO0qVhzVmMzqDoalgKyf1a_yk,243
+primitives/eag/transitions/predicates.py,sha256=MpYTo-2NBv6OQnPQt2zUa_lx0I9ToCnDtE1tr05zYoo,787
+primitives/extensions/__init__.py,sha256=prvW-U5XrULsOS4mq-2CXPOAlGWpMEZFwQ6SNc-4U9o,57
+primitives/extensions/code.py,sha256=cSQfJKhDEUBy5ZG5c2_uGfj1MR3pFcyVoQIcB-UkD2A,1001
+primitives/schema/__init__.py,sha256=jrtgvFhruq4XCkioXIqPeODMWNuEgOCb1Jb8hdPRs9M,1348
+primitives/schema/edges.py,sha256=RrdDeDgOK6wmH3W5synfEc-_pQFcClgNRMmqFUpQrKE,1769
+primitives/schema/labels.py,sha256=z5z_01sDU59Q2xpTavJ-RSnx3lLSUO-4nNyS6gEHx_s,3635
+primitives/scoring/__init__.py,sha256=T-3fWDlMGkoo-SPK23eMtIVgkAiKu85bMiZvv9Vnm9c,189
+primitives/scoring/decay.py,sha256=T1UNZ-5tFmwGl-1v0ri9hhLM-yO3m8hqziX4WnccX10,687
+primitives/shared/__init__.py,sha256=zghiwCEcKdwaHdVJIwFBsg9M9_XfBYSKbisDFRnUqSs,796
+primitives/shared/fingerprints.py,sha256=BONc4mKj0MuC-UcAMyOM3OhXBNz_8ZaqJubf4ZWLlnM,2347
+primitives/shared/validators.py,sha256=hkYvoTeNaURGeDUCnjYhDQLr_G4Blc_LQ-p12U37GAY,2946
+primitives/shared/cypher/__init__.py,sha256=gNTqo9P89Ue3uRQzAgRFnWoo7hiijL8FtinY4T52OPw,362
+primitives/shared/cypher/helpers.py,sha256=ciL7AwKXUOklIigRrRA0AC1NKIaVnfY0P3RtbkdV-BA,1558
+primitives/taxonomy/__init__.py,sha256=8EaCStzHThSHkxO-N1X_A3rBmcfUx-p5vVQa-JE_aqE,263
+primitives/taxonomy/categories.py,sha256=44tuSkYTcmwdaYXwUjuonGPwR3k045aJofDneHPjzfM,887
+engrammic_primitives-0.1.0.dist-info/METADATA,sha256=JV-G9b-O1z-B7Q2SpCHSWkcou4iJuvYarR9z52bNoaY,1795
+engrammic_primitives-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+engrammic_primitives-0.1.0.dist-info/licenses/LICENSE,sha256=esUnW0wDJTg5GnYzhkHmYMUpyPvOfw9Uu1xew_bTn24,1068
+engrammic_primitives-0.1.0.dist-info/RECORD,,

engrammic_primitives-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

engrammic_primitives-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delta Prime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

primitives/__init__.py

@@ -0,0 +1,6 @@
+"""GraphRAG primitives library.
+
+Hot-swappable knowledge management primitives for AI agent context systems.
+"""
+
+__version__ = "0.1.0"

primitives/eag/__init__.py

@@ -0,0 +1,44 @@
+"""EAG (Epistemic Augmented Generation) implementation.
+
+Four-layer cognitive architecture: Memory -> Knowledge -> Wisdom -> Intelligence.
+Implements the protocol interfaces with EAG-specific semantics.
+"""
+
+# Epistemology exports
+from primitives.eag.epistemology import (
+    ClaimForPromotion,
+    ContradictionResult,
+    PromotionDecision,
+    PromotionRule,
+    SourceTier,
+    SupersessionDecision,
+    combined_confidence,
+    detect_contradiction,
+    incremental_noisy_or,
+    noisy_or_aggregate,
+    should_promote_r1,
+    should_promote_r2,
+    should_supersede,
+)
+from primitives.eag.lifecycle import EAGLifecycleManager
+from primitives.eag.store import EAGKnowledgeStore
+
+__all__ = [
+    # Epistemology
+    "SourceTier",
+    "combined_confidence",
+    "noisy_or_aggregate",
+    "incremental_noisy_or",
+    "PromotionRule",
+    "ClaimForPromotion",
+    "PromotionDecision",
+    "should_promote_r1",
+    "should_promote_r2",
+    "ContradictionResult",
+    "detect_contradiction",
+    "should_supersede",
+    "SupersessionDecision",
+    # Implementations
+    "EAGKnowledgeStore",
+    "EAGLifecycleManager",
+]

primitives/eag/agents/__init__.py

@@ -0,0 +1,34 @@
+"""EAG Agent Protocol definitions.
+
+Defines abstract interfaces for EAG agents and tools. Implementations
+live in private repositories (context-service); this module provides
+the protocol contract that implementations must follow.
+"""
+
+from primitives.eag.agents.base import (
+    AgentConfig,
+    AgentPhase,
+    AgentProtocol,
+    AgentResult,
+    BudgetConfig,
+    BudgetStatus,
+    DepsProtocol,
+)
+from primitives.eag.agents.tools import (
+    ToolDefinition,
+    ToolProtocol,
+    ToolResult,
+)
+
+__all__ = [
+    "AgentConfig",
+    "AgentPhase",
+    "AgentProtocol",
+    "AgentResult",
+    "BudgetConfig",
+    "BudgetStatus",
+    "DepsProtocol",
+    "ToolDefinition",
+    "ToolProtocol",
+    "ToolResult",
+]

primitives/eag/agents/base.py

@@ -0,0 +1,135 @@
+"""Base protocol definitions for EAG agents.
+
+Agents in EAG operate in phases (fast, plan, deep, stitch), each with
+distinct output types and budget constraints. This module defines the
+abstract interfaces; implementations are private.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from primitives.eag.agents.tools import ToolProtocol
+
+
+class AgentPhase(StrEnum):
+    """Visit phases for EAG agents."""
+
+    FAST = "fast"
+    PLAN = "plan"
+    DEEP = "deep"
+    STITCH = "stitch"
+
+
+class BudgetStatus(BaseModel):
+    """Budget state exposed to agents in tool responses."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tokens_remaining: int
+    tool_calls_remaining: int
+    wrap_up_signal: bool
+
+
+@dataclass
+class BudgetConfig:
+    """Per-phase budget configuration."""
+
+    nominal_tokens: int
+    hard_tokens: int
+    tool_calls_limit: int
+    request_limit: int
+    soft_signal_ratio: float = 0.69
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for an agent instance."""
+
+    phase: AgentPhase
+    model: str
+    budget: BudgetConfig
+    retries: int = 8
+
+
+T = TypeVar("T")
+DepsT = TypeVar("DepsT", bound="DepsProtocol")
+OutputT = TypeVar("OutputT")
+
+
+@runtime_checkable
+class DepsProtocol(Protocol):
+    """Minimal interface for per-visit dependencies.
+
+    Implementations carry org/silo/cluster context, buffer for committed
+    artifacts, and infrastructure handles. The protocol defines only the
+    fields that tools and result types depend on.
+    """
+
+    org_id: str
+    silo_id: str
+    cluster_id: str
+    pass_id: str
+    seen_node_ids: set[str]
+    budget: BudgetStatus
+    finalized: bool
+
+    def record_commit(self, event: dict[str, Any]) -> None:
+        """Append an event to the commit log."""
+        ...
+
+
+@dataclass
+class AgentResult(Generic[T]):
+    """Result from an agent run."""
+
+    output: T
+    finalized: bool
+    claims_committed: int
+    edges_committed: int
+    rejections: int
+    tokens_used: int
+    tool_calls_used: int
+    commit_log: list[dict[str, Any]] = field(default_factory=list)
+
+
+@runtime_checkable
+class AgentProtocol(Protocol[DepsT, OutputT]):
+    """Protocol for EAG agents.
+
+    An agent encapsulates a model, system prompt, output type, and budget
+    constraints. Tools are registered separately via the ToolProtocol.
+    """
+
+    @property
+    def phase(self) -> AgentPhase:
+        """The phase this agent operates in."""
+        ...
+
+    @property
+    def config(self) -> AgentConfig:
+        """Agent configuration."""
+        ...
+
+    @abstractmethod
+    async def run(
+        self,
+        deps: DepsT,
+        user_prompt: str,
+    ) -> AgentResult[OutputT]:
+        """Execute the agent with the given dependencies and prompt.
+
+        The agent runs until it produces an output, calls finalize, or
+        exhausts its budget. Tools mutate deps in place.
+        """
+        ...
+
+    def register_tool(self, tool: ToolProtocol[DepsT]) -> None:
+        """Register a tool on this agent."""
+        ...

primitives/eag/agents/tools.py

@@ -0,0 +1,77 @@
+"""Tool protocol definitions for EAG agents.
+
+Tools are functions that agents call to read state, commit artifacts, or
+signal completion. Each tool call updates the budget and may mutate the
+dependency container.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from primitives.eag.agents.base import BudgetStatus, DepsProtocol
+
+DepsT = TypeVar("DepsT", bound=DepsProtocol)
+ResultT = TypeVar("ResultT")
+
+
+class ToolResult(BaseModel):
+    """Base class for tool results. All results carry budget status."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    budget_status: BudgetStatus
+
+
+class ToolDefinition(BaseModel):
+    """Metadata describing a tool for schema generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str
+    parameters_schema: dict[str, Any]
+    result_schema: dict[str, Any]
+
+
+@runtime_checkable
+class ToolProtocol(Protocol[DepsT]):  # type: ignore[misc]
+    """Protocol for EAG agent tools.
+
+    Tools are async callables that receive a context (containing deps)
+    and arguments, returning a result that includes budget status.
+    """
+
+    @property
+    def name(self) -> str:
+        """Tool name as exposed to the agent."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Description shown to the agent."""
+        ...
+
+    @property
+    def definition(self) -> ToolDefinition:
+        """Full tool definition for schema generation."""
+        ...
+
+    @abstractmethod
+    async def __call__(
+        self,
+        deps: DepsT,
+        **kwargs: Any,
+    ) -> ToolResult:
+        """Execute the tool.
+
+        Implementations should:
+        1. Perform the operation (read, commit, etc.)
+        2. Update deps.seen_node_ids if nodes were returned
+        3. Rebuild the budget status
+        4. Return a result with the updated budget
+        """
+        ...

primitives/eag/epistemology/__init__.py

@@ -0,0 +1,45 @@
+"""Epistemology primitives: confidence, promotion, supersession.
+
+All functions here are pure and deterministic. No LLM calls happen
+at adjudication time.
+"""
+
+from primitives.eag.epistemology.confidence import (
+    SourceTier,
+    combined_confidence,
+    incremental_noisy_or,
+    noisy_or_aggregate,
+    partial_confidence,
+)
+from primitives.eag.epistemology.promotion import (
+    ClaimForPromotion,
+    PromotionDecision,
+    PromotionRule,
+    should_promote_r1,
+    should_promote_r2,
+)
+from primitives.eag.epistemology.supersession import (
+    ContradictionResult,
+    FactForSupersession,
+    SupersessionDecision,
+    detect_contradiction,
+    should_supersede,
+)
+
+__all__ = [
+    "SourceTier",
+    "combined_confidence",
+    "noisy_or_aggregate",
+    "incremental_noisy_or",
+    "partial_confidence",
+    "PromotionRule",
+    "ClaimForPromotion",
+    "PromotionDecision",
+    "should_promote_r1",
+    "should_promote_r2",
+    "ContradictionResult",
+    "FactForSupersession",
+    "SupersessionDecision",
+    "detect_contradiction",
+    "should_supersede",
+]

primitives/eag/epistemology/confidence.py

@@ -0,0 +1,138 @@
+"""Confidence computation primitives.
+
+Pure functions for computing claim and aggregate confidence scores.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from functools import reduce
+
+
+class SourceTier(StrEnum):
+    """Source credibility tiers with associated weights."""
+
+    AUTHORITATIVE = "authoritative"  # 1.0
+    VALIDATED = "validated"  # 0.85
+    COMMUNITY = "community"  # 0.6
+    UNKNOWN = "unknown"  # 0.4
+
+    @property
+    def weight(self) -> float:
+        return _TIER_WEIGHTS[self]
+
+
+_TIER_WEIGHTS: dict[SourceTier, float] = {
+    SourceTier.AUTHORITATIVE: 1.0,
+    SourceTier.VALIDATED: 0.85,
+    SourceTier.COMMUNITY: 0.6,
+    SourceTier.UNKNOWN: 0.4,
+}
+
+
+def combined_confidence(
+    raw_confidence: float,
+    source_tier: SourceTier,
+    corroboration_factor: float = 1.0,
+    method_weight: float = 1.0,
+) -> float:
+    """Compute combined confidence for a single claim.
+
+    Formula: source_tier * corroboration_factor * method_weight * raw_confidence
+
+    Args:
+        raw_confidence: Base confidence from extraction (0.0 - 1.0)
+        source_tier: Credibility tier of the source
+        corroboration_factor: Boost from corroborating evidence (default 1.0)
+        method_weight: Weight based on extraction method (default 1.0)
+
+    Returns:
+        Combined confidence score (0.0 - 1.0)
+    """
+    result = source_tier.weight * corroboration_factor * method_weight * raw_confidence
+    return min(max(result, 0.0), 1.0)
+
+
+def noisy_or_aggregate(confidences: list[float], cap: float = 0.99) -> float:
+    """Aggregate multiple confidence scores using noisy-OR.
+
+    Formula: 1 - product(1 - c_i) for each confidence c_i
+
+    This models independent evidence: each source has a chance of being
+    correct, and we want the probability that at least one is correct.
+
+    Args:
+        confidences: List of individual confidence scores
+        cap: Maximum return value (default 0.99)
+
+    Returns:
+        Aggregated confidence score, capped at `cap`
+    """
+    if not confidences:
+        return 0.0
+
+    # 1 - product(1 - c_i)
+    complement_product = reduce(lambda acc, c: acc * (1 - c), confidences, 1.0)
+    result = 1 - complement_product
+
+    return min(result, cap)
+
+
+_EPISTEMIC_DISCOUNT: float = 0.7
+"""Discount applied to uncorroborated single-source claims.
+
+A claim supported by only one source has inherent uncertainty that
+corroboration resolves. This factor represents the pre-corroboration
+epistemic penalty.
+"""
+
+
+def partial_confidence(
+    raw_confidence: float,
+    source_reliability: float = 1.0,
+) -> float:
+    """Compute pre-corroboration confidence for a single-source claim.
+
+    Used when storing a Claim before corroboration has occurred. The result
+    is a provisional score; once the claim is corroborated and promoted to
+    a Fact, `combined_confidence` should be used to derive the final score.
+
+    Formula: raw_confidence * source_reliability * EPISTEMIC_DISCOUNT (0.7)
+
+    The 0.7 epistemic discount reflects that single-source claims carry
+    inherent uncertainty regardless of source quality. Corroboration by
+    independent sources removes this discount.
+
+    Args:
+        raw_confidence: Base confidence from extraction (0.0 - 1.0).
+        source_reliability: Reliability multiplier for the source (0.0 - 1.0,
+            default 1.0 for an unqualified source).
+
+    Returns:
+        Provisional confidence score clamped to [0.0, 1.0].
+    """
+    result = raw_confidence * source_reliability * _EPISTEMIC_DISCOUNT
+    return min(max(result, 0.0), 1.0)
+
+
+def incremental_noisy_or(
+    current_aggregate: float,
+    new_confidence: float,
+    cap: float = 0.99,
+) -> float:
+    """Incrementally update a noisy-OR aggregate with a new confidence.
+
+    Equivalent to recomputing from scratch but O(1) instead of O(n).
+
+    Formula: 1 - (1 - current) * (1 - new)
+
+    Args:
+        current_aggregate: Existing aggregated confidence
+        new_confidence: New confidence to incorporate
+        cap: Maximum return value (default 0.99)
+
+    Returns:
+        Updated aggregated confidence
+    """
+    result = 1 - (1 - current_aggregate) * (1 - new_confidence)
+    return min(result, cap)