conscious-agent 1.0.0__tar.gz

conscious_agent-1.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: conscious-agent
+Version: 1.0.0
+Summary: Self-referential structure-learning system — agents that learn by inhabiting worlds
+Author: Benjamin
+License: MIT
+Project-URL: Homepage, https://github.com/anomalyco/conscious-agents
+Project-URL: Repository, https://github.com/anomalyco/conscious-agents
+Keywords: consciousness,emergent-language,self-reference,structure-learning,hoffman,conscious-realism
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# conscious-agent
+
+**A computational implementation of Hoffman's Conscious Realism.**
+
+Build self-referential agents that learn by *inhabiting* worlds — constructing internal models of both their environment and themselves.
+
+```python
+from conscious_agent import ConsciousAgent
+from conscious_agent.worlds import CoinTossWorld
+
+world = CoinTossWorld(n_coins=4)
+agent = ConsciousAgent(world=world, agent_id="my_agent")
+outputs = agent.run(n_steps=1000)
+print(f'"I" locked: {agent.is_i_locked}')
+```
+
+## Installation
+
+```bash
+pip install numpy scipy       # core dependencies
+pip install conscious-agent   # once published
+```
+
+Or from source:
+```bash
+cd hoffman-agents-python
+pip install -e .
+```
+
+## Quick Start
+
+### Single agent in a coin-toss world
+
+```python
+from conscious_agent import ConsciousAgent
+from conscious_agent.worlds import CoinTossWorld
+
+world = CoinTossWorld(n_coins=3)
+agent = ConsciousAgent(agent_id="coin_agent", world=world)
+
+for _ in range(500):
+    output = agent.step()
+    if output.i_locked:
+        print(f"I locked at step {output.step}")
+        break
+```
+
+### Custom Markov world
+
+```python
+from conscious_agent import ConsciousAgent, WorldBuilder
+import numpy as np
+
+data = np.random.rand(500, 3)
+world = (WorldBuilder()
+    .add_feature("temp", normalization="minmax", n_bins=4)
+    .add_feature("humidity", normalization="minmax", n_bins=4)
+    .add_feature("pressure", normalization="minmax", n_bins=4)
+    .build(data))
+
+agent = ConsciousAgent(agent_id="weather_agent", world=world)
+outputs = agent.run(n_steps=1000)
+```
+
+### Combine two agents
+
+```python
+from conscious_agent import combine
+
+a = ConsciousAgent(agent_id="agent_a", world=world)
+b = ConsciousAgent(agent_id="agent_b", world=world)
+a.run(500)
+b.run(500)
+
+combined = combine(a, b)
+print(f"Combined agent: {combined.agent_id}, level: {combined.cycle_level}")
+```
+
+### Multi-agent network
+
+```python
+from conscious_agent import AgentNetwork
+
+network = AgentNetwork(n_agents=10, seed=42)
+states = network.run(n_generations=100)
+print(f"Avg prediction error: {network.avg_prediction_error():.3f}")
+```
+
+### Save and load
+
+```python
+from conscious_agent.io import save_agent, load_agent, clone_agent
+
+path = save_agent(agent, "./souls")
+loaded = load_agent(path)
+
+cloned = clone_agent(agent, "experiment_clone")
+```
+
+## Public API
+
+```python
+# Core classes
+from conscious_agent import ConsciousAgent, World, WorldBuilder
+from conscious_agent import SimpleWorld, ExperienceSpace
+
+# World factories
+from conscious_agent.worlds import CoinTossWorld, build_world_from_dataframe
+
+# IO
+from conscious_agent.io import save_agent, load_agent, clone_agent, load_latest
+
+# Multi-agent
+from conscious_agent import AgentNetwork, combine
+
+# Core components (for advanced use)
+from conscious_agent import (
+    TraceBuffer, TraceEvent, ExperienceTrie, MetaTrie,
+    SelfTokenState, ExperienceLexicon, strange_loop_score,
+)
+```
+
+## How It Works
+
+Every ConsciousAgent has an **experience space** — four interconnected structures:
+
+1. **TraceBuffer** — short-term memory: the last N state transitions
+2. **ExperienceTrie** — long-term world model: compressed prefix tree over observed state sequences
+3. **MetaTrie** — self-model: a second trie over the agent's own trace buffer snapshots (thinking about thinking)
+4. **SelfTokenState ("I")** — identity: the dominant meta-state that forms a stable attractor
+
+The agent cycles through **perception** (observe world → update trie) → **meta-observation** (observe self → update meta-trie) → **decision** (generate output tokens via ergodic Markov chain).
+
+When the meta-trie's stationary distribution converges on a single meta-state, the "I" locks — the agent has formed a stable identity.
+
+## Requirements
+
+- Python 3.10+
+- numpy >= 1.24
+- scipy >= 1.10
+
+## License
+
+MIT

