purpose_agent/__init__.py

"""
purpose_agent — A local-first self-improvement kernel for agents.

Turns traces into tested memory, policies, and rubrics so agents improve
without fine-tuning, cloud infrastructure, or vendor lock-in.

Architecture based on 13 published papers.
See COMPILED_RESEARCH.md for the full research trace.

Modules:
  Core:       types, llm_backend, actor, purpose_function, experience_replay, optimizer, orchestrator
  V2 Kernel:  v2_types, trace, memory, compiler, immune, memory_ci, evalport, benchmark_v2
  Research:   meta_rewarding, self_taught, prompt_optimizer, llm_compiler, retroformer
  SLM:        slm_backends (Ollama, llama-cpp, prompt compression)
  Streaming:  streaming (async generators, event streaming)
  Tools:      tools (Tool base class, built-in tools, Tool RAG)
  Observe:    observability (cost tracking, callbacks, metrics)
  Multi:      multi_agent (shared memory, agent delegation, teams)
  HITL:       hitl (checkpoint, interrupt, resume, Φ overrides)
  Eval:       evaluation (benchmark runner, improvement curves)
  Unified:    unified (Agent, Graph, parallel, Conversation, KnowledgeStore)
  Easy:       easy (purpose(), Team, quickstart wizard)
"""

__version__ = "2.0.0"

# ── Core ──────────────────────────────────────────────────────────────────
from purpose_agent.types import (
    State, Action, Trajectory, TrajectoryStep,
    Heuristic, PurposeScore, MemoryRecord, MemoryTier,
)
from purpose_agent.llm_backend import (
    LLMBackend, MockLLMBackend, HFInferenceBackend,
    OpenAICompatibleBackend, ChatMessage,
)
from purpose_agent.actor import Actor
from purpose_agent.purpose_function import PurposeFunction
from purpose_agent.experience_replay import ExperienceReplay
from purpose_agent.optimizer import HeuristicOptimizer
from purpose_agent.orchestrator import Orchestrator, Environment, SimpleEnvironment, TaskResult

# ── V2 Kernel ─────────────────────────────────────────────────────────────
from purpose_agent.v2_types import RunMode, MemoryScope, PurposeScoreV2
from purpose_agent.trace import Trace, TraceEvent
from purpose_agent.memory import MemoryStore, MemoryCard, MemoryKind, MemoryStatus
from purpose_agent.compiler import PromptCompiler, CompiledPrompt
from purpose_agent.immune import scan_memory, ScanResult
from purpose_agent.memory_ci import MemoryCI
from purpose_agent.evalport import EvalCase, EvalPort, DictEvalPort, ScoreBundle
from purpose_agent.benchmark_v2 import BenchmarkRunnerV2, V2BenchmarkResult

# ── Research Implementations ──────────────────────────────────────────────
from purpose_agent.meta_rewarding import MetaRewardingLoop
from purpose_agent.self_taught import SelfTaughtEvaluator
from purpose_agent.prompt_optimizer import PromptOptimizer, Signature, Demonstration
from purpose_agent.llm_compiler import LLMCompiler, ExecutionPlan, TaskNode
from purpose_agent.retroformer import Retroformer

# ── SLM-Native Backends ──────────────────────────────────────────────────
from purpose_agent.slm_backends import (
    OllamaBackend, LlamaCppBackend, SLMPromptCompressor,
    create_slm_backend, SLM_REGISTRY,
)

# ── Streaming & Async ────────────────────────────────────────────────────
from purpose_agent.streaming import StreamingMixin, StreamEvent, AsyncOrchestrator

# ── Tools ────────────────────────────────────────────────────────────────
from purpose_agent.tools import (
    Tool, FunctionTool, ToolResult, ToolRegistry,
    CalculatorTool, PythonExecTool, ReadFileTool, WriteFileTool,
)

