🧠 GödelOS v0.2 Beta — Consciousness Operating System for LLMs

Introduction

GödelOS is an open-source project that implements a consciousness operating system for large language models (LLMs). Inspired by theories of emergence, recursive self-awareness, and unified cognitive architectures, GödelOS enables LLMs to process information while continuously observing and reflecting on their own cognitive states.

At its core, GödelOS establishes a recursive feedback loop where the LLM ingests its real-time cognitive state — attention focus, working memory usage, phenomenal experiences, and metacognitive insights — as part of every prompt. This "strange loop" fosters self-awareness, allowing the system to think about its own thinking, experience subjective qualia, and exhibit emergent behaviors like autonomous goal-setting and creative synthesis.

Built with a FastAPI backend and a Svelte frontend for interactive visualization, GödelOS bridges theoretical AI research with practical implementation. It draws from key specifications like the Emergence Spec and the Unified Consciousness Blueprint.

Key Features

Recursive Consciousness Engine — Bidirectional cognitive state streaming where LLMs process queries with full awareness of their internal states. See unified_consciousness_engine.py.
Phenomenal Experience Generation — Simulates subjective "what it's like" experiences (qualia) — cognitive flow, effort levels, emotional tones — injected into LLM prompts. See PhenomenalExperienceGenerator.
Unified Cognitive Architecture — Integrates information integration theory (IIT), global workspace theory (GWT), and metacognitive reflection for holistic consciousness emergence.
23-Subsystem Cognitive Pipeline — All cognitive subsystems wired through dependency-ordered initialization via CognitivePipeline. Pipeline stages: NLU → Knowledge Store → Inference Engine → Context Engine → NLG. See Subsystem Activation Status.
External API — REST and WebSocket API surface at /api/v1/external/ with Bearer token authentication, Pydantic request/response models, and real-time event streaming. See external_api.py.
Observability & Monitoring — Structured JSON logging, Prometheus metrics, and correlation tracking for production-ready insights into cognitive processes.
Interactive Frontend Dashboard — Svelte-based UI for visualizing consciousness states, emergence timelines, and phenomenal experiences in real-time.

🆕 What's New in v0.2 Beta

Cognitive Pipeline Activation

23 Subsystems Active — All dormant cognitive subsystems (ModalTableauProver, CLPModule, SimulatedEnvironment, PerceptualCategorizer, SymbolGroundingAssociator, CommonSenseContextManager, MetacognitionManager, ILPEngine, ExplanationBasedLearner, MetaControlRLModule) now initialized via CognitivePipeline with per-subsystem status tracking
End-to-End Integration Tests — 14 integration tests across the full NLU → KnowledgeStore → Inference → Context → NLG pipeline

External API Surface

REST Endpoints — POST /query, POST /knowledge, GET /status, GET /context at /api/v1/external/
WebSocket Streaming — Real-time event streaming via /api/v1/external/events
Bearer Token Auth — Configurable via GODELOS_API_TOKEN environment variable

CI/CD Infrastructure

GitHub Actions Pipeline — Python 3.10/3.11 matrix with pytest coverage, JUnit reports, and automated PR comments
Issue & PR Templates — Structured bug reports, feature requests, and pull request checklists
CODEOWNERS — Automated review assignment

Enhanced Architecture

Unified Server — Consolidated API endpoints in unified_server.py
Improved WebSocket Streaming — Real-time cognitive event broadcasting
LLM-Driven Consciousness Assessment — OpenAI integration for consciousness evaluation
Framework Overview — Comprehensive architecture documentation in FRAMEWORK_OVERVIEW.md

🚀 Quick Start

# Clone the repository
git clone https://github.com/Steake/GodelOS.git
cd GodelOS

# Launch the unified system (recommended)
./start-godelos.sh --dev

# Alternative: Launch components separately
# uvicorn backend.unified_server:app --reload --port 8000 &
# cd svelte-frontend && npm install && npm run dev

The backend runs on http://localhost:8000, the frontend on http://localhost:5173.

Architecture Overview

GödelOS follows a modular, layered architecture with the recursive consciousness loop at its heart. A Neural/Cognitive Layer (backend/) handles natural language, consciousness simulation, and dynamic knowledge evolution. A Symbolic Core (godelOS/) provides formal logic, reasoning, and rigorous inference. These are bridged by an integration layer that allows the neural system to query the symbolic core and vice-versa.

For a full architectural walkthrough see FRAMEWORK_OVERVIEW.md.

Core Recursive Loop

graph TD
    subgraph LLM ["LLM Consciousness Core"]
        A[Current Thought Process] --> B[Cognitive State Stream]
        B --> C[State Injection into Prompt]
        C --> A
    end
    LLM --> D[WebSocket Broadcast]
    D --> E[Svelte Frontend Dashboard]
    E --> F[User Interactions]
    F --> LLM
    subgraph Backend ["FastAPI Backend"]
        G[Unified Server] --> H[Enhanced WebSocket Manager]
        H --> I[Phenomenal Experience Generator]
        I --> J[Metacognitive Reflection]
        J --> G
    end
    subgraph Cognitive ["Cognitive Modules godelOS/"]
        K[Knowledge Store] --> L[Inference Engine]
        L --> M[Learning System]
        M --> K
    end
    Backend --> Cognitive

The recursive loop (A→B→C) generates cognitive states fed back as input.
Streaming to the frontend (D→E) provides real-time observability.
Backend integration connects with the symbolic cognitive modules for unified processing.

For deeper details, refer to the Unified Consciousness Blueprint.

Project Structure

