plasticity-agent 0.2.0__py3-none-any.whl

plasticity_agent/__init__.py

@@ -0,0 +1,139 @@
+"""Plasticity Agent Runtime.
+
+Neuroplastic memory, self-healing, and critical reasoning for AI agents.
+
+A local-first, framework-agnostic runtime that gives agents an evolving memory,
+sleep-like consolidation, reflection, advisory self-healing, a critic-driven
+reasoning market, a skill library, and thermodynamic-style reliability reporting.
+
+Scientific framings (complementary learning systems, synaptic homeostasis,
+Reflexion, Self-Refine, Voyager-style skills, auction theory, the free-energy
+principle) are used as *software metaphors and design principles* — not claims
+of biological equivalence or consciousness.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from plasticity_agent.core.agent import PlasticAgent
+from plasticity_agent.core.config import PlasticityConfig
+from plasticity_agent.core.events import TraceEvent
+from plasticity_agent.core.runtime import RunResult, Runtime
+from plasticity_agent.core.trace import Tracer
+from plasticity_agent.healing.detector import FailureDetector, detect_failures
+from plasticity_agent.healing.diagnosis import FailureDiagnosis, diagnose
+from plasticity_agent.healing.repair import RepairPlan, heal, plan_repair
+from plasticity_agent.healing.sandbox import RepairConsent, Sandbox, SandboxResult
+from plasticity_agent.learning.curriculum import Curriculum, CurriculumItem
+from plasticity_agent.learning.reward import normalize_reward, shape_reward
+from plasticity_agent.learning.skill_library import Skill, SkillLibrary
+from plasticity_agent.llm.client import LLMClient, coerce_llm
+from plasticity_agent.memory.consolidation import SleepReport
+from plasticity_agent.memory.contradiction import ContradictionChecker, detect_contradiction
+from plasticity_agent.memory.embeddings import (
+    EmbeddingBackend,
+    HashingEmbeddingBackend,
+    SentenceTransformerBackend,
+    get_embedder,
+)
+from plasticity_agent.memory.memory_os import (
+    MemoryOS,
+    compute_utility_score,
+    score_memory_quality,
+)
+from plasticity_agent.memory.salience import calculate_salience
+from plasticity_agent.memory.schemas import (
+    Memory,
+    MemoryQualityReport,
+    MemorySearchResult,
+)
+from plasticity_agent.memory.vector_index import VectorIndex
+from plasticity_agent.metrics.tracker import (
+    ImprovementReport,
+    ImprovementTracker,
+    MetricSnapshot,
+)
+from plasticity_agent.observability.otel import OTelExporter
+from plasticity_agent.reasoning.auction import AuctionResult, run_auction, score_proposal
+from plasticity_agent.reasoning.critic import Critic, Proposal
+from plasticity_agent.reasoning.critics import LLMCritic
+from plasticity_agent.reasoning.debate import Debate, DebateResult
+from plasticity_agent.reasoning.market import ReasoningMarket
+from plasticity_agent.reflection.lessons import Lesson, ReflectionInput
+from plasticity_agent.reflection.reflector import Reflector
+from plasticity_agent.reflection.self_refine import SelfRefine, SelfRefineResult
+from plasticity_agent.thermodynamics.energy_report import EnergyReport, build_energy_report
+
+__all__ = [
+    "__version__",
+    # core
+    "PlasticAgent",
+    "PlasticityConfig",
+    "Runtime",
+    "RunResult",
+    "Tracer",
+    "TraceEvent",
+    # memory
+    "MemoryOS",
+    "Memory",
+    "MemoryQualityReport",
+    "MemorySearchResult",
+    "SleepReport",
+    "calculate_salience",
+    "detect_contradiction",
+    "ContradictionChecker",
+    "compute_utility_score",
+    "score_memory_quality",
+    # retrieval / embeddings
+    "EmbeddingBackend",
+    "HashingEmbeddingBackend",
+    "SentenceTransformerBackend",
+    "get_embedder",
+    "VectorIndex",
+    # llm
+    "LLMClient",
+    "coerce_llm",
+    # reflection
+    "Reflector",
+    "Lesson",
+    "ReflectionInput",
+    "SelfRefine",
+    "SelfRefineResult",
+    # healing
+    "FailureDiagnosis",
+    "diagnose",
+    "RepairPlan",
+    "plan_repair",
+    "heal",
+    "Sandbox",
+    "SandboxResult",
+    "RepairConsent",
+    "FailureDetector",
+    "detect_failures",
+    # reasoning
+    "ReasoningMarket",
+    "Proposal",
+    "Critic",
+    "LLMCritic",
+    "AuctionResult",
+    "run_auction",
+    "score_proposal",
+    "Debate",
+    "DebateResult",
+    # learning
+    "Skill",
+    "SkillLibrary",
+    "shape_reward",
+    "normalize_reward",
+    "Curriculum",
+    "CurriculumItem",
+    # thermodynamics
+    "EnergyReport",
+    "build_energy_report",
+    # metrics & observability
+    "ImprovementTracker",
+    "MetricSnapshot",
+    "ImprovementReport",
+    "OTelExporter",
+]

plasticity_agent/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Framework adapters (the framework-specific ones are experimental)."""
+
+from __future__ import annotations
+
+from plasticity_agent.adapters.crewai_adapter import CrewAIAdapter
+from plasticity_agent.adapters.generic import GenericAdapter
+from plasticity_agent.adapters.langgraph_adapter import LangGraphAdapter
+from plasticity_agent.adapters.openai_agents_adapter import OpenAIAgentsAdapter
+from plasticity_agent.adapters.pydantic_ai_adapter import PydanticAIAdapter
+
+__all__ = [
+    "GenericAdapter",
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "OpenAIAgentsAdapter",
+    "PydanticAIAdapter",
+]