conscious_agent-1.0.0/README.md

@@ -0,0 +1,144 @@
+# conscious-agent
+
+**A computational implementation of Hoffman's Conscious Realism.**
+
+Build self-referential agents that learn by *inhabiting* worlds — constructing internal models of both their environment and themselves.
+
+```python
+from conscious_agent import ConsciousAgent
+from conscious_agent.worlds import CoinTossWorld
+
+world = CoinTossWorld(n_coins=4)
+agent = ConsciousAgent(world=world, agent_id="my_agent")
+outputs = agent.run(n_steps=1000)
+print(f'"I" locked: {agent.is_i_locked}')
+```
+
+## Installation
+
+```bash
+pip install numpy scipy       # core dependencies
+pip install conscious-agent   # once published
+```
+
+Or from source:
+```bash
+cd hoffman-agents-python
+pip install -e .
+```
+
+## Quick Start
+
+### Single agent in a coin-toss world
+
+```python
+from conscious_agent import ConsciousAgent
+from conscious_agent.worlds import CoinTossWorld
+
+world = CoinTossWorld(n_coins=3)
+agent = ConsciousAgent(agent_id="coin_agent", world=world)
+
+for _ in range(500):
+    output = agent.step()
+    if output.i_locked:
+        print(f"I locked at step {output.step}")
+        break
+```
+
+### Custom Markov world
+
+```python
+from conscious_agent import ConsciousAgent, WorldBuilder
+import numpy as np
+
+data = np.random.rand(500, 3)
+world = (WorldBuilder()
+    .add_feature("temp", normalization="minmax", n_bins=4)
+    .add_feature("humidity", normalization="minmax", n_bins=4)
+    .add_feature("pressure", normalization="minmax", n_bins=4)
+    .build(data))
+
+agent = ConsciousAgent(agent_id="weather_agent", world=world)
+outputs = agent.run(n_steps=1000)
+```
+
+### Combine two agents
+
+```python
+from conscious_agent import combine
+
+a = ConsciousAgent(agent_id="agent_a", world=world)
+b = ConsciousAgent(agent_id="agent_b", world=world)
+a.run(500)
+b.run(500)
+
+combined = combine(a, b)
+print(f"Combined agent: {combined.agent_id}, level: {combined.cycle_level}")
+```
+
+### Multi-agent network
+
+```python
+from conscious_agent import AgentNetwork
+
+network = AgentNetwork(n_agents=10, seed=42)
+states = network.run(n_generations=100)
+print(f"Avg prediction error: {network.avg_prediction_error():.3f}")
+```
+
+### Save and load
+
+```python
+from conscious_agent.io import save_agent, load_agent, clone_agent
+
+path = save_agent(agent, "./souls")
+loaded = load_agent(path)
+
+cloned = clone_agent(agent, "experiment_clone")
+```
+
+## Public API
+
+```python
+# Core classes
+from conscious_agent import ConsciousAgent, World, WorldBuilder
+from conscious_agent import SimpleWorld, ExperienceSpace
+
+# World factories
+from conscious_agent.worlds import CoinTossWorld, build_world_from_dataframe
+
+# IO
+from conscious_agent.io import save_agent, load_agent, clone_agent, load_latest
+
+# Multi-agent
+from conscious_agent import AgentNetwork, combine
+
+# Core components (for advanced use)
+from conscious_agent import (
+    TraceBuffer, TraceEvent, ExperienceTrie, MetaTrie,
+    SelfTokenState, ExperienceLexicon, strange_loop_score,
+)
+```
+
+## How It Works
+
+Every ConsciousAgent has an **experience space** — four interconnected structures:
+
+1. **TraceBuffer** — short-term memory: the last N state transitions
+2. **ExperienceTrie** — long-term world model: compressed prefix tree over observed state sequences
+3. **MetaTrie** — self-model: a second trie over the agent's own trace buffer snapshots (thinking about thinking)
+4. **SelfTokenState ("I")** — identity: the dominant meta-state that forms a stable attractor
+
+The agent cycles through **perception** (observe world → update trie) → **meta-observation** (observe self → update meta-trie) → **decision** (generate output tokens via ergodic Markov chain).
+
+When the meta-trie's stationary distribution converges on a single meta-state, the "I" locks — the agent has formed a stable identity.
+
+## Requirements
+
+- Python 3.10+
+- numpy >= 1.24
+- scipy >= 1.10
+
+## License
+
+MIT

