autonoesis 0.2.0__py3-none-any.whl

autonoesis/__init__.py

@@ -0,0 +1,57 @@
+"""Autonoesis: self-modeling and phenomenology primitives for cognitive agents."""
+
+from autonoesis.episodic import (
+    SelfModelEpisode,
+    episode_summary,
+    predict_next,
+    surprise,
+)
+from autonoesis.models import (
+    AgencyAttribution,
+    BoundaryState,
+    OwnershipAttribution,
+    PerspectiveState,
+    PhenomenalState,
+    SelfModel,
+    TransparencyLevel,
+)
+from autonoesis.operators import (
+    assess_agency,
+    assess_ownership,
+    boundary_integrity,
+    surprise_to_observation_match,
+    transparency_audit,
+    update_attribution_from_observation,
+    update_ownership_from_observation,
+    update_precision,
+    update_self_model,
+)
+from autonoesis.store import (
+    InMemorySelfModelStore,
+    SelfModelStore,
+)
+
+__all__ = [
+    "AgencyAttribution",
+    "BoundaryState",
+    "InMemorySelfModelStore",
+    "OwnershipAttribution",
+    "PerspectiveState",
+    "PhenomenalState",
+    "SelfModel",
+    "SelfModelEpisode",
+    "SelfModelStore",
+    "TransparencyLevel",
+    "assess_agency",
+    "assess_ownership",
+    "boundary_integrity",
+    "episode_summary",
+    "predict_next",
+    "surprise",
+    "surprise_to_observation_match",
+    "transparency_audit",
+    "update_attribution_from_observation",
+    "update_ownership_from_observation",
+    "update_precision",
+    "update_self_model",
+]

autonoesis/episodic.py

@@ -0,0 +1,111 @@
+"""Successor-stream primitives over ``SelfModel``.
+
+The episodic layer records a subject's self-model trajectory as a frozen,
+append-only sequence. It does not journal to disk or schedule updates; those
+concerns belong to host adapters (see ``autonoesis.store``) and to active
+inference (see ``autonoesis.operators``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from autonoesis.models import (
+    SelfModel,
+    TransparencyLevel,
+    _clamp,
+)
+
+
+@dataclass(frozen=True)
+class SelfModelEpisode:
+    """A monotonic, append-only sequence of ``SelfModel`` snapshots."""
+
+    subject_id: str
+    history: tuple[SelfModel, ...] = ()
+
+    def __post_init__(self) -> None:
+        for snapshot in self.history:
+            if snapshot.subject_id != self.subject_id:
+                raise ValueError(
+                    f"snapshot subject_id {snapshot.subject_id!r} does not match "
+                    f"episode subject_id {self.subject_id!r}"
+                )
+        for prev, curr in zip(self.history, self.history[1:], strict=False):
+            if curr.revision <= prev.revision:
+                raise ValueError(
+                    "episode revisions must strictly increase: "
+                    f"{prev.revision} -> {curr.revision}"
+                )
+
+    def extended(self, snapshot: SelfModel) -> SelfModelEpisode:
+        """Return a successor episode with ``snapshot`` appended."""
+        if snapshot.subject_id != self.subject_id:
+            raise ValueError(
+                f"snapshot subject_id {snapshot.subject_id!r} does not match "
+                f"episode subject_id {self.subject_id!r}"
+            )
+        if self.history and snapshot.revision <= self.history[-1].revision:
+            raise ValueError(
+                f"snapshot revision {snapshot.revision} must exceed "
+                f"current tail revision {self.history[-1].revision}"
+            )
+        return SelfModelEpisode(
+            subject_id=self.subject_id,
+            history=(*self.history, snapshot),
+        )
+
+
+def episode_summary(episode: SelfModelEpisode) -> Mapping[str, float]:
+    """Return a read-only summary mapping over an episode's history."""
+    history = episode.history
+    if not history:
+        return MappingProxyType(
+            {
+                "length": 0.0,
+                "mean_salience": 0.0,
+                "mean_arousal": 0.0,
+                "peak_arousal": 0.0,
+                "transparent_fraction": 0.0,
+            }
+        )
+    n = len(history)
+    salience_sum = sum(s.phenomenal.salience for s in history)
+    arousal_sum = sum(s.phenomenal.arousal for s in history)
+    peak_arousal = max(s.phenomenal.arousal for s in history)
+    transparent_count = sum(
+        1 for s in history if s.phenomenal.transparency is TransparencyLevel.TRANSPARENT
+    )
+    return MappingProxyType(
+        {
+            "length": float(n),
+            "mean_salience": _clamp(salience_sum / n),
+            "mean_arousal": _clamp(arousal_sum / n),
+            "peak_arousal": _clamp(peak_arousal),
+            "transparent_fraction": _clamp(transparent_count / n),
+        }
+    )
+
+
+def predict_next(episode: SelfModelEpisode) -> SelfModel | None:
+    """Return the v0.2 baseline prediction for the next snapshot.
+
+    Returns ``None`` when ``history`` is empty, otherwise the last snapshot.
+    """
+    if not episode.history:
+        return None
+    return episode.history[-1]
+
+
+def surprise(predicted: SelfModel, actual: SelfModel) -> float:
+    """Return a clamped ``[0, 1]`` distance between two ``SelfModel`` snapshots."""
+    components = (
+        abs(predicted.phenomenal.salience - actual.phenomenal.salience),
+        abs(predicted.phenomenal.valence - actual.phenomenal.valence) / 2.0,
+        abs(predicted.phenomenal.arousal - actual.phenomenal.arousal),
+        abs(predicted.agency.confidence - actual.agency.confidence),
+        abs(predicted.ownership.confidence - actual.ownership.confidence),
+    )
+    return _clamp(sum(components) / len(components))

