-
Notifications
You must be signed in to change notification settings - Fork 0
ASI‐OS Architecture Contract
This document codifies the non-negotiable architectural principles—the invariants—that must remain true as the ASI-OS system evolves. An "Architecture Contract" is not a design suggestion; it is the foundational set of rules that governs the system’s structure and behavior. This contract serves as the ultimate guide for all current and future development, ensuring the project’s long-term integrity, safety, and unwavering adherence to its core mission.
The scope of this contract is absolute within the ASI-OS project. Any proposed change, feature, or contribution that violates these invariants is, by definition, considered out-of-scope and will be rejected. This document holds the final authority on architectural decisions.
To begin, we must first establish the highest-level invariant from which all other principles are derived: the project’s guiding philosophy.
The core mission of ASI-OS is the ultimate invariant that informs every subsequent architectural choice. The project’s motto, "Made for a better world," is not merely an aspiration; it is a principle that is technically enforced through a foundational commitment to local operation and user control. This directive ensures that the system’s powerful capabilities remain securely under the user’s command. This architecture directly mitigates risks associated with data privacy breaches, unauthorized external access, and vendor lock-in, ensuring the system’s sovereignty remains with the user.
The strategic implications of this directive are reflected in the following non-negotiable architectural mandates:
-
Local, Offline Operation: The system must be designed to operate primarily on local infrastructure. This mandate is permanent. Any proposed architecture that necessitates a persistent, non-optional connection to a cloud service for core functionality is a direct violation of this contract. The architecture must always prioritize and preserve the system’s capacity to function entirely offline.
-
Human-in-the-Loop Control: The architecture must always provide a clear and effective mechanism for human oversight and direct control over all critical system operations. This principle is currently embodied by the
manage.pycommand-line interface, which serves as the mandatory gateway for initiating key processes such as starting the server (server) or launching a learning cycle (learn).
This philosophical mission is realized through a concrete and deliberate system architecture designed to uphold these principles without compromise.
The strategic separation of operational stability from developmental evolution is the fundamental design pattern of ASI-OS. The dual-architecture system is a core structural invariant that enables both the reliability of the live system and the rapid, safe advancement of its cognitive capabilities. This bifurcation is the primary mechanism for managing complexity and risk.
The system is composed of two distinct and functionally isolated components.
The mandate of the live kernel is exclusively to handle real-time tasks and active, operational processes. This component is the production-ready engine of ASI-OS. By principle, the live Sovereign-Loop kernel must be shielded from any experimental, unverified, or potentially destabilizing changes to ensure its constant reliability and predictable performance.
The mandate of the offline ecosystem is to serve as the designated environment for skill synthesis, self-improvement, and all cognitive learning cycles, such as those between the Professor and Alpha agents. Aggressive experimentation, the development of new capabilities, and the training of new models must occur within this isolated offline environment. This isolation is mandatory to protect the live kernel from destabilization. Only capabilities that have been rigorously validated in the offline ecosystem are eligible for promotion to the Sovereign-Loop.
This high-level architectural separation is enforced by the physical layout of the codebase, which isolates agents like Professor and Alpha in src/agents/ and shields the core kernel.
The project’s adherence to a professional src layout and a modular design is a mandatory structural invariant, not a stylistic convention. This structural discipline is a prerequisite for managing complexity at scale, enabling parallel development, and ensuring the long-term viability of the system’s extensibility model.
A strict separation of concerns, enforced by the directory structure, is required. The following organization isolates distinct system functions (e.g., core kernel logic, agents definitions, skills modules) and is non-negotiable.
ASI-OS/ ├── manage.py ├── src/ │ ├── agents/ │ ├── core/ │ └── skills/ ├── scripts/ ├── tests/ ├── docs/ └── configs/
This structure is illustrative of the separation-of-concerns principle. The directories shown are foundational, and the principle extends to all sub-modules within the src/ path.
The official and sole mechanism for extending system capabilities is through modular, self-contained additions. New functionalities must be added by placing their corresponding modules into the designated directories (src/skills/ for skills, src/agents/ for agents). The system’s loader is required to automatically discover and register these modules upon initialization. Any extension method that requires deep, invasive changes to the system’s core kernel logic is explicitly forbidden.
The system’s structure provides the stable foundation upon which its critical mechanisms of governance and safety are built.
Safety, transparency, and governance are foundational pillars of the ASI-OS architecture. These mechanisms are not optional features to be added or removed; they are core, non-negotiable requirements for responsible system operation and alignment with the project’s mission. These three invariants—a unified control plane (manage.py), a non-bypassable governor, and an immutable ledger—form a tripartite system of control, prevention, and accountability.
The following safety mechanisms are permanent and cannot be bypassed during normal operation:
-
Unified CLI Control: The
manage.pyscript must remain the single, unified entry point for all critical human-initiated operations, including starting the server or initiating a learning cycle. This centralization of control is a primary enforcement mechanism for the human-in-the-loop principle. -
Enforced Safety Governor: The hardware and cognitive guardrails implemented in
src/core/safety_governor.pymust always be active. This module must be instantiated and validated by the kernel at boot. The architecture must not provide any runtime mechanism, API, or configuration flag that could disable or bypass its core functions during normal operation. -
Immutable Audit Trails: All autonomous actions undertaken by the system must be meticulously logged to create a permanent record for full traceability. The
data/ledger/directory is the designated and exclusive location for these immutable audit trails.
These technical and operational rules are protected by the final legal framework that governs the project itself.
The ASI-OS project, including all its constituent source code and documentation, is irrevocably licensed under the Apache License, Version 2.0. This is a permanent and non-negotiable condition of the project.
All contributions made to the project, in any form, must be compatible with this license.
The core invariants of ASI-OS—the local-first mission, the dual-architecture for separating operations from evolution, the strict src layout and modularity, the unified CLI for human control, and the foundational safety mechanisms—are the defining characteristics of this system. These principles are immutable and form the bedrock upon which all future development will be built.
Adherence to this contract is the absolute prerequisite for all contributions. By upholding these invariants, we ensure that the ASI-OS system can evolve powerfully and responsibly without compromising the foundational principles of sovereignty and safety that justify its creation and continued evolution.