conscio 1.3.0__py3-none-any.whl

conscio/__init__.py

@@ -0,0 +1,60 @@
+"""
+Conscio — A self-awareness framework for AI agents.
+
+Enables emergent consciousness through context-aware memory, introspection,
+and goal generation. Adapts behavior based on the underlying model's
+context window size.
+"""
+
+__version__ = "1.3.0"
+__author__ = "Neguiolidas / Neguitech"
+
+from .engine import ConsciousnessEngine
+from .context_manager import ContextManager, ContextMode
+from .models import ModelRegistry
+from .content_store import ContentStore
+from .event_bus import EventBus
+from .output_filter import FilterPipeline, build_pipeline_from_dict
+from .token_tracker import TokenTracker
+from .migrate import Migrator
+from .session_lifecycle import SessionSummary, record_session_lifecycle
+from .metabolic import MetabolicContext, MetabolicState
+from .dreaming import DreamCycle, DreamReport
+from .agency import MockAdapter, OllamaAdapter, LlamaCppAdapter, \
+    OpenAICompatAdapter  # noqa: F401
+from .risk import Risk
+from .perception import SensorAdapter, PerceptionFrame, MockSensor
+# Plugin discovery lives under `conscio.plugins` (discover_adapters/sensors/tools)
+# — kept out of the top-level namespace to keep this import light.
+
+# Note: SessionRAG is intentionally NOT imported here — it depends on numpy
+# and probes Ollama. Use the shared factory (`from conscio.session_rag_factory
+# import create_session_rag`) for lazy, graceful construction, or import
+# SessionRAG directly when you know it's available.
+
+__all__ = [
+ "ConsciousnessEngine",
+ "ContextManager",
+ "ContextMode",
+ "ModelRegistry",
+ "ContentStore",
+ "EventBus",
+ "FilterPipeline",
+ "build_pipeline_from_dict",
+ "TokenTracker",
+ "Migrator",
+ "SessionSummary",
+ "record_session_lifecycle",
+ "MetabolicContext",
+ "MetabolicState",
+ "DreamCycle",
+ "DreamReport",
+ "MockAdapter",
+ "OllamaAdapter",
+ "LlamaCppAdapter",
+ "OpenAICompatAdapter",
+ "Risk",
+ "SensorAdapter",
+ "PerceptionFrame",
+ "MockSensor",
+]

conscio/__main__.py

