EPIC: Unify and conform the Prolog-RLM control plane #154

New issue

Open

opened 2026-09-09 15:05:12 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-09 15:05:12 +00:00

Owner

Parent: #1

Goal

Consume Prolog-RLM as a pinned reusable symbolic library through a thin Python bridge, without copying/reimplementing its policy semantics inside Agent Zero.

Bootstrap integration

Prefer a persistent SWI-Prolog sidecar or narrowly supervised synchronous process boundary with typed JSON messages. Keep process/language failure isolated from the Agent Zero framework runtime.

Initial bridge contract:

Input:

{task, user_message, recent_turns, tool_metadata, memory_candidates,
 project_context_candidates, active_state, budget}

Output:

{selected_context_units, selected_tool_ids, rejected_units_with_reasons,
 ledger, evidence_refs, fingerprint, warnings}

No output field grants tool authority.

Dependency policy

Pin exact Prolog-RLM commit/flake input; never track moving main in production.
Begin with rlm_context_budget + tiny audited admission predicates.
Add rlm_artifact when focused conformance tests pass.
Gate rlm_prompt_compiler behind exact-path tests until its current anonymous-dict/schema regression is demonstrably fixed.
Hold critical async/subagent control flow until cancellation/time-limit propagation is proven.
Do not make bootstrap depend on conversation/evolution modules while their current regressions remain unresolved.

Failure semantics

SWI unavailable/start failure -> explicit symbolic-unavailable state.
Invalid schema/response -> reject result, log evidence, use documented bounded fallback.
Timeout -> terminate/restart symbolic worker; never interpret timeout as empty successful selection.
Fingerprint input + output so repeated/replayed decisions are inspectable.

2026-08-24 convergence directive

One Prolog-RLM plugin

Agent Zero must expose one bundled Prolog-RLM plugin, _prolog_rlm.

The current split between _prolog_rlm and _prolog_context_compiler is an implementation migration state, not the target architecture. Context compilation, provider-visible projection, persistent symbolic workers, completion, memory-KB integration, tools, and settings belong behind the single _prolog_rlm plugin boundary.

Migration may temporarily preserve internal Python modules/packages to avoid import churn, but only _prolog_rlm may remain discoverable/configurable as a runtime plugin at completion.

Required invariants:

exactly one Prolog-RLM plugin manifest is discovered;
one plugin owns enablement/configuration;
no duplicate lifecycle hooks or conflicting tool-filter hooks;
no plugin import-order dependency;
context/compiler workers may remain separate supervised processes internally when latency/isolation requires it;
plugin settings expose one coherent surface.

500-token starting context

The symbolic provider-visible context budget starts at 500 tokens for the minimal/default working projection.

500 is the starting/floor target for a simple turn, not permission to truncate required user input or tool protocol until the request becomes invalid. Prolog-RLM should grow context deliberately from that lean starting point based on task requirements, dependencies, evidence, and tool contracts.

Tests must distinguish:

minimal/simple-turn target around 500 tokens;
required protocol/system overhead;
expanded context selected for genuinely complex tasks;
hard provider input limits.

The current 16k/12k context defaults are not the target operating behavior for Symbolics.

Provider compatibility belongs at the boundary

Provider-specific request legality must be normalized before dispatch. In particular, OpenRouter routes backed by Z.AI that reject tool_choice: required must receive a supported value such as auto rather than failing with HTTP 400.

Do not globally force auto for providers that support stronger tool-choice semantics. Capability/compatibility selection belongs in the transport/provider policy and must be covered by #58.

Persistent Prolog KB memory integration

When _prolog_rlm is active, persistent memory/state intended for symbolic reasoning must be available to Prolog as durable KB facts/records rather than existing only as vector-memory prose.

The memory lifecycle and epistemic rules remain owned by #4. This epic owns the runtime/bridge path that makes those persistent KBs queryable by the single Prolog-RLM control plane.

RAGE loop

Review exact current Prolog-RLM commit/APIs/tests -> analyze smallest safe ABI -> generate bridge + fixtures -> execute both happy/failure paths -> inspect Prolog and Python failures independently -> repeat.

Acceptance

