autonoesis 0.2.0__tar.gz

autonoesis-0.2.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,23 @@
+---
+name: Bug
+about: Report incorrect kernel behavior
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Behavior
+
+What happened?
+
+## Expected
+
+What should have happened?
+
+## Reproduction
+
+Minimal code or test case.
+
+## Contract
+
+Which spec, record, or operator contract is violated?

autonoesis-0.2.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,27 @@
+---
+name: Feature
+about: Propose a kernel feature or public API addition
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Purpose
+
+What cognitive responsibility should this add or clarify?
+
+## Public Surface
+
+What records, operators, or protocols would change?
+
+## Spec Impact
+
+Which spec file needs to be added or updated?
+
+## Tests
+
+What tests should fail before implementation and pass after?
+
+## Non-Goals
+
+What should stay out of scope?

autonoesis-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+- 
+
+## Spec / Docs
+
+- [ ] Relevant spec updated or no spec impact
+- [ ] README/docs updated or no user-facing impact
+
+## Tests
+
+- [ ] `uv run pytest -q`
+- [ ] `uv run ruff check .`
+- [ ] `python -m compileall -q src tests`

autonoesis-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: uv sync --group dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Compile
+        run: python -m compileall -q src tests

autonoesis-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+dist/
+build/
+.coverage
+htmlcov/

autonoesis-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to Autonoesis are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Breaking changes are allowed before `1.0.0` and will always be called out
+explicitly under a `Breaking` heading.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [0.2.0] - 2026-05-11
+
+### Added
+
+- `SelfModelEpisode`: frozen, append-only sequence of `SelfModel` snapshots
+  with strict per-subject revision monotonicity.
+- `episode_summary`: read-only mapping over an episode's history (length,
+  mean salience, mean arousal, peak arousal, transparent fraction).
+- `predict_next`: v0.2 baseline predictor that returns the last snapshot.
+- `surprise`: clamped `[0, 1]` distance between two `SelfModel` snapshots
+  combining phenomenal and attribution components.
+- `update_precision`: pure precision/confidence update under observation,
+  exponential-moving-average flavor, clamped to `[0, 1]`.
+- `update_attribution_from_observation`: successor `AgencyAttribution`
+  with `confidence` revised via `update_precision`.
+- `update_ownership_from_observation`: successor `OwnershipAttribution`
+  with `confidence` revised via `update_precision`.
+- `surprise_to_observation_match`: default mapping from `surprise` output
+  to `observation_match` input.
+- `SelfModelStore`: `@runtime_checkable` Protocol describing the
+  journaling adapter contract (`save` / `load_latest` / `load_history`)
+  with strict per-subject revision monotonicity.
+- `InMemorySelfModelStore`: stdlib-only reference adapter used by the
+  test suite.
+
+## [0.1.0] - 2026-05-09
+
+### Added
+
+- Frozen records: `PhenomenalState`, `AgencyAttribution`, `OwnershipAttribution`,
+  `BoundaryState`, `PerspectiveState`, `SelfModel`.
+- Pure operators: `assess_agency`, `assess_ownership`, `boundary_integrity`,
+  `transparency_audit`, `update_self_model`.
+- `TransparencyLevel` string enum.
+- `update_self_model` accepts an optional `perspective` argument and threads
+  it into the successor `SelfModel`.

autonoesis-0.2.0/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.

autonoesis-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,64 @@
+# 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/docs/prd.md

@@ -0,0 +1,66 @@
+# Product Requirements: Autonoesis
+
+## Purpose
+
+Autonoesis is a self-modeling and phenomenology kernel for cognitive agents.
+It provides typed records and pure operators for representing an agent's model
+of itself as a subject situated in a world.
+
+The package exists so cognitive computing developers can reuse self-modeling
+primitives without adopting a full agent runtime, database, orchestration
+framework, or product stack.
+
+## Users
+
+- Developers building cognitive architectures and agent runtimes.
+- Researchers prototyping self-modeling, agency, ownership, and perspective
+  mechanisms.
+- Maintainers extracting reusable kernels from larger systems.
+
+## Problem
+
+Self-modeling concepts often get embedded directly inside host runtimes. That
+makes them hard to test, hard to reuse, and hard to distinguish from storage,
+prompting, policy, and orchestration code.
+
+Autonoesis separates the self-modeling kernel from the host substrate.
+
+## v0.1 Scope
+
+Autonoesis v0.1 provides:
+
+- Frozen records for phenomenal state, agency attribution, ownership
+  attribution, boundary state, perspective state, and self-model snapshots.
+- Pure operators for agency scoring, ownership scoring, boundary integrity,
+  transparency audit, and self-model successor updates.
+- A typed public API exported from `autonoesis`.
+- Unit tests for every public operator and core invariant.
+
+## Non-Goals
+
+Autonoesis v0.1 does not provide:
+
+- Memory persistence.
+- LLM prompting.
+- Agent orchestration.
+- Active inference policy selection.
+- Safety or governance policy.
+- FastAPI, CLI, database, queue, or product runtime surfaces.
+
+## Public API Promise
+
+The core package should remain dependency-light and host-neutral. Public records
+and operators should be small enough to embed inside other systems without
+pulling in storage or runtime assumptions.
+
+Breaking changes before `1.0` are allowed, but every change to public records or
+operators must be captured in a spec update and covered by tests.
+
+## Success Criteria
+
+- A developer can install the package and construct/update a self-model without
+  configuring any external service.
+- Public records are immutable by default.
+- Public operators are deterministic for the same inputs.
+- Every public operator has direct tests.
+- The package imports on supported Python versions in CI.

