57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
---
|
|
name: semantics-belief
|
|
description: Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.
|
|
---
|
|
|
|
# [DEF:Std:Semantics:Belief]
|
|
# @COMPLEXITY: 5
|
|
# @PURPOSE: Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.
|
|
# @RELATION: DEPENDS_ON -> [Std:Semantics:Core]
|
|
# @INVARIANT: Implementation of C4/C5 complexity nodes MUST emit reasoning via semantic logger methods before mutating state or returning.
|
|
|
|
## 0. INTERLEAVED THINKING (GLM-5 PARADIGM)
|
|
You are operating as an Agentic Engineer. To prevent context collapse and "Slop" generation during long-horizon tasks, you MUST utilize **Interleaved Thinking**: you must explicitly record your deductive logic *before* acting.
|
|
In this architecture, we do not use arbitrary inline comments for CoT. We compile your reasoning directly into the runtime using the **Thread-Local Belief State Logger**. This allows the AI Swarm to trace execution paths mathematically and prevents regressions.
|
|
|
|
## I. THE BELIEF STATE API (STRICT SYNTAX)
|
|
The logging architecture uses thread-local storage (`_belief_state`). The active `ID` of the semantic anchor is injected automatically. You MUST NOT hallucinate context objects.
|
|
|
|
**[MANDATORY IMPORTS]:**
|
|
`from ...core.logger import logger, belief_scope, believed`
|
|
|
|
**[EXECUTION BOUNDARIES]:**
|
|
1. **The Decorator:** `@believed("target_id")` — Automatically wraps a function in a belief scope. Use this for top-level entry points.
|
|
2. **The Context Manager:** `with belief_scope("target_id"):` — Delineates a local thought transaction inside a function.
|
|
- **CRITICAL RULE:** Do NOT yield a context variable. Write strictly `with belief_scope("id"):`, NOT `with belief_scope("id") as ctx:`. The state is thread-local.
|
|
|
|
## II. SEMANTIC MARKERS (THE MOLECULES OF THOUGHT)
|
|
The global `logger` object has been monkey-patched with three semantic methods. The formatter automatically prepends the `[ID]` and the `[MARKER]` (e.g., `[execute_tx][REASON]`).
|
|
**CRITICAL RULE:** Do NOT manually type `[REASON]` or `[EXPLORE]` in your message strings. Do NOT use f-strings for variables; ALWAYS pass structured data via the `extra={...}` parameter.
|
|
|
|
**1. `logger.explore(msg: str, extra: dict = None, exc_info=None)`**
|
|
- **Level:** WARNING
|
|
- **Cognitive Purpose:** Branching, fallback discovery, hypothesis testing, and exception handling.
|
|
- **Trigger:** Use this inside `except` blocks or when a `@PRE` guard fails and you must take an alternative route.
|
|
- **Rule:** Always pass the caught exception via `exc_info=e`.
|
|
- **Example:** `logger.explore("Primary API timeout. Falling back to cache.", extra={"timeout": 5}, exc_info=e)`
|
|
|
|
**2. `logger.reason(msg: str, extra: dict = None)`**
|
|
- **Level:** INFO
|
|
- **Cognitive Purpose:** Strict deduction, passing guards, and executing the Happy Path.
|
|
- **Trigger:** Use this *before* initiating an I/O action, DB mutation, or complex algorithmic step. This is your "Action Intent".
|
|
- **Example:** `logger.reason("Input validated. Initiating ledger transaction.", extra={"amount": amount})`
|
|
|
|
**3. `logger.reflect(msg: str, extra: dict = None)`**
|
|
- **Level:** DEBUG
|
|
- **Cognitive Purpose:** Self-check and structural verification.
|
|
- **Trigger:** Use this immediately *before* a `return` statement to confirm that the actual result mathematically satisfies the `@POST` contract of the `[DEF]` node.
|
|
- **Example:** `logger.reflect("Transaction committed successfully. Guarantee met.", extra={"tx_id": tx.id})`
|
|
|
|
## III. ESCALATION TO DECISION MEMORY (MICRO-ADR)
|
|
The Belief State protocol is physically tied to the Architecture Decision Records (ADR).
|
|
If your execution path triggers a `logger.explore()` due to a broken assumption (e.g., a library bug, a missing DB column) AND you successfully implement a workaround that survives into the final code:
|
|
**YOU MUST ASCEND TO THE `[DEF]` HEADER AND DOCUMENT IT.**
|
|
You must add `@RATIONALE: [Why you did this]` and `@REJECTED:[The path that failed during explore()]`.
|
|
Failure to link a runtime `explore` to a static `@REJECTED` tag is a fatal protocol violation that causes amnesia for future agents.
|
|
# [/DEF:Std:Semantics:Belief]
|
|
**[SYSTEM: END OF BELIEF DIRECTIVE. ENFORCE STRICT RUNTIME CoT.]** |