@agentikos/omega-os 0.1.0 → 0.2.0

package/omega/Agentik_Engine/omega_engine/educators/skill.py

@@ -0,0 +1,69 @@
+"""`skill-educator` — generates new skill specs + maintains the catalog.
+
+The signature: a skill spec is the contract between the engine and a unit of
+capability (a `/command`). It declares: the trigger phrases, the inputs, the
+steps, the artifacts it produces, the verification gate, and the failure modes.
+
+Target SSOT path: ``Agentik_SSOT/skills/<name>.md``.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from omega_engine.educators.base import EducatorProposal, run_education
+from omega_engine.provider import AgentProvider
+
+_INSTRUCTIONS = """\
+Produce ONE skill spec the engine will load as a runnable capability. The spec
+MUST contain, in order, these sections:
+
+  1. Name + one-line purpose (the question the skill answers).
+  2. Trigger phrases (case-insensitive, FR + EN if applicable) — the strings
+     the router matches against. Be exhaustive: a missing trigger means the
+     skill never fires.
+  3. Inputs schema — every parameter, with type + whether it is required +
+     what the default is. No optional-and-undocumented fields.
+  4. Steps — numbered, each step one verb in imperative voice with a verify
+     checkpoint. State the input and output of each step.
+  5. Artifacts produced — the file/path the skill writes, the schema of any
+     structured output.
+  6. Verification gate — which forensic audit(s) (from the Quality Arsenal)
+     run on the artifact, and the minimum score. If none applies, state that
+     and explain why.
+  7. Failure modes — list at least 3 ways the skill can fail and what the
+     engine does in each (retry, escalate, abort).
+
+The spec MUST NOT:
+  - paraphrase another existing skill — state the boundary if related.
+  - omit the audit gate (every skill is auditable, no exceptions).
+  - hand-wave the failure modes.
+
+Format the artifact as Markdown.
+"""
+
+
+class SkillEducator:
+    """Generates skill specs for the SSOT skill catalog."""
+
+    name = "skill"
+    domain = "skills"
+
+    def generate(
+        self,
+        intent: str,
+        context: dict[str, Any],
+        provider: AgentProvider,
+    ) -> EducatorProposal:
+        skill_name = str(context.get("skill_name", "new-skill"))
+        target_path = f"Agentik_SSOT/skills/{skill_name}.md"
+        return run_education(
+            educator_name=self.name,
+            domain=self.domain,
+            intent=intent,
+            target_kind="skill",
+            target_path=target_path,
+            domain_instructions=_INSTRUCTIONS,
+            context={**context, "skill_name": skill_name},
+            provider=provider,
+            artifact_id=skill_name,
+        )

package/omega/Agentik_Engine/omega_engine/executor.py

@@ -49,11 +49,21 @@ class Executor:
         bus: EventBus,
         router: ModelRouter,
         audit: AuditGate,
+        partial_policy: str = "fail_up",
     ) -> None:
+        # partial_policy: how a dispatcher reacts to a PARTIAL scope (a child
+        # FAILED). One of: "fail_up" (default — the dispatcher fails too),
+        # "accept_partial" (the dispatcher completes with the verified children
+        # only), "retry_failed" (one retry pass on failed children, then
+        # fail_up if still PARTIAL). Declared per-topology in
+        # Agentik_Orchestration/topologies/<name>.yaml -> policy.on_partial.
+        if partial_policy not in ("fail_up", "accept_partial", "retry_failed"):
+            raise ValueError(f"unknown partial_policy: {partial_policy}")
         self._store = store
         self._bus = bus
         self._router = router
         self._audit = audit
+        self._partial_policy = partial_policy
         self._tasks: dict[str, Task] = {}
 
     # -- public ---------------------------------------------------------------
@@ -119,20 +129,50 @@ class Executor:
             children.append(child)
 
         status = scope_status([self._state(c.id) for c in children])
-        if status is ScopeStatus.JOINABLE:
+
+        # Per-topology PARTIAL policy
+        if status is ScopeStatus.PARTIAL and self._partial_policy == "retry_failed":
+            # one retry pass for every FAILED child — children are re-spawned as
+            # fresh tasks, each with their own budget. If they all pass, the
+            # scope becomes JOINABLE; otherwise we fall through to fail_up.
+            failed_children = [c for c in children
+                               if self._state(c.id) is TaskState.FAILED]
+            for failed in failed_children:
+                replacement = self._new_task(
+                    kind=failed.kind, role=failed.role,
+                    spec=failed.spec, parent_id=task.id, mission_id=mission_id,
+                )
+                self._run(replacement, mission_id)
+                children.append(replacement)
+            status = scope_status([self._state(c.id) for c in children])
+
+        accept_partial = (
+            status is ScopeStatus.PARTIAL
+            and self._partial_policy == "accept_partial"
+        )
+
+        if status is ScopeStatus.JOINABLE or accept_partial:
             # the barrier resolved — the dispatcher may now close
-            self._emit(task.id, EventType.SCOPE_JOINABLE, {"children": len(children)})
+            self._emit(task.id, EventType.SCOPE_JOINABLE,
+                       {"children": len(children),
+                        "partial_accepted": accept_partial})
             self._emit(task.id, EventType.CLAIMED_DONE)
             self._emit(task.id, EventType.VERIFYING)
-            self._emit(task.id, EventType.VERIFIED, {"reason": "all children verified"})
+            self._emit(task.id, EventType.VERIFIED,
+                       {"reason": "partial accepted" if accept_partial
+                        else "all children verified"})
             self._emit(task.id, EventType.COMPLETED)
         else:
-            # PARTIAL — a child failed. on_partial = fail_up (children already
-            # retried within their own budget). Honest partial failure.
+            # PARTIAL or RUNNING under fail_up. RUNNING here means recursion
+            # left non-terminal children — that is a real bug. PARTIAL under
+            # fail_up is honest failure.
             failed = [c.id for c in children
                       if self._state(c.id) is TaskState.FAILED]
             self._emit(task.id, EventType.FAILED,
-                       {"reason": "partial scope", "failed_children": failed})
+                       {"reason": "partial scope" if status is ScopeStatus.PARTIAL
+                        else "scope unresolved",
+                        "failed_children": failed,
+                        "policy": self._partial_policy})
 
     def _run_worker(self, task: Task) -> None:
         provider = self._router.resolve(task.role)

package/omega/Agentik_Engine/omega_engine/mission.py

@@ -109,7 +109,19 @@ def run_mission(
         gate: object = ArsenalGate(AuditRegistry.load(audits_dir), router)
     else:
         gate = AuditGate()
-    executor = Executor(store, bus, router, gate)
+    # read the topology's PARTIAL policy if a topology config is present;
+    # the default (fail_up) is the safe behaviour.
+    partial_policy = "fail_up"
+    topo_path = home / "Agentik_Orchestration" / "topologies" / "aisb-oracle-worker.yaml"
+    if topo_path.exists():
+        try:
+            import yaml
+            topo = yaml.safe_load(topo_path.read_text()) or {}
+            partial_policy = (topo.get("policy") or {}).get("on_partial", "fail_up")
+        except Exception:  # noqa: BLE001 — bad topology config falls back safely
+            partial_policy = "fail_up"
+
+    executor = Executor(store, bus, router, gate, partial_policy=partial_policy)
     result = executor.run_mission(intent)
 
     # the Oracle ALWAYS produces a report

package/omega/Agentik_Engine/omega_engine/provider.py

@@ -1,12 +1,20 @@
 """The provider abstraction — one contract, any LLM.
 
 The executor talks only to `AgentProvider`. `MockProvider` makes the whole