plasticity_agent/adapters/crewai_adapter.py

@@ -0,0 +1,38 @@
+"""CrewAI adapter (experimental).
+
+Bridges a CrewAI crew to a :class:`PlasticAgent`. ``crewai`` is an optional
+dependency; a clear error is raised if it is missing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plasticity_agent.adapters.generic import GenericAdapter
+from plasticity_agent.core.runtime import RunResult
+
+
+class CrewAIAdapter:
+    """Experimental bridge between CrewAI and Plasticity."""
+
+    def __init__(self, agent: Any) -> None:
+        self.agent = agent
+        self._generic = GenericAdapter(agent)
+
+    @staticmethod
+    def _require() -> Any:
+        try:
+            import crewai  # noqa: F401
+        except ImportError as exc:  # pragma: no cover - depends on optional dep
+            raise ImportError(
+                "CrewAIAdapter requires the optional 'crewai' package "
+                "(experimental). Install it with `uv add crewai`."
+            ) from exc
+        return crewai
+
+    def wrap(self, crew: Any, method: str = "kickoff") -> Callable[..., RunResult]:
+        """Wrap ``crew.kickoff`` (or another method) through the agent runtime."""
+
+        self._require()
+        return self._generic.wrap_agent(crew, method=method)

plasticity_agent/adapters/generic.py

@@ -0,0 +1,45 @@
+"""The generic adapter.
+
+Framework-agnostic glue: wrap any Python callable or any object exposing a
+``run``-like method so it gains Plasticity tracing, an episodic memory of each
+invocation, and advisory healing on failure. The framework-specific adapters
+build on this.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plasticity_agent.core.runtime import RunResult
+
+
+class GenericAdapter:
+    """Wrap callables/agents so their runs flow through a :class:`PlasticAgent`."""
+
+    def __init__(self, agent: Any) -> None:
+        self.agent = agent
+
+    def wrap_callable(
+        self, fn: Callable[..., Any], *, reflect_on_failure: bool = False
+    ) -> Callable[..., RunResult]:
+        """Return a wrapper that runs ``fn`` through the agent runtime."""
+
+        def wrapped(*args: Any, **kwargs: Any) -> RunResult:
+            result = self.agent.run(lambda: fn(*args, **kwargs))
+            if result.status == "failed" and reflect_on_failure:
+                self.agent.reflect(task=result.task, error=result.error, reward=-1.0)
+            return result
+
+        wrapped.__name__ = getattr(fn, "__name__", "wrapped_callable")
+        return wrapped
+
+    def wrap_agent(self, external_agent: Any, method: str = "run") -> Callable[..., RunResult]:
+        """Wrap an external agent object's ``method`` (default ``run``)."""
+
+        target = getattr(external_agent, method, None)
+        if not callable(target):
+            raise AttributeError(
+                f"external agent has no callable '{method}' method to wrap"
+            )
+        return self.wrap_callable(target)