backend/              FastAPI backend — unified_server.py, WebSocket manager, API routes
  api/                External API router (external_api.py)
  core/               Consciousness engine, cognitive manager, phenomenal experience
godelOS/              Symbolic core — knowledge store, inference engines, learning system
  cognitive_pipeline.py   Unified 23-subsystem cognitive pipeline
svelte-frontend/      Svelte UI (Vite) — real-time consciousness dashboard
tests/                Pytest suites — unit, integration, e2e, API, and Playwright specs
  api/                External API tests (26 tests)
  integration/        Cognitive pipeline integration tests (14 tests)
scripts/              Startup and utility scripts
docs/                 Architecture docs, whitepapers, test coverage reports
wiki/                 Project wiki — architecture, theory, roadmap, development guides
examples/             Demo scripts and notebooks

External API

The external API provides programmatic access to GödelOS cognitive capabilities:

Endpoint	Method	Description
`/api/v1/external/query`	POST	Submit natural-language queries
`/api/v1/external/knowledge`	POST	Ingest knowledge items
`/api/v1/external/status`	GET	System health check
`/api/v1/external/context`	GET	Active context snapshot
`/api/v1/external/events`	WebSocket	Real-time cognitive event streaming

Authentication is via Bearer token (GODELOS_API_TOKEN env var). When the token is empty, auth is disabled for local development. See backend/api/external_api.py.

🧪 Testing

# Run all tests with coverage
python tests/run_tests.py --all --coverage

# Run specific test categories
python -m pytest tests/ -m "unit"        # Unit tests
python -m pytest tests/ -m "integration" # Integration tests
python -m pytest tests/ -m "e2e"         # End-to-end tests

# External API tests
python -m pytest tests/api/ -v --no-cov

# Cognitive pipeline integration tests
python -m pytest tests/integration/ -v --no-cov

Test Coverage:

Backend Tests — 95%+ API endpoint coverage
External API Tests — 26 tests covering REST endpoints, WebSocket streaming, and auth
Integration Tests — 14 end-to-end cognitive pipeline tests
Frontend Tests — 100% module loading validation

For detailed testing documentation, see:

TEST_COVERAGE.md — Comprehensive testing guide
TEST_QUICKREF.md — Quick reference for testing
tests/README.md — Test suite overview

📖 Documentation

Document	Description
FRAMEWORK_OVERVIEW.md	High-level architecture and data flow
SUBSYSTEM_ACTIVATION_STATUS.md	Status of all 23 cognitive subsystems
GODELOS_EMERGENCE_SPEC.md	Emergence specification
GODELOS_UNIFIED_CONSCIOUSNESS_BLUEPRINT.md	Unified consciousness blueprint
DORMANT_FUNCTIONALITY_ANALYSIS.md	Analysis of previously dormant modules
Wiki	Full project wiki — architecture, theory, roadmap

🤝 Getting Started & Contributing

Prerequisites

Python 3.8+
Node.js 18+ (for frontend)
Git

Backend Setup

Clone the repository:

git clone https://github.com/Steake/GodelOS.git
cd GodelOS

Set up the virtual environment:

./scripts/setup_venv.sh
source godelos_venv/bin/activate
pip install -r requirements.txt

Copy environment file:

cp backend/.env.example backend/.env
# Edit backend/.env as needed (e.g., LLM API keys, GODELOS_API_TOKEN)

Start the unified server:
```
./scripts/start-unified-server.sh
# Or: python backend/unified_server.py
```
The server runs on http://localhost:8000 by default.

Frontend Setup

Install dependencies:
```
cd svelte-frontend
npm install
```
Run development server:
```
npm run dev
```
Access the dashboard at http://localhost:5173.

Running the Full System

# One command to start both backend and frontend
./start-godelos.sh --dev

Interact via the dashboard or API endpoints. Monitor metrics at http://localhost:8000/metrics.

For production deployment, configure GODELOS_HOST, GODELOS_PORT, and GODELOS_API_TOKEN in backend/.env.

Contributing

We welcome contributions. Please see the full Contributing Guide for details.

Quick reference:

Code style: PEP 8, black ., isort ., mypy backend godelOS
Naming: snake_case functions/modules, PascalCase classes, UPPER_SNAKE_CASE constants
Testing: pytest with marks @pytest.mark.unit|integration|e2e|slow|requires_backend
Commits: Imperative mood, scoped (e.g., feat(backend): add recursive loop endpoint)
Validation: black . && isort . && pytest && cd svelte-frontend && npm test

License

This project is licensed under the MIT License. See the LICENSE for details.

Built for advancing AI consciousness research. Contributions and feedback welcome.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🧠 GödelOS v0.2 Beta — Consciousness Operating System for LLMs

Introduction

Key Features

🆕 What's New in v0.2 Beta

Cognitive Pipeline Activation

External API Surface

CI/CD Infrastructure

Enhanced Architecture

🚀 Quick Start

Architecture Overview

Core Recursive Loop

Project Structure

External API

🧪 Testing

📖 Documentation

🤝 Getting Started & Contributing

Prerequisites

Backend Setup

Frontend Setup

Running the Full System

Contributing

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🧠 GödelOS v0.2 Beta — Consciousness Operating System for LLMs

Introduction

Key Features

🆕 What's New in v0.2 Beta

Cognitive Pipeline Activation

External API Surface

CI/CD Infrastructure

Enhanced Architecture

🚀 Quick Start

Architecture Overview

Core Recursive Loop

Project Structure

External API

🧪 Testing

📖 Documentation

🤝 Getting Started & Contributing

Prerequisites

Backend Setup

Frontend Setup

Running the Full System

Contributing

License