@@ -0,0 +1,6 @@
+# conscio/__main__.py
+"""`python -m conscio` → the conscio CLI."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

conscio/agency/__init__.py

@@ -0,0 +1,40 @@
+"""
+Conscio Agency — the volition layer (v1.0.0 "Spine" + "Immunity" +
+"Volition", v1.1 "Procedural").
+
+Stateless LLM orchestration downstream of engine.reflect():
+contracts -> adapter -> gateway (T1 GBNF/T2 JSON/T3 KV) -> tools ->
+skeptic/trust -> ledger -> breaker -> act pipeline -> arbiter/loop.
+Capabilities are measured (ProbeSuite), never assumed.
+Core stays zero-deps (stdlib + sqlite3); HTTP adapters use urllib only.
+"""
+from .act import ActPipeline, ActReport, ActStatus
+from .adapter import (AdapterCaps, AdapterError, InferenceAdapter,
+                      InferenceResult, Meter, MeteredAdapter, MockAdapter)
+from .adapters import LlamaCppAdapter, OllamaAdapter, OpenAICompatAdapter
+from .breaker import DEFAULT_MAX_RETRIES, CircuitBreaker
+from .contracts import ActionProposal, AuditVerdict, ToolResult, validate
+from .gateway import GatewayError, OutputGateway
+from .grammar import compile_proposal_grammar, compile_schema_grammar
+from .ledger import ActionLedger
+from .loop import (DISSONANCE_HINTS, ActBudget, AutonomyLoop, GoalArbiter,
+                   RunReport)
+from .profiles import (ModelProfile, ProbeSuite, choose_tier,
+                       max_visible_tools, skeptic_mode)
+from .skeptic import Skeptic
+from .skills import SkillLibrary
+from .tools import Risk, ToolRegistry, make_default_registry
+from .trust import TrustMatrix
+
+__all__ = [
+    "ActPipeline", "ActReport", "ActStatus", "AdapterCaps", "AdapterError",
+    "InferenceAdapter", "InferenceResult", "Meter", "MeteredAdapter",
+    "MockAdapter", "LlamaCppAdapter", "OllamaAdapter", "OpenAICompatAdapter",
+    "DEFAULT_MAX_RETRIES", "CircuitBreaker", "ActionProposal", "AuditVerdict",
+    "ToolResult", "validate", "GatewayError", "OutputGateway",
+    "compile_proposal_grammar", "compile_schema_grammar", "ActionLedger",
+    "DISSONANCE_HINTS", "ActBudget", "AutonomyLoop", "GoalArbiter",
+    "RunReport", "ModelProfile", "ProbeSuite", "choose_tier",
+    "max_visible_tools", "skeptic_mode", "Skeptic", "SkillLibrary", "Risk",
+    "ToolRegistry", "TrustMatrix", "make_default_registry",
+]

conscio/agency/act.py

@@ -0,0 +1,302 @@
+# conscio/agency/act.py
+"""
+ActPipeline — the volition loop (spec section 6). F2: immunity.
+
+reflect() stays untouched and passive; act() runs downstream consuming
+the ConsciousnessState it produced. The cycle: deterministic checks →
+risk gating → Skeptic audit (clean call) → PROPOSED (L1 / HIGH risk) or
+immediate supervised execution (L2, earned via TrustMatrix). Skeptic
+FAIL is recorded as a failed row (feeds the breaker); a human reject()
+stays 'rejected' and never counts against the agent.
+
+F3: GoalArbiter selection, real decode tier in the ledger,
+profile-driven tool visibility (max_visible_tools).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable
+
+from conscio.context_manager import ConsciousnessState
+
+from .actor import build_actor_prompt
+from .adapter import InferenceAdapter
+from .breaker import CircuitBreaker
+from .contracts import (PROPOSAL_SCHEMA, ActionProposal, AuditVerdict,
+                        ToolResult, validate)
+from .gateway import GatewayError, OutputGateway
+from .ledger import ActionLedger
+from .skeptic import Skeptic
+from .tools import Risk, ToolRegistry
+from .trust import TrustMatrix
+
+
+class ActStatus(str, Enum):
+    PROPOSED = "proposed"
+    EXECUTED = "executed"
+    REJECTED = "rejected"
+    FAILED = "failed"
+    LOCKED = "locked"
+
+
+@dataclass
+class ActReport:
+    status: ActStatus
+    proposal: ActionProposal | None = None
+    verdict: AuditVerdict | None = None
+    result: ToolResult | None = None
+    ledger_id: int | None = None
+    reason: str = ""
+    lockdown: bool = False
+
+
+def goal_fingerprint(goal_text: str) -> str:
+    return hashlib.sha256(goal_text.encode("utf-8")).hexdigest()[:16]
+
+
+class ActPipeline:
+    def __init__(self, *, adapter: InferenceAdapter, registry: ToolRegistry,
+                 ledger: ActionLedger, breaker: CircuitBreaker,
+                 gateway: OutputGateway | None = None,
+                 skeptic: Skeptic | None = None,
+                 trust: TrustMatrix | None = None,
+                 meta: Any = None,
+                 autonomy_cap: int = 1,
+                 recall_fn: Callable[[str], list[str]] | None = None,
+                 emit_fn: Callable[..., Any] | None = None,
+                 few_shot_provider: Callable[[str], list[str]] | None = None,
+                 arbiter: Any = None):
+        from .loop import GoalArbiter      # runtime: loop imports this module
+
+        self.adapter = adapter
+        self.registry = registry
+        self.ledger = ledger
+        self.breaker = breaker
+        self.gateway = gateway or OutputGateway(adapter)
+        self.skeptic = skeptic
+        self.trust = trust
+        self.meta = meta
+        self.autonomy_cap = autonomy_cap
+        self.recall_fn = recall_fn
+        self.emit_fn = emit_fn or (lambda **kw: None)
+        self.few_shot_provider = few_shot_provider
+        self.arbiter = arbiter or GoalArbiter(breaker)
+        self.max_visible_tools: int | None = None    # set by engine.probe()
+
+    # ── act cycle (spec §6) ──
+
+    def act(self, state: ConsciousnessState) -> ActReport:
+        if state.action_lockdown:
+            return ActReport(status=ActStatus.LOCKED,
+                             reason="action_lockdown active")
+        if not state.active_goals:
+            return ActReport(status=ActStatus.FAILED,
+                             reason="no active goals")
+
+        goal_text = self.arbiter.choose(state)
+        if goal_text is None:
+            return ActReport(status=ActStatus.FAILED,
+                             reason="all active goals quarantined")
+        goal_fp = goal_fingerprint(goal_text)
+
+        recall = self.recall_fn(goal_text) if self.recall_fn else []
+        few_shot = (self.few_shot_provider(goal_text)
+                    if self.few_shot_provider else [])
+        prompt = build_actor_prompt(
+            state=state, goal_text=goal_text,
+            catalog_text=self.registry.catalog_text(self.max_visible_tools),
+            recall_snippets=recall, few_shot=few_shot)
+        self.emit_fn(type="tool_call", category="external",
+                     data={"action": "cycle_start", "goal_fp": goal_fp})
+
+        try:
+            proposal = self.gateway.request_action(
+                prompt, PROPOSAL_SCHEMA, goal_id=goal_fp,
+                tool_names=self.registry.names())
+        except GatewayError as exc:
+            return self._fail(goal_fp, tool="", args={},
+                              reason=f"decode failed: {exc}",
+                              goal_text=goal_text)
+
+        # deterministic checks (skeptic checks 1-2 + sandbox — no LLM)
+        spec = self.registry.get(proposal.tool)
+        if spec is None:
+            return self._fail(goal_fp, tool=proposal.tool,
+                              args=proposal.args,
+                              reason=f"unknown tool '{proposal.tool}'",
+                              goal_text=goal_text)
+        arg_errors = validate(proposal.args, spec.params)
+        if arg_errors:
+            return self._fail(goal_fp, tool=proposal.tool,
+                              args=proposal.args,
+                              reason="invalid args: " + "; ".join(arg_errors),
+                              goal_text=goal_text)
+        if spec.precheck is not None:
+            precheck_error = spec.precheck(proposal.args)
+            if precheck_error:
+                return self._fail(goal_fp, tool=proposal.tool,
+                                  args=proposal.args,
+                                  reason=f"precheck: {precheck_error}",
+                                  goal_text=goal_text)
+
+        # risk gating + semantic audit (spec §5.6)
+        verdict = self._audit(spec, proposal, goal_text)
+        if not verdict.passed:
+            if self.meta is not None:
+                self.meta.record_error(f"act:{proposal.tool}:skeptic_fail")
+            return self._fail(goal_fp, tool=proposal.tool,
+                              args=proposal.args,
+                              reason="skeptic: " + "; ".join(verdict.reasons),
+                              verdict=verdict, goal_text=goal_text,
+                              report_status=ActStatus.REJECTED,
+                              proposal=proposal)
+
+        row_id = self.ledger.record(
+            goal_fp=goal_fp, goal_text=goal_text, tool=proposal.tool,
+            args_json=json.dumps(proposal.args),
+            rationale=proposal.rationale,
+            tier=self.gateway.last_tier or "T2", status="proposed",
+            adapter=getattr(self.adapter, "wrapped_name",
+                            type(self.adapter).__name__),
+            model=self.adapter.capabilities().model_name)
+        self.ledger.update_verdict(
+            row_id, "PASS" if verdict.audited else "unaudited",
+            verdict.reasons)
+        self.emit_fn(type="tool_call", category="external",
+                     data={"action": "proposed", "tool": proposal.tool,
+                           "goal_fp": goal_fp})
+
+        # HIGH risk never auto-executes (R6); L2 must be earned AND allowed
+        if spec.risk is Risk.HIGH or self._effective_autonomy(
+                proposal.tool) < 2:
+            return ActReport(status=ActStatus.PROPOSED, proposal=proposal,
+                             verdict=verdict, ledger_id=row_id)
+
+        # L2 SUPERVISED: execute now, under the verdict just earned
+        return self._execute(row_id, proposal, verdict, goal_fp, goal_text)
+
+    # ── audit + autonomy helpers ──
+
+    def _audit(self, spec, proposal: ActionProposal,
+               goal_text: str) -> AuditVerdict:
+        if (spec.risk is Risk.LOW and self.trust is not None
+                and self.trust.fast_path_ok()):
+            return AuditVerdict(
+                verdict="PASS", audited=False, reasons=[],
+                confidence=self.trust.meta.calibration_score()
+                if getattr(self.trust, "meta", None) is not None else 0.75)
+        if self.skeptic is None:               # F1 wiring: no audit available
+            return AuditVerdict(verdict="PASS", audited=False)
+        return self.skeptic.audit(proposal, goal_text=goal_text)
+
+    def _effective_autonomy(self, task_type: str) -> int:
+        earned = (self.trust.autonomy_level(task_type)
+                  if self.trust is not None else 1)
+        return min(self.autonomy_cap, earned)
+
+    def _execute(self, row_id: int, proposal: ActionProposal,
+                 verdict: AuditVerdict, goal_fp: str,
+                 goal_text: str) -> ActReport:
+        result = self.registry.dispatch(proposal.tool, proposal.args)
+        status = "executed" if result.ok else "failed"
+        self.ledger.update_execution(
+            row_id, ok=result.ok, output=result.output,
+            error=result.error, duration_ms=result.duration_ms,
+            status=status)
+        self.emit_fn(type="tool_call", category="external",
+                     data={"action": status, "tool": proposal.tool})
+        if self.meta is not None:
+            self.meta.record_confidence(
+                proposal.tool, verdict.confidence,
+                "success" if result.ok else "failure")
+        lockdown = False
+        if result.ok:
+            if self.trust is not None:
+                self.trust.on_success(proposal.tool)
+        else:
+            if self.meta is not None:
+                self.meta.record_error(f"act:{proposal.tool}:exec_fail")
+            if self.breaker.should_trip(goal_fp, task_type=proposal.tool):
+                self.breaker.trip(goal_fp, detail=result.error,
+                                  goal_text=goal_text)
+                lockdown = self.breaker.global_lockdown_due()
+        return ActReport(
+            status=ActStatus.EXECUTED if result.ok else ActStatus.FAILED,
+            proposal=proposal, verdict=verdict, result=result,
+            ledger_id=row_id, reason="" if result.ok else result.error,
+            lockdown=lockdown)
+
+    # ── human gate ──
+
+    def approve(self, ledger_id: int) -> ActReport:
+        row = self.ledger.get(ledger_id)
+        if row is None:
+            return ActReport(status=ActStatus.FAILED,
+                             reason=f"no pending proposal #{ledger_id}")
+        # The atomic claim (proposed -> executing) is the SOLE gate: only the
+        # winner dispatches, so a concurrent or repeated approve() can never
+        # double-execute. A non-proposed row (already executed/rejected, or
+        # claimed by a racing caller) loses the claim and is reported handled.
+        if not self.ledger.claim(ledger_id):
+            return ActReport(status=ActStatus.FAILED, ledger_id=ledger_id,
+                             reason=f"proposal #{ledger_id} already handled")
+        if self.registry.get(row["tool"]) is None:
+            # registry changed between act() and approve()
+            self.ledger.update_execution(
+                ledger_id, ok=False, output="",
+                error="tool no longer registered", duration_ms=0,
+                status="failed")
+            return ActReport(status=ActStatus.FAILED, ledger_id=ledger_id,
+                             reason="tool no longer registered")
+        result = self.registry.dispatch(row["tool"],
+                                        json.loads(row["args_json"]))
+        status = "executed" if result.ok else "failed"
+        self.ledger.update_execution(
+            ledger_id, ok=result.ok, output=result.output,
+            error=result.error, duration_ms=result.duration_ms,
+            status=status)
+        self.emit_fn(type="tool_call", category="external",
+                     data={"action": status, "tool": row["tool"]})
+        if self.meta is not None:
+            self.meta.record_confidence(
+                row["tool"], 0.5,                  # human-gated: neutral conf
+                "success" if result.ok else "failure")
+        if result.ok and self.trust is not None:
+            self.trust.on_success(row["tool"])
+        return ActReport(
+            status=ActStatus.EXECUTED if result.ok else ActStatus.FAILED,
+            result=result, ledger_id=ledger_id,
+            reason="" if result.ok else result.error)
+
+    def reject(self, ledger_id: int, reason: str = "") -> None:
+        row = self.ledger.get(ledger_id)
+        if row is None or row["status"] != "proposed":
+            return                              # audit rows are immutable (R8)
+        self.ledger.update_execution(ledger_id, ok=False, output="",
+                                     error=reason or "rejected",
+                                     duration_ms=0, status="rejected")
+
+    # ── failure path + breaker ──
+
+    def _fail(self, goal_fp: str, *, tool: str, args: dict, reason: str,
+              verdict: AuditVerdict | None = None, goal_text: str = "",
+              report_status: ActStatus = ActStatus.FAILED,
+              proposal: ActionProposal | None = None) -> ActReport:
+        row_id = self.ledger.record(goal_fp=goal_fp, goal_text=goal_text,
+                                    tool=tool or "(none)",
+                                    args_json=json.dumps(args), rationale="",
+                                    tier=self.gateway.last_tier or "T2",
+                                    status="failed")
+        if verdict is not None:
+            self.ledger.update_verdict(row_id, verdict.verdict,
+                                       verdict.reasons)
+        lockdown = False
+        if self.breaker.should_trip(goal_fp, task_type=tool or ""):
+            self.breaker.trip(goal_fp, detail=reason, goal_text=goal_text)
+            lockdown = self.breaker.global_lockdown_due()
+        return ActReport(status=report_status, proposal=proposal,
+                         verdict=verdict, ledger_id=row_id, reason=reason,
+                         lockdown=lockdown)