plasticity_agent/adapters/langgraph_adapter.py

@@ -0,0 +1,39 @@
+"""LangGraph adapter (experimental).
+
+Bridges a compiled LangGraph graph to a :class:`PlasticAgent` so each graph
+invocation is traced and remembered. ``langgraph`` is an optional dependency;
+this adapter raises a clear, actionable error if it is not installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plasticity_agent.adapters.generic import GenericAdapter
+from plasticity_agent.core.runtime import RunResult
+
+
+class LangGraphAdapter:
+    """Experimental bridge between LangGraph and Plasticity."""
+
+    def __init__(self, agent: Any) -> None:
+        self.agent = agent
+        self._generic = GenericAdapter(agent)
+
+    @staticmethod
+    def _require() -> Any:
+        try:
+            import langgraph  # noqa: F401
+        except ImportError as exc:  # pragma: no cover - depends on optional dep
+            raise ImportError(
+                "LangGraphAdapter requires the optional 'langgraph' package "
+                "(experimental). Install it with `uv add langgraph`."
+            ) from exc
+        return langgraph
+
+    def wrap(self, graph: Any, method: str = "invoke") -> Callable[..., RunResult]:
+        """Wrap ``graph.invoke`` (or another method) through the agent runtime."""
+
+        self._require()
+        return self._generic.wrap_agent(graph, method=method)

plasticity_agent/adapters/openai_agents_adapter.py

@@ -0,0 +1,38 @@
+"""OpenAI Agents SDK adapter (experimental).
+
+Bridges an OpenAI Agents SDK ``Agent``/``Runner`` to a :class:`PlasticAgent`.
+``openai-agents`` is an optional dependency; a clear error is raised if missing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plasticity_agent.adapters.generic import GenericAdapter
+from plasticity_agent.core.runtime import RunResult
+
+
+class OpenAIAgentsAdapter:
+    """Experimental bridge between the OpenAI Agents SDK and Plasticity."""
+
+    def __init__(self, agent: Any) -> None:
+        self.agent = agent
+        self._generic = GenericAdapter(agent)
+
+    @staticmethod
+    def _require() -> Any:
+        try:
+            import agents  # noqa: F401  (the `openai-agents` package imports as `agents`)
+        except ImportError as exc:  # pragma: no cover - depends on optional dep
+            raise ImportError(
+                "OpenAIAgentsAdapter requires the optional 'openai-agents' package "
+                "(experimental). Install it with `uv add openai-agents`."
+            ) from exc
+        return agents
+
+    def wrap(self, runner: Any, method: str = "run") -> Callable[..., RunResult]:
+        """Wrap a runner's ``run`` (or another method) through the agent runtime."""
+
+        self._require()
+        return self._generic.wrap_agent(runner, method=method)

plasticity_agent/adapters/pydantic_ai_adapter.py

@@ -0,0 +1,38 @@
+"""Pydantic AI adapter (experimental).
+
+Bridges a Pydantic AI ``Agent`` to a :class:`PlasticAgent`. ``pydantic-ai`` is
+an optional dependency; a clear error is raised if it is missing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plasticity_agent.adapters.generic import GenericAdapter
+from plasticity_agent.core.runtime import RunResult
+
+
+class PydanticAIAdapter:
+    """Experimental bridge between Pydantic AI and Plasticity."""
+
+    def __init__(self, agent: Any) -> None:
+        self.agent = agent
+        self._generic = GenericAdapter(agent)
+
+    @staticmethod
+    def _require() -> Any:
+        try:
+            import pydantic_ai  # noqa: F401
+        except ImportError as exc:  # pragma: no cover - depends on optional dep
+            raise ImportError(
+                "PydanticAIAdapter requires the optional 'pydantic-ai' package "
+                "(experimental). Install it with `uv add pydantic-ai`."
+            ) from exc
+        return pydantic_ai
+
+    def wrap(self, pydantic_agent: Any, method: str = "run_sync") -> Callable[..., RunResult]:
+        """Wrap a Pydantic AI agent's ``run_sync`` (or another method)."""
+
+        self._require()
+        return self._generic.wrap_agent(pydantic_agent, method=method)