autonoesis-0.2.0/docs/specs/v0.1-self-model-kernel.md

@@ -0,0 +1,164 @@
+# Spec: v0.1 Self-Model Kernel
+
+## Status
+
+Draft for v0.1.
+
+## Goal
+
+Define the first stable Autonoesis kernel surface: self-model records and pure
+operators for agency, ownership, boundary integrity, transparency, and successor
+state updates.
+
+## Public Records
+
+### `PhenomenalState`
+
+Represents a compact phenomenal field summary.
+
+Required invariants:
+
+- `salience` is clamped to `[0.0, 1.0]`.
+- `valence` is clamped to `[-1.0, 1.0]`.
+- `arousal` is clamped to `[0.0, 1.0]`.
+- `metadata` is copied into a read-only mapping.
+- The record is frozen.
+
+### `AgencyAttribution`
+
+Represents confidence that an event or action is controlled by the subject.
+
+Required invariants:
+
+- `confidence`, `intention_strength`, `outcome_match`, and `external_override`
+  are clamped to `[0.0, 1.0]`.
+- The record is frozen.
+
+### `OwnershipAttribution`
+
+Represents confidence that a state, action, or representation is "mine."
+
+Required invariants:
+
+- `confidence`, `continuity`, `source_alignment`, and `alienation` are clamped
+  to `[0.0, 1.0]`.
+- The record is frozen.
+
+### `BoundaryState`
+
+Represents subject/world boundary estimates.
+
+Required invariants:
+
+- `self_world_separation`, `tool_incorporation`, and `social_permeability` are
+  clamped to `[0.0, 1.0]`.
+- The record is frozen.
+
+### `PerspectiveState`
+
+Represents vantage and temporal continuity.
+
+Required invariants:
+
+- `temporal_continuity` is clamped to `[0.0, 1.0]`.
+- The record is frozen.
+
+### `SelfModel`
+
+Represents a compact phenomenal self-model snapshot.
+
+Required invariants:
+
+- The record is frozen.
+- `metadata` is copied into a read-only mapping.
+- `evolved(**changes)` returns a successor with `revision + 1`.
+- `evolved(**changes)` never mutates the source record.
+
+## Public Operators
+
+### `assess_agency(...)`
+
+Inputs:
+
+- `intention_strength`
+- `outcome_match`
+- `external_override`
+
+Behavior:
+
+- Returns `AgencyAttribution`.
+- Higher intention and outcome match increase confidence.
+- Higher external override decreases confidence.
+- Output values are clamped.
+- Same inputs produce the same output.
+
+### `assess_ownership(...)`
+
+Inputs:
+
+- `continuity`
+- `source_alignment`
+- `alienation`
+
+Behavior:
+
+- Returns `OwnershipAttribution`.
+- Higher continuity and source alignment increase confidence.
+- Higher alienation decreases confidence.
+- Output values are clamped.
+- Same inputs produce the same output.
+
+### `boundary_integrity(boundary)`
+
+Behavior:
+
+- Returns a compact `[0.0, 1.0]` boundary integrity score.
+- Higher self/world separation increases integrity.
+- Higher social permeability and tool incorporation reduce integrity in the
+  conservative default formula.
+- Same inputs produce the same output.
+
+### `transparency_audit(state)`
+
+Behavior:
+
+- Returns `TransparencyLevel`.
+- High salience plus high arousal returns `OPAQUE`.
+- Moderate load returns `PARTLY_OPAQUE`.
+- Low load returns `TRANSPARENT`.
+- Same inputs produce the same output.
+
+### `update_self_model(...)`
+
+Behavior:
+
+- Returns a successor `SelfModel`.
+- Does not mutate the input `SelfModel`.
+- Increments `revision` by one.
+- Updates phenomenal state and any provided attribution, boundary, or
+  perspective records.
+- If phenomenal transparency is still `PARTLY_OPAQUE`, applies
+  `transparency_audit()`.
+
+## Acceptance Tests
+
+The v0.1 test suite must prove:
+
+- Records are frozen.
+- Metadata cannot be mutated through the source mapping.
+- Agency confidence decreases under external override.
+- Ownership confidence decreases under alienation.
+- Boundary integrity responds to boundary components.
+- Transparency audit marks high-load states opaque.
+- Self-model updates return successors and increment revision.
+- Operators are deterministic for repeated calls with the same inputs.
+
+## Non-Goals
+
+This spec does not include:
+
+- Persistence adapters.
+- Prompt templates.
+- Agent loops.
+- Active inference policies.
+- Runtime configuration.