conscious_agent-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "conscious-agent"
+dynamic = ["version"]
+description = "Self-referential structure-learning system — agents that learn by inhabiting worlds"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Benjamin"},
+]
+keywords = [
+    "consciousness",
+    "emergent-language",
+    "self-reference",
+    "structure-learning",
+    "hoffman",
+    "conscious-realism",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=7"]
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["conscious_agent*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "conscious_agent.__version__"}
+
+[project.urls]
+Homepage = "https://github.com/anomalyco/conscious-agents"
+Repository = "https://github.com/anomalyco/conscious-agents"

conscious_agent-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

conscious_agent-1.0.0/src/conscious_agent/__init__.py

@@ -0,0 +1,73 @@
+"""conscious-agent — A computational implementation of Conscious Realism.
+
+One import. One world. The agent does the rest.
+
+Quick start:
+    from conscious_agent import ConsciousAgent
+    from conscious_agent.worlds import CoinTossWorld
+
+    world = CoinTossWorld(n_coins=4)
+    agent = ConsciousAgent(world=world, agent_id="my_agent")
+
+    outputs = agent.run(n_steps=1000)
+    print(f'"I" locked: {agent.experience.self_token.locked}')
+"""
+
+__version__ = "1.0.0"
+
+from .agent import ConsciousAgent, SimpleWorld, WorldState, StepOutput, ExperienceSpace
+from .world import World, WorldBuilder, CoinTossWorld, build_world_from_dataframe
+from .network import AgentNetwork
+from .combination import combine, trivial_agent, experience_space_distance
+from .io import serialize, deserialize, clone, clone_agent, fingerprint, save_agent, load_agent, load_latest
+from .core import (
+    TraceBuffer,
+    TraceEvent,
+    ExperienceTrie,
+    MetaTrie,
+    SelfTokenState,
+    ExperienceLexicon,
+    LexiconEntry,
+    strange_loop_score,
+    compute_self_reference_score,
+)
+from .meaning import SharedMeaningTracker
+
+# Alias for CA_RUNTIME_API.md compatibility
+import sys as _sys
+_sys.modules['conscious_agent.worlds'] = _sys.modules['conscious_agent.world']
+_sys.modules['conscious_agent.io'] = _sys.modules['conscious_agent.io']
+
+__all__ = [
+    "ConsciousAgent",
+    "SimpleWorld",
+    "WorldState",
+    "StepOutput",
+    "ExperienceSpace",
+    "World",
+    "WorldBuilder",
+    "CoinTossWorld",
+    "build_world_from_dataframe",
+    "AgentNetwork",
+    "combine",
+    "trivial_agent",
+    "experience_space_distance",
+    "serialize",
+    "deserialize",
+    "clone",
+    "clone_agent",
+    "fingerprint",
+    "save_agent",
+    "load_agent",
+    "load_latest",
+    "TraceBuffer",
+    "TraceEvent",
+    "ExperienceTrie",
+    "MetaTrie",
+    "SelfTokenState",
+    "ExperienceLexicon",
+    "LexiconEntry",
+    "strange_loop_score",
+    "compute_self_reference_score",
+    "SharedMeaningTracker",
+]

conscious_agent-1.0.0/src/conscious_agent/agent/__init__.py

@@ -0,0 +1,15 @@
+from .conscious_agent import ConsciousAgent, StepOutput
+from .simple_world import SimpleWorld
+from .world_state import WorldState, EnvironmentState, sequence_to_state_id
+from .experience_space import ExperienceSpace, MemorySpace
+
+__all__ = [
+    "ConsciousAgent",
+    "StepOutput",
+    "SimpleWorld",
+    "WorldState",
+    "EnvironmentState",
+    "sequence_to_state_id",
+    "ExperienceSpace",
+    "MemorySpace",
+]

conscious_agent-1.0.0/src/conscious_agent/agent/conscious_agent.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from ..core import (
+    compute_self_reference_score as _compute_self_reference_score,
+    ExperienceTrie,
+    MetaTrie,
+    SelfTokenState,
+    TraceBuffer,
+)
+from .world_state import WorldState
+from .experience_space import ExperienceSpace
+from .perceptual_map import perceive
+from .decision_map import decide, OutputState
+
+
+@dataclass
+class StepOutput:
+    step: int
+    generation: int
+    state: int
+    state_label: str
+    prediction_error: float
+    sequence: list[str]
+    sequence_str: str
+    loop_depth: float
+    i_locked: bool
+    i_stability: float
+    interrupt: Any = None
+
+
+@dataclass
+class ConsciousAgent:
+    agent_id: str
+    experience: ExperienceSpace = field(default_factory=ExperienceSpace)
+    world: Any = None
+    generation: int = 0
+    step_count: int = 0
+    meta_observation_interval: int = 20
+    constituent_ids: frozenset[str] = field(default_factory=frozenset)
+    leaf_constituent_ids: frozenset[str] = field(default_factory=frozenset)
+    cycle_level: int = 0
+    expression_temp: float = 1.0
+    p_stable: float = 0.80
+    p_lexicon: float = 0.10
+    p_explore: float = 0.05
+    _combined: bool = False
+    _ergodic_state: OutputState = "idle"
+    _last_output: list[str] = field(default_factory=lambda: ["wait"])
+
+    @staticmethod
+    def from_config(agent_id: str, config: dict) -> ConsciousAgent:
+        agent_cfg = config.get("agent", {})
+        st_cfg = agent_cfg.get("self_token", {})
+        st = SelfTokenState(
+            lock_threshold=st_cfg.get("lock_threshold", 0.25),
+            lock_consecutive_required=st_cfg.get("lock_consecutive_required", 3),
+        )
+        exp = ExperienceSpace(self_token=st)
+        return ConsciousAgent(
+            agent_id=agent_id,
+            experience=exp,
+            meta_observation_interval=agent_cfg.get("meta_observation_interval", 20),
+            expression_temp=agent_cfg.get("expression_temp", 1.0),
+        )
+
+    def step(self, world: WorldState | None = None) -> StepOutput:
+        if world is not None:
+            pass
+
+        if world is None and self.world is not None:
+            if hasattr(self.world, 'step'):
+                world = self.world.step()
+
+        if world is not None:
+            self.experience = perceive(
+                world,
+                self.experience,
+                step=self.step_count,
+                meta_observation_interval=self.meta_observation_interval,
+            )
+
+        output, self._ergodic_state = decide(
+            self.experience,
+            p_stable=self.p_stable,
+            p_lexicon=self.p_lexicon,
+            p_explore=self.p_explore,
+            ergodic_state=self._ergodic_state,
+        )
+
+        for token in output:
+            if self.experience.meta_trie.last_meta_state is not None:
+                self.experience.meta_trie.record_token(
+                    self.experience.meta_trie.last_meta_state, token
+                )
+
+        self._last_output = output
+        self.step_count += 1
+        if self.step_count > 0 and self.step_count % self.meta_observation_interval == 0:
+            self.generation += 1
+
+        return StepOutput(
+            step=self.step_count,
+            generation=self.generation,
+            state=self.experience.last_world_state_id or -1,
+            state_label=str(self.experience.last_world_state_id or "?"),
+            prediction_error=self.experience.trace_buffer.prediction_error_mean(window=5),
+            sequence=list(output),
+            sequence_str=" ".join(output),
+            loop_depth=float(_compute_self_reference_score(output)),
+            i_locked=self.experience.self_token.locked,
+            i_stability=self.experience.self_token.stationary_variance(),
+        )
+
+    def run(self, n_steps: int) -> list[StepOutput]:
+        outputs = []
+        for _ in range(n_steps):
+            outputs.append(self.step())
+        return outputs
+
+    def observe(self, output_sequence: list[str], source_id: str) -> StepOutput:
+        return self.step(WorldState.from_sequence(source_id, output_sequence))
+
+    def get_output(self) -> list[str]:
+        return list(self._last_output)
+
+    def set_world(self, world: Any) -> None:
+        self.world = world
+
+    @property
+    def loop_score(self) -> float:
+        return float(_compute_self_reference_score(self._last_output))
+
+    @property
+    def mean_prediction_error(self) -> float:
+        return self.experience.trace_buffer.prediction_error_mean(window=100)
+
+    @property
+    def is_i_locked(self) -> bool:
+        return self.experience.self_token.locked
+
+    @property
+    def is_identity_stable(self) -> bool:
+        return self.experience.is_identity_stable
+
+    is_ripe = is_identity_stable
+
+    def clear(self) -> None:
+        self.experience.trace_buffer.clear()
+        self.experience.trie.clear()
+        self.experience.meta_trie.clear()
+        self.experience.lexicon.clear()
+        self.step_count = 0
+        self.generation = 0
+        self._last_output = ["wait"]
+
+
+ConsciousAgent.__init__.__doc__ = """Create a ConsciousAgent.
+
+Args:
+    agent_id: Unique identifier for this agent.
+    experience: The agent's internal experience space (trie, meta-trie, etc.)
+    world: Optional world object with a .step() method returning WorldState.
+    generation: Current generation counter.
+    step_count: Current step counter.
+    meta_observation_interval: Steps between meta-trie observations (default 20).
+    constituent_ids: IDs of agents that combined to create this agent.
+    leaf_constituent_ids: IDs of leaf agents below combined agents.
+    cycle_level: Depth in combination tree (0 = base agent).
+    expression_temp: Temperature controlling output style (1.0=poetic, 0.0=clinical).
+    p_stable: Probability of remaining in core output state.
+    p_lexicon: Probability of transitioning to lexicon output state.
+    p_explore: Probability of exploring random tokens.
+"""