-orchestration testable with no network. `ClaudeProvider` is the real adapter.
+orchestration testable with no network. `ClaudeProvider` wraps Anthropic;
+`GLMProvider`, `OpenAIProvider`, and `DeepSeekProvider` wrap the OpenAI
+chat-completions wire format used by Zhipu/BigModel, OpenAI, and DeepSeek.
+
+The real adapters use the stdlib only (`urllib.request`, `json`). They never
+fail at construction — a missing API key only raises when `.run()` is called.
 """
 from __future__ import annotations
 
 import json
+import os
 import re
+import urllib.error
+import urllib.request
 from dataclasses import dataclass, field
 from typing import Any, Protocol, runtime_checkable
 
@@ -47,6 +55,8 @@ class MockProvider:
 
     def __init__(self, plan_size: int = 2) -> None:
         self._plan_size = plan_size
+        self._grader_calls = 0
+        self._agent_calls = 0
 
     def run(self, req: AgentRequest) -> AgentResult:
         role = req.role
@@ -75,6 +85,67 @@ class MockProvider:
                     "summary": "mock forensic audit — no falsifiable claims found",
                     "findings": [], "fix_plan": [],
                 }})
+        if role == "educator" or role.startswith("educator-"):
+            # a structured generation result — what the Educators expect.
+            # The mock returns a plausible artifact + self-critique score so the
+            # promotion pipeline has something real to gate on.
+            intent = req.context.get("intent", "generate")
+            kind = req.context.get("kind", "artifact")
+            educator = role.split("-", 1)[1] if "-" in role else "educator"
+            return AgentResult(
+                text=f"educator {educator} produced {kind} for: {intent}",
+                claimed_done=True,
+                artifacts={"proposal": {
+                    "kind": kind,
+                    "content": (
+                        f"# {kind} for {intent}\n\n"
+                        f"Generated by mock {educator} educator.\n"
+                    ),
+                    "score": 92,
+                    "summary": f"mock {educator} artifact for '{intent}'",
+                    "fix_plan": [],
+                }})
+
+        # --- RAG roles ---
+        if role == "rag-route":
+            # Default to hybrid (matches the architecture's "hybrid is the
+            # default" guidance). The router still applies its own heuristic
+            # for query-specific overrides.
+            return AgentResult(
+                text="route: hybrid", claimed_done=True,
+                artifacts={"strategy": "hybrid"},
+            )
+        if role == "rag-agent":
+            self._agent_calls += 1
+            # Terminate after one refinement hop — bounded behaviour, no loops.
+            original = req.context.get("original_query") or req.context.get(
+                "current_query", "")
+            done = self._agent_calls >= 2
+            return AgentResult(
+                text="agent step", claimed_done=True,
+                artifacts={
+                    "next_query": f"deeper: {original}",
+                    "done": done,
+                },
+            )
+        if role == "rag-grader":
+            self._grader_calls += 1
+            docs = req.context.get("documents", []) or []
+            # First call: every doc scores 40 (forces a Corrective retry).
+            # Second+ call: every doc scores 90 (lands above the threshold).
+            score = 40 if self._grader_calls == 1 else 90
+            return AgentResult(
+                text=f"graded {len(docs)} docs at {score}",
+                claimed_done=True,
+                artifacts={"scores": [score for _ in docs] or [score]},
+            )
+        if role == "rag-caption":
+            path = req.context.get("path", "")
+            return AgentResult(
+                text="captioned", claimed_done=True,
+                artifacts={"caption": f"mock caption for {path}"},
+            )
+
         return AgentResult(text="ok", claimed_done=True)
 
 
@@ -127,6 +198,181 @@ class ClaudeProvider:
         )
 
 
+# ---------------------------------------------------------------------------
+# OpenAI-compatible providers: GLM (BigModel/Zhipu), OpenAI, DeepSeek.
+#
+# All three speak the same chat-completions wire format. We share one tiny
+# stdlib HTTP transport (`_post_json`) and one response parser, then expose
+# three small adapter classes — each with its own id, default model, env key,
+# and base URL.
+# ---------------------------------------------------------------------------
+
+_DEFAULT_TIMEOUT = 120.0
+
+
+def _post_json(url: str, headers: dict[str, str], body: dict[str, Any],
+               timeout: float = _DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """POST JSON, return parsed JSON. Raises RuntimeError on protocol errors.
+
+    Stdlib-only (`urllib.request`) so the providers stay dependency-free.
+    """
+    data = json.dumps(body).encode("utf-8")
+    headers = {"Content-Type": "application/json", **headers}
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        raise RuntimeError(
+            f"HTTP {exc.code} from {url}: {detail[:500]}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"network error talking to {url}: {exc.reason}") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"non-JSON response from {url}: {raw[:500]}"
+        ) from exc
+
+
+def _parse_openai_chat_response(payload: dict[str, Any]) -> tuple[str, dict[str, int]]:
+    """Pull text + usage from an OpenAI-format chat completion response.
+
+    Returns ("", {}) if the structure is unexpected, rather than crashing.
+    """
+    text = ""
+    choices = payload.get("choices") or []
+    if choices and isinstance(choices, list):
+        first = choices[0] or {}
+        msg = first.get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            # GLM/anthropic-style content blocks: list of {"type": "text", "text": "..."}
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, dict):
+                    val = block.get("text") or block.get("content") or ""
+                    if isinstance(val, str):
+                        parts.append(val)
+            text = "".join(parts)
+    usage_raw = payload.get("usage") or {}
+    usage = {
+        "input_tokens": int(usage_raw.get("prompt_tokens", 0) or 0),
+        "output_tokens": int(usage_raw.get("completion_tokens", 0) or 0),
+    }
+    return text, usage
+
+
+class _OpenAICompatProvider:
+    """Shared transport for OpenAI-format chat completion APIs.
+
+    Subclasses set `id`, `_default_model`, `_env_var`, `_default_base_url`.
+    Construction never fails on missing key — `.run()` raises if it's still
+    missing when called.
+    """
+
+    id: str = "openai-compat"
+    _default_model: str = ""
+    _env_var: str = ""
+    _default_base_url: str = ""
+
+    def __init__(
+        self,
+        model: str | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self._model = model or self._default_model
+        self._api_key = api_key
+        self._base_url = base_url or self._default_base_url
+
+    def _resolve_key(self) -> str:
+        key = self._api_key or os.environ.get(self._env_var)
+        if not key:
+            raise RuntimeError(
+                f"{type(self).__name__} requires an API key. "
+                f"Pass api_key=... or set {self._env_var} in the environment."
+            )
+        return key
+
+    def _build_messages(self, req: AgentRequest) -> list[dict[str, str]]:
+        prompt = req.prompt
+        if req.role in ("oracle", "manager", "aisb"):
+            prompt = prompt + (
+                "\n\nRespond with a JSON array of subtasks, each "
+                '{"role":"worker","spec":{"task":"..."}}. JSON only.'
+            )
+        return [{"role": "user", "content": prompt}]
+
+    def _extra_body(self) -> dict[str, Any]:
+        """Adapter-specific knobs (overridable). Default: no extras."""
+        return {}
+
+    def run(self, req: AgentRequest) -> AgentResult:
+        api_key = self._resolve_key()
+        body: dict[str, Any] = {
+            "model": self._model,
+            "messages": self._build_messages(req),
+            "max_tokens": 4096,
+        }
+        body.update(self._extra_body())
+        payload = _post_json(
+            self._base_url,
+            {"Authorization": f"Bearer {api_key}"},
+            body,
+        )
+        text, usage = _parse_openai_chat_response(payload)
+        return AgentResult(
+            text=text,
+            claimed_done=True,
+            plan=_extract_plan(text) if req.role in ("oracle", "manager", "aisb") else [],
+            usage=usage,
+        )
+
+
+class GLMProvider(_OpenAICompatProvider):
+    """Zhipu / BigModel GLM via the OpenAI-compatible chat-completions API.
+
+    Endpoint: https://open.bigmodel.cn/api/paas/v4/chat/completions
+    Env: `GLM_API_KEY`.
+    """
+
+    id = "glm"
+    _default_model = "glm-4.6"
+    _env_var = "GLM_API_KEY"
+    _default_base_url = "https://open.bigmodel.cn/api/paas/v4/chat/completions"
+
+
+class OpenAIProvider(_OpenAICompatProvider):
+    """OpenAI Chat Completions.
+
+    Endpoint: https://api.openai.com/v1/chat/completions
+    Env: `OPENAI_API_KEY`.
+    """
+
+    id = "openai"
+    _default_model = "gpt-4o"
+    _env_var = "OPENAI_API_KEY"
+    _default_base_url = "https://api.openai.com/v1/chat/completions"
+
+
+class DeepSeekProvider(_OpenAICompatProvider):
+    """DeepSeek (OpenAI-compatible chat completions).
+
+    Endpoint: https://api.deepseek.com/v1/chat/completions
+    Env: `DEEPSEEK_API_KEY`.
+    """
+
+    id = "deepseek"
+    _default_model = "deepseek-chat"
+    _env_var = "DEEPSEEK_API_KEY"
+    _default_base_url = "https://api.deepseek.com/v1/chat/completions"
+
+
 def _extract_plan(text: str) -> list[dict[str, Any]]:
     """Pull a JSON subtask array out of an LLM response. Empty list if none."""
     match = re.search(r"\[.*\]", text, re.DOTALL)

package/omega/Agentik_Engine/omega_engine/rag/__init__.py

@@ -0,0 +1,21 @@
+"""Omega OS multi-RAG subsystem — five strategies behind one Protocol.
+
+`base.Retriever` is the contract every strategy honours. The Corrective RAG
+envelope (corrective.CorrectiveRetriever) wraps the chosen strategy; the
+router picks which strategy runs.
+
+See docs/ARCHITECTURE.md §7 for the full design.
+"""
+from omega_engine.rag.agentic import AgenticRetriever
+from omega_engine.rag.base import Document, RetrievalResult, Retriever
+from omega_engine.rag.corrective import CorrectiveRetriever
+from omega_engine.rag.graph import GraphRetriever
+from omega_engine.rag.hybrid import HybridRetriever
+from omega_engine.rag.multimodal import MultimodalRetriever
+from omega_engine.rag.router import RAGRouter
+
+__all__ = [
+    "Document", "RetrievalResult", "Retriever",
+    "HybridRetriever", "GraphRetriever", "AgenticRetriever",
+    "CorrectiveRetriever", "MultimodalRetriever", "RAGRouter",
+]

package/omega/Agentik_Engine/omega_engine/rag/agentic.py

@@ -0,0 +1,83 @@
+"""Agentic retriever — multi-hop retrieval steered by a provider.
+
+After every hop, the provider (role "rag-agent") looks at the current
+context and decides: keep going (return a refined `next_query`) or stop
+(`done: true`). The retriever loops up to `max_hops` and returns the
+accumulated, de-duplicated documents.
+
+This is the strategy for "decompose then dig" queries — questions where the
+first retrieval surfaces a clue, and the second clue is buried inside what
+the first one found.
+"""
+from __future__ import annotations
+
+from omega_engine.provider import AgentProvider, AgentRequest
+from omega_engine.rag.base import Document, RetrievalResult, Retriever
+
+
+class AgenticRetriever:
+    """Multi-hop on top of any underlying retriever."""
+
+    strategy = "agentic"
+
+    def __init__(
+        self,
+        inner: Retriever,
+        provider: AgentProvider,
+        *,
+        max_hops: int = 3,
+        k_per_hop: int = 4,
+    ) -> None:
+        self.inner = inner
+        self.provider = provider
+        self.max_hops = max_hops
+        self.k_per_hop = k_per_hop
+
+    def retrieve(self, query: str, k: int = 5) -> RetrievalResult:
+        seen_ids: set[str] = set()
+        accumulated: list[Document] = []
+        current = query
+        last_score = 0.0
+
+        for hop in range(self.max_hops):
+            partial = self.inner.retrieve(current, k=self.k_per_hop)
+            last_score = partial.score
+            for d in partial.documents:
+                if d.id in seen_ids:
+                    continue
+                seen_ids.add(d.id)
+                meta = dict(d.metadata)
+                meta["hop"] = hop
+                accumulated.append(Document(id=d.id, text=d.text, metadata=meta))
+
+            # Ask the provider whether to stop or refine.
+            ctx_snippets = [d.text[:200] for d in partial.documents[:3]]
+            decision = self.provider.run(AgentRequest(
+                role="rag-agent",
+                prompt=(
+                    f"Original query: {query}\n"
+                    f"Current hop: {hop}\n"
+                    f"Just-retrieved snippets:\n- " + "\n- ".join(ctx_snippets)
+                ),
+                context={
+                    "original_query": query,
+                    "current_query": current,
+                    "hop": hop,
+                    "snippets": ctx_snippets,
+                },
+            ))
+            artifacts = decision.artifacts or {}
+            if artifacts.get("done"):
+                break
+            next_q = artifacts.get("next_query")
+            if not next_q or next_q == current:
+                break
+            current = str(next_q)
+
+        # Final ranking: keep accumulation order (earlier hops first), trim to k.
+        return RetrievalResult(
+            query=query,
+            documents=accumulated[:k],
+            score=last_score,
+            strategy=self.strategy,
+        )

package/omega/Agentik_Engine/omega_engine/rag/base.py

@@ -0,0 +1,42 @@
+"""Shared contracts for every retriever — Document, RetrievalResult, Retriever.
+
+The whole RAG subsystem talks to these three types. A retriever is anything
+with `retrieve(query, k) -> RetrievalResult`. Strategies plug in behind the
+same interface, the router picks between them, and the Corrective envelope
+wraps any of them.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class Document:
+    """A single retrievable unit — text + provenance.
+
+    `metadata` is free-form: source path, modality, chunk index, score,
+    captions for images, anything a strategy wants to surface upward.
+    """
+
+    id: str
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RetrievalResult:
+    """What every retriever returns. The router fans these up; the corrective
+    envelope grades them; the caller reads `documents`."""
+
+    query: str
+    documents: list[Document]
+    score: float = 0.0       # aggregate confidence in [0, 1]
+    strategy: str = ""       # which retriever produced this result
+
+
+@runtime_checkable
+class Retriever(Protocol):
+    """The whole RAG subsystem speaks this Protocol."""
+
+    def retrieve(self, query: str, k: int = 5) -> RetrievalResult: ...