Exact Prolog-RLM revision is recorded and reproducible.
Python bridge contains transport/schema/integration only, not duplicated policy logic.
Synchronous compile call is bounded by deadline and output size.
Prolog crash/timeout/malformed result cannot corrupt Agent Zero state.
rlm_context_budget path has a focused conformance suite.
Prompt compiler remains feature-gated until exact known regressions are covered.
Symbolic decision fingerprint/reasons are visible to telemetry/evals.
Upgrade procedure requires conformance suite before changing the pinned revision.
_prolog_rlm is the only discoverable Prolog-RLM plugin.
Context compilation and runtime behavior are configured through that one plugin.
Simple turns begin from a roughly 500-token symbolic working projection and expand only when justified.
Persistent symbolic memory KBs are accessible through the Prolog-RLM runtime when enabled.
Provider-specific tool-choice requirements are normalized and covered by live Docker CI (#58).

Non-goal

Do not embed the entire Agent Zero loop into Prolog in this epic.

Mirrored from lost-rob0t/a0-symbolics#8 via tracker sync.

Parent: #1 ## Goal Consume Prolog-RLM as a pinned reusable symbolic library through a thin Python bridge, without copying/reimplementing its policy semantics inside Agent Zero. ## Bootstrap integration Prefer a persistent SWI-Prolog sidecar or narrowly supervised synchronous process boundary with typed JSON messages. Keep process/language failure isolated from the Agent Zero framework runtime. Initial bridge contract: Input: ```text {task, user_message, recent_turns, tool_metadata, memory_candidates, project_context_candidates, active_state, budget} ``` Output: ```text {selected_context_units, selected_tool_ids, rejected_units_with_reasons, ledger, evidence_refs, fingerprint, warnings} ``` No output field grants tool authority. ## Dependency policy - Pin exact Prolog-RLM commit/flake input; never track moving `main` in production. - Begin with `rlm_context_budget` + tiny audited admission predicates. - Add `rlm_artifact` when focused conformance tests pass. - Gate `rlm_prompt_compiler` behind exact-path tests until its current anonymous-dict/schema regression is demonstrably fixed. - Hold critical async/subagent control flow until cancellation/time-limit propagation is proven. - Do not make bootstrap depend on conversation/evolution modules while their current regressions remain unresolved. ## Failure semantics - SWI unavailable/start failure -> explicit symbolic-unavailable state. - Invalid schema/response -> reject result, log evidence, use documented bounded fallback. - Timeout -> terminate/restart symbolic worker; never interpret timeout as empty successful selection. - Fingerprint input + output so repeated/replayed decisions are inspectable. ## 2026-08-24 convergence directive ### One Prolog-RLM plugin Agent Zero must expose **one bundled Prolog-RLM plugin**, `_prolog_rlm`. The current split between `_prolog_rlm` and `_prolog_context_compiler` is an implementation migration state, not the target architecture. Context compilation, provider-visible projection, persistent symbolic workers, completion, memory-KB integration, tools, and settings belong behind the single `_prolog_rlm` plugin boundary. Migration may temporarily preserve internal Python modules/packages to avoid import churn, but only `_prolog_rlm` may remain discoverable/configurable as a runtime plugin at completion. Required invariants: - exactly one Prolog-RLM plugin manifest is discovered; - one plugin owns enablement/configuration; - no duplicate lifecycle hooks or conflicting tool-filter hooks; - no plugin import-order dependency; - context/compiler workers may remain separate supervised processes internally when latency/isolation requires it; - plugin settings expose one coherent surface. ### 500-token starting context The symbolic provider-visible context budget starts at **500 tokens** for the minimal/default working projection. 500 is the starting/floor target for a simple turn, not permission to truncate required user input or tool protocol until the request becomes invalid. Prolog-RLM should grow context deliberately from that lean starting point based on task requirements, dependencies, evidence, and tool contracts. Tests must distinguish: - minimal/simple-turn target around 500 tokens; - required protocol/system overhead; - expanded context selected for genuinely complex tasks; - hard provider input limits. The current 16k/12k context defaults are not the target operating behavior for Symbolics. ### Provider compatibility belongs at the boundary Provider-specific request legality must be normalized before dispatch. In particular, OpenRouter routes backed by Z.AI that reject `tool_choice: required` must receive a supported value such as `auto` rather than failing with HTTP 400. Do not globally force `auto` for providers that support stronger tool-choice semantics. Capability/compatibility selection belongs in the transport/provider policy and must be covered by #58. ### Persistent Prolog KB memory integration When `_prolog_rlm` is active, persistent memory/state intended for symbolic reasoning must be available to Prolog as durable KB facts/records rather than existing only as vector-memory prose. The memory lifecycle and epistemic rules remain owned by #4. This epic owns the runtime/bridge path that makes those persistent KBs queryable by the single Prolog-RLM control plane. ## RAGE loop Review exact current Prolog-RLM commit/APIs/tests -> analyze smallest safe ABI -> generate bridge + fixtures -> execute both happy/failure paths -> inspect Prolog and Python failures independently -> repeat. ## Acceptance - [ ] Exact Prolog-RLM revision is recorded and reproducible. - [ ] Python bridge contains transport/schema/integration only, not duplicated policy logic. - [ ] Synchronous compile call is bounded by deadline and output size. - [ ] Prolog crash/timeout/malformed result cannot corrupt Agent Zero state. - [ ] `rlm_context_budget` path has a focused conformance suite. - [ ] Prompt compiler remains feature-gated until exact known regressions are covered. - [ ] Symbolic decision fingerprint/reasons are visible to telemetry/evals. - [ ] Upgrade procedure requires conformance suite before changing the pinned revision. - [ ] `_prolog_rlm` is the only discoverable Prolog-RLM plugin. - [ ] Context compilation and runtime behavior are configured through that one plugin. - [ ] Simple turns begin from a roughly 500-token symbolic working projection and expand only when justified. - [ ] Persistent symbolic memory KBs are accessible through the Prolog-RLM runtime when enabled. - [ ] Provider-specific tool-choice requirements are normalized and covered by live Docker CI (#58). ## Non-goal Do not embed the entire Agent Zero loop into Prolog in this epic. --- *Mirrored from [`lost-rob0t/a0-symbolics#8`](https://github.com/lost-rob0t/a0-symbolics/issues/8)* via tracker sync.