autonoesis-0.2.0/docs/specs/v0.2-active-inference.md

@@ -0,0 +1,103 @@
+# Spec: v0.2 Active-Inference Operators
+
+## Status
+
+Draft for v0.2.
+
+## Goal
+
+Provide pure, deterministic operators for revising attribution confidences
+under observation. The kernel does not pick policies, decide when to update,
+or represent free energy. It exposes a small, composable precision-update
+seam that hosts can drive however they like (including with the `surprise`
+operator from `v0.2-episodic-layer.md`).
+
+The active-inference layer is additive. v0.1 records and operators are not
+changed.
+
+## Public Operators
+
+### `update_precision(prior, observation_match, learning_rate=0.2)`
+
+Inputs:
+
+- `prior`: prior precision/confidence in `[0.0, 1.0]`.
+- `observation_match`: how well the observation supports the prior, in
+  `[0.0, 1.0]`. `1.0` means the observation fully confirms the prior;
+  `0.0` means it fully contradicts.
+- `learning_rate`: weight on the observation, in `[0.0, 1.0]`.
+  Default `0.2`.
+
+Behavior:
+
+- Returns a `float` in `[0.0, 1.0]`.
+- Pure formula:
+  `clamp(prior + learning_rate * (observation_match - prior))`.
+- All inputs are clamped before use.
+- `learning_rate == 0.0` returns the (clamped) prior unchanged.
+- `learning_rate == 1.0` returns the (clamped) observation_match.
+- For fixed `prior` and `learning_rate`, the result is monotonically
+  non-decreasing in `observation_match`.
+- Same inputs produce the same output.
+
+### `update_attribution_from_observation(attr, observation_match, learning_rate=0.2)`
+
+Inputs:
+
+- `attr`: an `AgencyAttribution`.
+- `observation_match` and `learning_rate` as above.
+
+Behavior:
+
+- Returns a successor `AgencyAttribution`.
+- `confidence` is updated via `update_precision`.
+- `intention_strength`, `outcome_match`, and `external_override` are
+  preserved unchanged on the successor.
+- Does not mutate the input record.
+- Same inputs produce the same output.
+
+### `update_ownership_from_observation(attr, observation_match, learning_rate=0.2)`
+
+Symmetric to `update_attribution_from_observation` but for
+`OwnershipAttribution`. `continuity`, `source_alignment`, and `alienation`
+are preserved unchanged on the successor; only `confidence` is updated.
+
+### `surprise_to_observation_match(surprise_value)`
+
+Inputs:
+
+- `surprise_value`: a `float`. Clamped to `[0.0, 1.0]`.
+
+Behavior:
+
+- Returns `1.0 - clamp(surprise_value)`.
+- Documented as a default mapping from `surprise` (see
+  `v0.2-episodic-layer.md`) to `observation_match`. Hosts may use any other
+  mapping.
+
+## Acceptance Tests
+
+The v0.2 active-inference test suite must prove:
+
+- `update_precision` is monotonic non-decreasing in `observation_match`.
+- `update_precision` returns the prior when `learning_rate == 0`.
+- `update_precision` returns `observation_match` when `learning_rate == 1`.
+- `update_precision` clamps under negative or above-1 inputs.
+- `update_attribution_from_observation` returns a new `AgencyAttribution`,
+  leaves the source unchanged, and updates only `confidence`.
+- `update_ownership_from_observation` behaves analogously for
+  `OwnershipAttribution`.
+- `surprise_to_observation_match` inverts the unit interval and clamps
+  out-of-range inputs.
+- All four operators are deterministic for repeated calls with the same
+  inputs.
+
+## Non-Goals
+
+This spec does not include:
+
+- Free-energy minimization or KL-divergence policies.
+- Choice of when to update (scheduling, eligibility, gating).
+- Multi-modal precision priors over more than one attribution at a time.
+- Persistence of updated attributions (covered by
+  `v0.2-persistence-protocol.md`).