autonoesis/models.py

@@ -0,0 +1,126 @@
+"""Typed self-model and phenomenology records.
+
+The records in this module are intentionally frozen. Host systems should create
+successor records instead of mutating cognitive state in place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+
+def _frozen_metadata(metadata: Mapping[str, Any] | None) -> Mapping[str, Any]:
+    return MappingProxyType(dict(metadata or {}))
+
+
+class TransparencyLevel(StrEnum):
+    """How available a process is to the agent's self-model."""
+
+    TRANSPARENT = "transparent"
+    PARTLY_OPAQUE = "partly_opaque"
+    OPAQUE = "opaque"
+
+
+@dataclass(frozen=True)
+class PhenomenalState:
+    """Current phenomenal field summary for an agent."""
+
+    salience: float = 0.0
+    valence: float = 0.0
+    arousal: float = 0.0
+    perspective: str = "first_person"
+    transparency: TransparencyLevel = TransparencyLevel.PARTLY_OPAQUE
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "salience", _clamp(self.salience))
+        object.__setattr__(self, "valence", _clamp(self.valence, -1.0, 1.0))
+        object.__setattr__(self, "arousal", _clamp(self.arousal))
+        object.__setattr__(self, "metadata", _frozen_metadata(self.metadata))
+
+
+@dataclass(frozen=True)
+class AgencyAttribution:
+    """Attribution that an event/action is controlled by the subject."""
+
+    confidence: float = 0.0
+    intention_strength: float = 0.0
+    outcome_match: float = 0.0
+    external_override: float = 0.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "confidence", _clamp(self.confidence))
+        object.__setattr__(self, "intention_strength", _clamp(self.intention_strength))
+        object.__setattr__(self, "outcome_match", _clamp(self.outcome_match))
+        object.__setattr__(self, "external_override", _clamp(self.external_override))
+
+
+@dataclass(frozen=True)
+class OwnershipAttribution:
+    """Attribution that a state, action, or representation is mine."""
+
+    confidence: float = 0.0
+    continuity: float = 0.0
+    source_alignment: float = 0.0
+    alienation: float = 0.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "confidence", _clamp(self.confidence))
+        object.__setattr__(self, "continuity", _clamp(self.continuity))
+        object.__setattr__(self, "source_alignment", _clamp(self.source_alignment))
+        object.__setattr__(self, "alienation", _clamp(self.alienation))
+
+
+@dataclass(frozen=True)
+class BoundaryState:
+    """Subject/world boundary estimate."""
+
+    self_world_separation: float = 1.0
+    tool_incorporation: float = 0.0
+    social_permeability: float = 0.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "self_world_separation", _clamp(self.self_world_separation))
+        object.__setattr__(self, "tool_incorporation", _clamp(self.tool_incorporation))
+        object.__setattr__(self, "social_permeability", _clamp(self.social_permeability))
+
+
+@dataclass(frozen=True)
+class PerspectiveState:
+    """The agent's perspective and temporal continuity marker."""
+
+    vantage: str = "first_person"
+    temporal_continuity: float = 1.0
+    embodied_anchor: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "temporal_continuity", _clamp(self.temporal_continuity))
+
+
+@dataclass(frozen=True)
+class SelfModel:
+    """A compact phenomenal self-model snapshot."""
+
+    subject_id: str
+    phenomenal: PhenomenalState = field(default_factory=PhenomenalState)
+    agency: AgencyAttribution = field(default_factory=AgencyAttribution)
+    ownership: OwnershipAttribution = field(default_factory=OwnershipAttribution)
+    boundary: BoundaryState = field(default_factory=BoundaryState)
+    perspective: PerspectiveState = field(default_factory=PerspectiveState)
+    revision: int = 0
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "metadata", _frozen_metadata(self.metadata))
+
+    def evolved(self, **changes: Any) -> SelfModel:
+        """Return a successor self-model with ``revision`` incremented."""
+        return replace(self, revision=self.revision + 1, **changes)
+
+
+def _clamp(value: float, lower: float = 0.0, upper: float = 1.0) -> float:
+    return min(upper, max(lower, float(value)))

