Spaces:
Paused
Paused
| """Read-only, replaceable language model backend contracts. | |
| This module defines the core protocols and data types for the Language Organ, | |
| a controlled, replaceable interface between Brain-5D and external language models. | |
| The Language Organ is designed as a read-only adapter that: | |
| - Translates between symbolic text and subsymbolic SignalFrames | |
| - Never mutates Brain-5D state directly | |
| - Is replaceable (NullBackend, LlamaCppBackend, etc.) | |
| - Is fault-tolerant (failures do not stop the simulation) | |
| Design Principles: | |
| 1. The Language Organ is an optional component, not a core dependency. | |
| 2. It operates asynchronously and does not block the simulation loop. | |
| 3. It has no direct access to synapse weights or network structure. | |
| 4. All outputs are treated as data, never as runtime commands. | |
| Example: | |
| >>> from src.language_organ import NullBackend, LanguageRequest | |
| >>> backend = NullBackend() | |
| >>> request = LanguageRequest( | |
| ... request_id="req_001", | |
| ... purpose="translate", | |
| ... text="Hello, world!" | |
| ... ) | |
| >>> response = backend.infer(request) | |
| >>> print(response.text) | |
| Hello, world! | |
| """ | |
| from __future__ import annotations | |
| from dataclasses import asdict, dataclass | |
| from enum import StrEnum | |
| from typing import Any, Protocol | |
| from src.signal_processing.models import SignalFrame | |
| # ============================================================================ | |
| # Request / Response Models | |
| # ============================================================================ | |
| class LanguageOrganMode(StrEnum): | |
| """Experimental treatment applied by the language organ.""" | |
| LINGUISTIC_TRANSPORT = "LINGUISTIC_TRANSPORT" | |
| SEMANTIC_AUGMENTATION = "SEMANTIC_AUGMENTATION" | |
| class LanguageRequest: | |
| """A bounded request to the optional language organ. | |
| This represents a self-contained, immutable request for language | |
| processing. It is intentionally limited to text and optional | |
| SignalFrame data to prevent any mutation of Brain-5D state. | |
| Attributes: | |
| request_id: Unique identifier for this request (for traceability). | |
| purpose: The purpose of the request (e.g., 'translate', 'monitor', | |
| 'encode', 'decode', 'describe'). | |
| text: The input text to process. | |
| signal_frame: Optional SignalFrame for context-aware processing. | |
| """ | |
| request_id: str | |
| purpose: str | |
| text: str | |
| signal_frame: SignalFrame | None = None | |
| mode: LanguageOrganMode = LanguageOrganMode.LINGUISTIC_TRANSPORT | |
| def to_dict(self) -> dict[str, Any]: | |
| """Convert to dictionary for serialization.""" | |
| # Explicitly annotate result as dict[str, Any] to allow mixed types | |
| result: dict[str, Any] = { | |
| "request_id": self.request_id, | |
| "purpose": self.purpose, | |
| "text": self.text, | |
| "mode": self.mode.value, | |
| } | |
| if self.signal_frame is not None: | |
| result["signal_frame"] = asdict(self.signal_frame) | |
| return result | |
| class LanguageResponse: | |
| """Language-organ result. It is data, never a runtime command. | |
| This response contains only text and metadata. It must never contain | |
| commands that could mutate the Brain-5D network state. | |
| Attributes: | |
| request_id: ID of the original request (for traceability). | |
| text: The response text generated by the language model. | |
| backend_name: Name of the backend that generated the response. | |
| success: Whether the inference was successful. | |
| error: Error message if success is False, otherwise None. | |
| """ | |
| request_id: str | |
| text: str | |
| backend_name: str | |
| success: bool | |
| error: str | None = None | |
| def to_dict(self) -> dict[str, Any]: | |
| """Convert to dictionary for serialization.""" | |
| # Explicitly annotate result as dict[str, Any] to allow mixed types | |
| result: dict[str, Any] = { | |
| "request_id": self.request_id, | |
| "text": self.text, | |
| "backend_name": self.backend_name, | |
| "success": self.success, | |
| } | |
| if self.error is not None: | |
| result["error"] = self.error | |
| return result | |
| # ============================================================================ | |
| # Backend Protocol | |
| # ============================================================================ | |
| class LanguageModelBackend(Protocol): | |
| """Backend contract that deliberately exposes no Brain-5D runtime object. | |
| This protocol defines the minimal interface that any language model | |
| backend must implement. It is designed to be: | |
| 1. Replaceable – Backends can be swapped at runtime (NullBackend, LlamaCppBackend, etc.) | |
| 2. Read-only – No Brain-5D state mutation | |
| 3. Fault-tolerant – Errors are returned in the response, not raised | |
| 4. Asynchronous-capable – Inference should be non-blocking where possible | |
| The backend is intentionally decoupled from the Brain-5D runtime to | |
| prevent accidental mutation of network state. All communication is | |
| through immutable request/response objects. | |
| Example: | |
| >>> class MyBackend(LanguageModelBackend): | |
| ... @property | |
| ... def name(self) -> str: | |
| ... return "my_backend" | |
| ... def infer(self, request: LanguageRequest) -> LanguageResponse: | |
| ... return LanguageResponse( | |
| ... request_id=request.request_id, | |
| ... text=f"Processed: {request.text}", | |
| ... backend_name=self.name, | |
| ... success=True, | |
| ... ) | |
| """ | |
| def name(self) -> str: | |
| """Return the backend identifier. | |
| This should be a short, descriptive string that identifies | |
| the backend implementation (e.g., 'null', 'qwen_0.5b', 'granite_nano'). | |
| """ | |
| ... | |
| def infer(self, request: LanguageRequest) -> LanguageResponse: | |
| """Process a language request and return text data only. | |
| This method must never mutate Brain-5D state. It receives a | |
| self-contained request and returns a self-contained response. | |
| Args: | |
| request: The language request to process. | |
| Returns: | |
| A LanguageResponse containing the result or error. | |
| Raises: | |
| This method should never raise exceptions. All errors should | |
| be captured and returned in the response with success=False. | |
| """ | |
| ... | |
| # ============================================================================ | |
| # Module Exports | |
| # ============================================================================ | |
| __all__ = [ | |
| "LanguageModelBackend", | |
| "LanguageOrganMode", | |
| "LanguageRequest", | |
| "LanguageResponse", | |
| ] | |