conscio/agency/actor.py

@@ -0,0 +1,39 @@
+# conscio/agency/actor.py
+"""
+Actor phase — stateless proposal prompt (spec section 5.5).
+
+Semantic content only; the OutputGateway appends the syntax contract
+(JSON or KV instructions). Zero history: every build starts from the
+current ConsciousnessState, never from previous cycles.
+
+few_shot is the v1.1 SkillLibrary hook: F1 callers pass an empty list.
+"""
+from __future__ import annotations
+
+from conscio.context_manager import ConsciousnessState
+
+ACTOR_PERSONA = (
+    "You are the volition of a persistent agent. You receive the agent's "
+    "current conscious state, one active goal and the available tools. "
+    "Propose exactly ONE tool action that reduces the agent's dominant "
+    "dissonance and advances the goal. Be conservative: prefer reading "
+    "before writing, and never invent tools or arguments.")
+
+
+def build_actor_prompt(*, state: ConsciousnessState, goal_text: str,
+                       catalog_text: str, recall_snippets: list[str],
+                       few_shot: list[str]) -> str:
+    sections = [ACTOR_PERSONA, "", state.to_injection()]
+    if state.coherence_note:
+        sections.append(f"Dominant dissonance: {state.coherence_note}")
+    sections.append(f"Active goal: {goal_text}")
+    if recall_snippets:
+        sections.append("Relevant memories:")
+        sections.extend(f"- {snippet}" for snippet in recall_snippets)
+    if few_shot:
+        sections.append("Examples of past successful actions:")
+        sections.extend(few_shot)
+    if catalog_text:
+        sections.append("Available tools:")
+        sections.append(catalog_text)
+    return "\n".join(sections)