autonoesis/operators.py

@@ -0,0 +1,161 @@
+"""Pure operators over Autonoesis records."""
+
+from __future__ import annotations
+
+from autonoesis.models import (
+    AgencyAttribution,
+    BoundaryState,
+    OwnershipAttribution,
+    PerspectiveState,
+    PhenomenalState,
+    SelfModel,
+    TransparencyLevel,
+    _clamp,
+)
+
+
+def assess_agency(
+    *,
+    intention_strength: float,
+    outcome_match: float,
+    external_override: float = 0.0,
+) -> AgencyAttribution:
+    """Estimate agency from intention, outcome fit, and override pressure."""
+    intention_strength = _clamp(intention_strength)
+    outcome_match = _clamp(outcome_match)
+    external_override = _clamp(external_override)
+    confidence = _clamp(
+        (0.45 * intention_strength)
+        + (0.45 * outcome_match)
+        - (0.35 * external_override)
+    )
+    return AgencyAttribution(
+        confidence=confidence,
+        intention_strength=intention_strength,
+        outcome_match=outcome_match,
+        external_override=external_override,
+    )
+
+
+def assess_ownership(
+    *,
+    continuity: float,
+    source_alignment: float,
+    alienation: float = 0.0,
+) -> OwnershipAttribution:
+    """Estimate mineness/ownership for a state or representation."""
+    continuity = _clamp(continuity)
+    source_alignment = _clamp(source_alignment)
+    alienation = _clamp(alienation)
+    confidence = _clamp((0.5 * continuity) + (0.4 * source_alignment) - (0.45 * alienation))
+    return OwnershipAttribution(
+        confidence=confidence,
+        continuity=continuity,
+        source_alignment=source_alignment,
+        alienation=alienation,
+    )
+
+
+def boundary_integrity(boundary: BoundaryState) -> float:
+    """Return a compact integrity score for the subject/world boundary."""
+    return _clamp(
+        (0.65 * boundary.self_world_separation)
+        + (0.2 * (1.0 - boundary.social_permeability))
+        + (0.15 * (1.0 - boundary.tool_incorporation))
+    )
+
+
+def transparency_audit(state: PhenomenalState) -> TransparencyLevel:
+    """Classify transparency from salience/arousal balance.
+
+    Highly salient, highly aroused states tend to be less available for calm
+    inspection, so this conservative default marks them as more opaque.
+    """
+    load = (state.salience + state.arousal) / 2.0
+    if load >= 0.75:
+        return TransparencyLevel.OPAQUE
+    if load >= 0.35:
+        return TransparencyLevel.PARTLY_OPAQUE
+    return TransparencyLevel.TRANSPARENT
+
+
+def update_precision(
+    prior: float,
+    observation_match: float,
+    learning_rate: float = 0.2,
+) -> float:
+    """Return a precision/confidence update under an observation.
+
+    Pure formula::
+
+        clamp(prior + learning_rate * (observation_match - prior))
+
+    All inputs are clamped to ``[0.0, 1.0]`` before use. ``learning_rate == 0``
+    returns the prior unchanged; ``learning_rate == 1`` returns
+    ``observation_match`` unchanged.
+    """
+    prior = _clamp(prior)
+    observation_match = _clamp(observation_match)
+    learning_rate = _clamp(learning_rate)
+    return _clamp(prior + learning_rate * (observation_match - prior))
+
+
+def update_attribution_from_observation(
+    attr: AgencyAttribution,
+    observation_match: float,
+    learning_rate: float = 0.2,
+) -> AgencyAttribution:
+    """Return a successor ``AgencyAttribution`` with updated confidence."""
+    return AgencyAttribution(
+        confidence=update_precision(attr.confidence, observation_match, learning_rate),
+        intention_strength=attr.intention_strength,
+        outcome_match=attr.outcome_match,
+        external_override=attr.external_override,
+    )
+
+
+def update_ownership_from_observation(
+    attr: OwnershipAttribution,
+    observation_match: float,
+    learning_rate: float = 0.2,
+) -> OwnershipAttribution:
+    """Return a successor ``OwnershipAttribution`` with updated confidence."""
+    return OwnershipAttribution(
+        confidence=update_precision(attr.confidence, observation_match, learning_rate),
+        continuity=attr.continuity,
+        source_alignment=attr.source_alignment,
+        alienation=attr.alienation,
+    )
+
+
+def surprise_to_observation_match(surprise_value: float) -> float:
+    """Default mapping from ``surprise`` to ``observation_match``."""
+    return 1.0 - _clamp(surprise_value)
+
+
+def update_self_model(
+    model: SelfModel,
+    phenomenal: PhenomenalState,
+    *,
+    agency: AgencyAttribution | None = None,
+    ownership: OwnershipAttribution | None = None,
+    boundary: BoundaryState | None = None,
+    perspective: PerspectiveState | None = None,
+) -> SelfModel:
+    """Return a successor self-model with updated phenomenal and attribution state."""
+    if phenomenal.transparency is TransparencyLevel.PARTLY_OPAQUE:
+        phenomenal = PhenomenalState(
+            salience=phenomenal.salience,
+            valence=phenomenal.valence,
+            arousal=phenomenal.arousal,
+            perspective=phenomenal.perspective,
+            transparency=transparency_audit(phenomenal),
+            metadata=phenomenal.metadata,
+        )
+    return model.evolved(
+        phenomenal=phenomenal,
+        agency=agency or model.agency,
+        ownership=ownership or model.ownership,
+        boundary=boundary or model.boundary,
+        perspective=perspective or model.perspective,
+    )