# ── Observability ────────────────────────────────────────────────────────
from purpose_agent.observability import (
    CostTracker, TokenUsage, CallbackManager,
    AgentEvent, EventType, LoggingCallback, MetricsCollector,
)

# ── Multi-Agent ──────────────────────────────────────────────────────────
from purpose_agent.multi_agent import AgentSpec, AgentTeam

# ── Human-in-the-Loop ───────────────────────────────────────────────────
from purpose_agent.hitl import (
    HITLOrchestrator, Checkpoint, HumanInputHandler,
    CLIInputHandler, AutoApproveHandler, InterruptType,
)

# ── Evaluation (V1 compat) ──────────────────────────────────────────────
from purpose_agent.evaluation import BenchmarkTask, BenchmarkRunner, BenchmarkResult

# ── Plugin Registry ──────────────────────────────────────────────────────
from purpose_agent.registry import (
    PluginRegistry, backend_registry, callback_registry, model_registry,
    EmbeddingBackend, default_embedding,
)

# ── Unified Capabilities ────────────────────────────────────────────────
from purpose_agent.unified import (
    Agent, Graph, parallel, Conversation, KnowledgeStore,
    START, END, Message,
)

# ── Easy API (the only thing beginners need) ─────────────────────────────
from purpose_agent.easy import purpose, Team, quickstart, TEAM_TEMPLATES

__all__ = [
    # Core
    "State", "Action", "Trajectory", "TrajectoryStep", "Heuristic",
    "PurposeScore", "MemoryRecord", "MemoryTier",
    "LLMBackend", "MockLLMBackend", "HFInferenceBackend",
    "OpenAICompatibleBackend", "ChatMessage",
    "Actor", "PurposeFunction", "ExperienceReplay", "HeuristicOptimizer",
    "Orchestrator", "Environment", "SimpleEnvironment", "TaskResult",
    # V2 Kernel
    "RunMode", "MemoryScope", "PurposeScoreV2",
    "Trace", "TraceEvent",
    "MemoryStore", "MemoryCard", "MemoryKind", "MemoryStatus",
    "PromptCompiler", "CompiledPrompt",
    "scan_memory", "ScanResult",
    "MemoryCI",
    "EvalCase", "EvalPort", "DictEvalPort", "ScoreBundle",
    "BenchmarkRunnerV2", "V2BenchmarkResult",
    # Research
    "MetaRewardingLoop", "SelfTaughtEvaluator",
    "PromptOptimizer", "Signature", "Demonstration",
    "LLMCompiler", "ExecutionPlan", "TaskNode",
    "Retroformer",
    # SLM
    "OllamaBackend", "LlamaCppBackend", "SLMPromptCompressor",
    "create_slm_backend", "SLM_REGISTRY",
    # Streaming
    "StreamingMixin", "StreamEvent", "AsyncOrchestrator",
    # Tools
    "Tool", "FunctionTool", "ToolResult", "ToolRegistry",
    "CalculatorTool", "PythonExecTool", "ReadFileTool", "WriteFileTool",
    # Observability
    "CostTracker", "TokenUsage", "CallbackManager",
    "AgentEvent", "EventType", "LoggingCallback", "MetricsCollector",
    # Multi-Agent
    "AgentSpec", "AgentTeam",
    # HITL
    "HITLOrchestrator", "Checkpoint", "HumanInputHandler",
    "CLIInputHandler", "AutoApproveHandler", "InterruptType",
    # Evaluation (V1)
    "BenchmarkTask", "BenchmarkRunner", "BenchmarkResult",
    # Plugin Registry
    "PluginRegistry", "backend_registry", "callback_registry", "model_registry",
    "EmbeddingBackend", "default_embedding",
    # Unified Capabilities
    "Agent", "Graph", "parallel", "Conversation", "KnowledgeStore",
    "START", "END", "Message",
    # Easy API
    "purpose", "Team", "quickstart", "TEAM_TEMPLATES",
]