-
Notifications
You must be signed in to change notification settings - Fork 0
Extension Blueprint
The long-term vision for the Autonomous Artificial Superintelligence Operating System (ASI-OS), a self-evolving cognitive ecosystem designed to operate autonomously on local infrastructure, hinges on its capacity to evolve through community-driven contributions. To accelerate this evolution, the system is explicitly designed to be extended. However, this openness requires a disciplined approach to prevent the degradation of its core design.
We define "architectural drift" as the gradual erosion of a system's foundational principles through uncoordinated or ad-hoc modifications. In the context of a self-evolving cognitive ecosystem, such drift poses a critical threat. It can introduce instability, compromise safety, and ultimately undermine the project's core mission: to be "Made for a better world."
This document serves as the official blueprint for all contributors. It outlines the sanctioned methods for adding new functionality, ensuring that every extension reinforces, rather than weakens, the system's architectural integrity and long-term viability. We will cover three core topics: the foundational architectural principles that must be respected, the specific pathways for extending the system, and a practical guide to maintaining system integrity with every contribution.
Before writing a single line of code, contributors must internalize the core design philosophies that govern ASI-OS. These principles are not merely suggestions; they are the non-negotiable pillars upon which the system's stability, safety, and future potential are built. Adherence to these principles is our primary defense against architectural drift and the key to building a robust, trustworthy system together.
A core design principle of ASI-OS is its strategic separation of active operation from long-term evolution. This is achieved through a dual architecture composed of two distinct components:
- The live runtime kernel (Sovereign-Loop), which handles real-time tasks and active processes.
- The offline cognitive ecosystem for skill synthesis and self-improvement, where the system can learn, evolve, and develop new capabilities.
This bifurcation is a core risk mitigation strategy. It allows for aggressive, offline experimentation and skill development in a sandbox that is physically decoupled from the stability-critical runtime kernel. This design ensures that new capabilities are developed and refined in a controlled environment before they have the potential to affect live operations, thereby preserving kernel integrity.
To enforce maintainability and a clear separation of concerns, ASI-OS mandates a professional src layout. This deliberate structure is the primary mechanism for ensuring modularity across the entire codebase and maintaining a stable contract between components.
ASI-OS/
├── manage.py # Unified CLI Entry Point (Server, Learn, Test)
├── src/ # Core Source Code
│ ├── boot.py # Runtime Kernel Entry
│ ├── agents/ # Autonomous Agents (Professor, Alpha, etc.)
│ ├── core/ # System Kernel (Switchboard, Safety, Memory)
│ ├── gpia/ # General Purpose Intelligent Agent Logic
│ ├── hnet/ # Hierarchical Neural Memory
│ └── skills/ # Skill Registry (Proprietary implementations ignored)
├── scripts/ # Operational & Maintenance Scripts
├── tests/ # Test Suite (pytest)
├── docs/ # System Documentation
└── configs/ # Configuration Files
This structure is not arbitrary; it isolates different functional parts of the system, from core kernel logic to individual agent definitions and skills. For contributors, this organization makes it significantly easier to navigate the codebase, understand where specific functionality resides, and contribute effectively without causing unintended side effects, enabling parallel development without introducing regressions.
As stated in our core project documentation, "transparency and safety are foundational pillars" of the ASI-OS design. These are not afterthoughts; they are non-negotiable constraints woven directly into the architecture, designed for responsible operation and alignment with emerging standards like the EU AI Act.
-
Safety Governor: The
src/core/safety_governor.pymodule is the designated enforcer of hardware and cognitive guardrails, preventing the system from taking unintended or harmful actions. -
Audit Trails: All autonomous actions are meticulously logged in the
data/ledger/directory. This creates immutable audit trails, ensuring full traceability and transparency for analysis. -
Human Oversight: The
manage.pycommand-line interface is intentionally designed as the single entry point for all critical system operations, ensuring human-in-the-loop control. - Privacy by Design: The system is built for local, offline operation. This is a core design choice to keep sensitive user data and proprietary skills secure on local infrastructure, guaranteeing user privacy and data sovereignty.
These robust safety features provide the stable foundation necessary to confidently open the system to community-driven development. The following sections detail how to build upon this foundation correctly.
The modular architecture of ASI-OS provides three distinct and well-defined pathways for adding new functionality. This design is intentional, allowing contributors to add value at different levels of the system's hierarchy while preserving the integrity of the core. The following subsections provide a practical guide for each pathway, detailing its purpose and its precise location within the professional src layout.
A "Skill" in the ASI-OS context is a discrete, self-contained capability. To add one, create a new Python module within the src/skills/ directory. The system's loader is designed to automatically discover and register any valid skill placed here, requiring no modifications to the core kernel. This pathway is the primary method for teaching the system new tasks while maintaining a clean separation between capabilities and the core execution logic.
An "Agent" is a component that encapsulates new autonomous behaviors and logic. These definitions must be placed in the src/agents/ directory. This directory already contains the core Professor and Alpha agents, which serve as examples within the system's multi-agent swarm. This pathway is intended for contributors looking to define entirely new modes of autonomous operation or reasoning that can be integrated into the broader cognitive architecture.
"Scripts" are tools for creating custom operational tasks, maintenance utilities, and other forms of automation that support the system rather than being part of its cognitive core. All operational scripts must be placed in the top-level scripts/ folder. To interface cleanly with the core system, developers must use the standardized import block to access src/ components. This ensures that scripts remain decoupled from the core source code while still being able to leverage its functionality in a controlled manner.
Knowing the correct directory for a new feature is only half the battle. A true contribution reinforces the system's architecture, making it stronger and more maintainable. A contribution that ignores these principles introduces technical debt and contributes to architectural drift. Before submitting any contribution, review this checklist to ensure your work is clean, sustainable, and aligned with the project's vision.
Use the directory structure as your guide. Each folder has a distinct purpose; respecting these boundaries is critical.
- ✅ DO: Place new, self-contained capabilities that the system can execute in
src/skills/. - ✅ DO: Define new autonomous reasoning loops or behavioral logic in
src/agents/. - ❌ DON'T: Modify the
src/core/kernel to add a niche capability that should be implemented as a skill. The kernel is reserved for system-wide concerns such as the core execution loop, memory management, and the safety governor's enforcement logic.
Your new code must operate within the established safety and governance guardrails.
- Ensure any new autonomous actions or agent behaviors integrate with the audit trail system by logging their operations to
data/ledger/. - All new logic must respect the constraints imposed by the
src/core/safety_governor.py. It should not attempt to bypass or disable these fundamental safety mechanisms.
The manage.py script is the sole, sanctioned entry point for system operations. This upholds the human-in-the-loop principle.
- If your new extension requires human initiation, control, or configuration (e.g., launching a specialized learning session or a new maintenance task), it should be exposed as a new command or option within the
manage.pyCLI. - Avoid creating separate, standalone scripts to launch or manage core processes. Centralizing control through
manage.pyensures a consistent and predictable operational experience.
The long-term success of ASI-OS depends on a disciplined, community-wide commitment to its architectural principles. This blueprint provides a clear path for contribution, ensuring that as the system grows in capability, it also grows in stability and integrity.
By channeling new functionality through the three primary extension pathways—Skills, Agents, and Scripts—and by rigorously adhering to the principles of modularity and safety, we can collectively build a more powerful system without sacrificing its core design. Every disciplined contribution is a step toward fulfilling our ambitious vision: building a robust, secure, and beneficial AGI "Made for a better world."