autonoesis/store.py

@@ -0,0 +1,64 @@
+"""Adapter seam for journaling ``SelfModel`` snapshots.
+
+Hosts may implement ``SelfModelStore`` against any backend (file, database,
+queue, in-memory). The kernel never depends on a concrete implementation.
+``InMemorySelfModelStore`` is shipped as a stdlib-only reference adapter
+suitable for tests, prototypes, and host-driven aggregation.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from autonoesis.models import SelfModel
+
+
+@runtime_checkable
+class SelfModelStore(Protocol):
+    """Structural adapter contract for journaling ``SelfModel`` snapshots."""
+
+    def save(self, snapshot: SelfModel) -> None:
+        """Persist a snapshot.
+
+        Implementations must raise ``ValueError`` when ``snapshot.revision``
+        is less than or equal to the most recent stored revision for the
+        same subject.
+        """
+        ...
+
+    def load_latest(self, subject_id: str) -> SelfModel | None:
+        """Return the highest-revision snapshot for ``subject_id``, or ``None``."""
+        ...
+
+    def load_history(self, subject_id: str) -> tuple[SelfModel, ...]:
+        """Return all snapshots for ``subject_id``, oldest first, newest last."""
+        ...
+
+
+class InMemorySelfModelStore:
+    """Reference ``SelfModelStore`` using an in-memory dict.
+
+    Stdlib only. No thread-safety guarantees in v0.2.
+    """
+
+    def __init__(self) -> None:
+        self._by_subject: dict[str, list[SelfModel]] = {}
+
+    def save(self, snapshot: SelfModel) -> None:
+        history = self._by_subject.setdefault(snapshot.subject_id, [])
+        if history and snapshot.revision <= history[-1].revision:
+            raise ValueError(
+                f"snapshot revision {snapshot.revision} must exceed "
+                f"current tail revision {history[-1].revision} for subject "
+                f"{snapshot.subject_id!r}"
+            )
+        history.append(snapshot)
+
+    def load_latest(self, subject_id: str) -> SelfModel | None:
+        history = self._by_subject.get(subject_id)
+        if not history:
+            return None
+        return history[-1]
+
+    def load_history(self, subject_id: str) -> tuple[SelfModel, ...]:
+        return tuple(self._by_subject.get(subject_id, ()))

autonoesis-0.2.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: autonoesis
+Version: 0.2.0
+Summary: A self-modeling and phenomenology kernel for cognitive agents.
+Project-URL: Homepage, https://github.com/bionicbutterfly13/autonoesis
+Project-URL: Repository, https://github.com/bionicbutterfly13/autonoesis
+Project-URL: Issues, https://github.com/bionicbutterfly13/autonoesis/issues
+Author: Bionic Butterfly
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agency,ai-agents,cognitive-architecture,metacognition,phenomenology,self-modeling
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Autonoesis
+
+A self-modeling and phenomenology kernel for cognitive agents.
+
+Autonoesis provides small, typed primitives for representing and updating an
+agent's model of itself as a subject situated in a world. It is designed to be
+embedded inside larger cognitive architectures without bringing a database, web
+framework, agent runtime, or storage backend.
+
+## What It Owns
+
+- Phenomenal state records
+- Self-model state records
+- Agency and ownership attribution
+- First-person perspective state
+- Boundary and mineness checks
+- Transparency / opacity markers
+- Pure self-model update operations
+
+## What It Does Not Own
+
+- Memory storage
+- Agent orchestration
+- LLM prompting infrastructure
+- Active inference policy selection
+- Safety policy systems
+- Product runtime surfaces
+
+## Install
+
+```bash
+pip install autonoesis
+```
+
+## Minimal Example
+
+```python
+from autonoesis import PhenomenalState, SelfModel, assess_agency, update_self_model
+
+state = PhenomenalState(
+    salience=0.8,
+    valence=0.2,
+    arousal=0.4,
+    perspective="first_person",
+)
+
+model = SelfModel(subject_id="agent")
+agency = assess_agency(intention_strength=0.9, outcome_match=0.7, external_override=0.0)
+updated = update_self_model(model, state, agency=agency)
+
+assert updated.agency.confidence > 0.0
+```
+
+## Design Rule
+
+Autonoesis is a kernel. It should stay pure, typed, dependency-light, and easy to
+test. Host systems should attach storage, orchestration, LLM calls, and runtime
+policy through adapters.
+
+## Project Docs
+
+- [Product requirements](docs/prd.md)
+- [v0.1 self-model kernel spec](docs/specs/v0.1-self-model-kernel.md)
+- [Testing and TDD](docs/testing.md)

autonoesis-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+autonoesis/__init__.py,sha256=acaTPr1-4mRvkJ6BbwOcz729t4wSXMzjfhrLDuJ_1PI,1325
+autonoesis/episodic.py,sha256=pboRkdXpvtQGE9HiHxVJoqEwS6TZbZrrUMd5LYVEtys,4104
+autonoesis/models.py,sha256=cz3MVcSsE-exOi_513p5cljzhjAbazl1Z7L_LlojU6g,4479
+autonoesis/operators.py,sha256=eiu0hbOssGk6b11qu4c68DwgTDiNa0xGWqFYm8utNrQ,5230
+autonoesis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+autonoesis/store.py,sha256=NgGToGtyUIVdbR4tm-bY_jpWWzR-htAade4sCcNZ3Pc,2227
+autonoesis-0.2.0.dist-info/METADATA,sha256=VVv0HMugxgrWrxI3lUz2nZSbu8ZkXcpwqzTJ_19ymgE,2549
+autonoesis-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+autonoesis-0.2.0.dist-info/licenses/LICENSE,sha256=yvXLyy21nFLrzQkxoGzNOZ5fJPsk-6HlH2ISir6wz2s,1073
+autonoesis-0.2.0.dist-info/RECORD,,

autonoesis-0.2.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

autonoesis-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bionic Butterfly
+
+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.