conscio/agency/adapter.py

@@ -0,0 +1,131 @@
+# conscio/agency/adapter.py
+"""
+InferenceAdapter — decouples the agentic core from any inference backend
+(spec section 5.1 / blueprint section 7).
+
+The engine never does HTTP itself; it talks to this interface. MockAdapter
+is the deterministic backend used by the entire test suite.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from collections.abc import Sequence
+from typing import Any, Callable
+
+
+class AdapterError(Exception):
+    """Base error for inference failures."""
+
+
+class AdapterTimeout(AdapterError):
+    pass
+
+
+class AdapterConnectionError(AdapterError):
+    pass
+
+
+class AdapterBadResponse(AdapterError):
+    pass
+
+
+@dataclass
+class InferenceResult:
+    text: str
+    tokens_in: int = 0
+    tokens_out: int = 0
+    latency_ms: int = 0
+
+
+@dataclass
+class AdapterCaps:
+    model_name: str = "mock"
+    json_mode: bool = True
+    grammar: bool = False
+
+
+@dataclass
+class Meter:
+    """Shared inference odometer — the binding budget reads this (P3)."""
+    calls: int = 0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    latencies_ms: list[int] = field(default_factory=list)
+
+    @property
+    def tokens(self) -> int:
+        return self.tokens_in + self.tokens_out
+
+
+class InferenceAdapter(ABC):
+    @abstractmethod
+    def generate(self, prompt: str, *, schema: dict | None = None,
+                 grammar: str | None = None, max_tokens: int = 512,
+                 temperature: float = 0.2,
+                 stop: list[str] | None = None) -> InferenceResult: ...
+
+    @abstractmethod
+    def capabilities(self) -> AdapterCaps: ...
+
+
+class MockAdapter(InferenceAdapter):
+    """Scriptable adapter: returns queued responses, records every call.
+
+    Script entries may be callables (prompt -> str) so a mock can react
+    to prompt content — e.g. answer differently when few-shot exemplars
+    are present (the bench skill curve relies on this).
+    """
+
+    def __init__(self,
+                 script: Sequence[str | Callable[[str], str]] | None = None,
+                 caps: AdapterCaps | None = None):
+        self._script = list(script or [])
+        self._caps = caps or AdapterCaps()
+        self.calls: list[dict[str, Any]] = []
+
+    def generate(self, prompt: str, *, schema: dict | None = None,
+                 grammar: str | None = None, max_tokens: int = 512,
+                 temperature: float = 0.2,
+                 stop: list[str] | None = None) -> InferenceResult:
+        self.calls.append({"prompt": prompt, "schema": schema,
+                           "grammar": grammar, "max_tokens": max_tokens,
+                           "temperature": temperature, "stop": stop})
+        if not self._script:
+            raise AdapterError("MockAdapter script exhausted")
+        entry = self._script.pop(0)
+        text = entry(prompt) if callable(entry) else entry
+        return InferenceResult(text=text, tokens_in=len(prompt) // 4,
+                               tokens_out=len(text) // 4)
+
+    def capabilities(self) -> AdapterCaps:
+        return self._caps
+
+
+class MeteredAdapter(InferenceAdapter):
+    """Transparent wrapper counting calls/tokens/latency on a Meter.
+
+    A failed call still debits one call: the budget pays for attempts.
+    `wrapped_name` keeps the real adapter class visible to the ledger.
+    """
+
+    def __init__(self, inner: InferenceAdapter, meter: Meter):
+        self.inner = inner
+        self.meter = meter
+        self.wrapped_name = type(inner).__name__
+
+    def generate(self, prompt: str, *, schema: dict | None = None,
+                 grammar: str | None = None, max_tokens: int = 512,
+                 temperature: float = 0.2,
+                 stop: list[str] | None = None) -> InferenceResult:
+        self.meter.calls += 1
+        result = self.inner.generate(
+            prompt, schema=schema, grammar=grammar, max_tokens=max_tokens,
+            temperature=temperature, stop=stop)
+        self.meter.tokens_in += result.tokens_in
+        self.meter.tokens_out += result.tokens_out
+        self.meter.latencies_ms.append(result.latency_ms)
+        return result
+
+    def capabilities(self) -> AdapterCaps:
+        return self.inner.capabilities()