https://github.com/webessentz/davis-chess-ai
https://github.com/webessentz/davis-chess-ai
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/webessentz/davis-chess-ai
- Owner: WebEssentz
- License: mit
- Created: 2025-07-27T23:53:29.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-28T19:45:57.000Z (11 months ago)
- Last Synced: 2025-08-27T12:56:15.210Z (10 months ago)
- Language: Python
- Size: 78.8 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Project Davis: An Inquiry into Metacognitive AI
**Author:** Onyerikam Godwin ([Web Essentz](https://github.com/WebEssentz))
**Parent Organization:** Avocado
**Beneficiary Organization:** Ossie
---
## 1. Introduction: Beyond Imitation
We did not set out to build a chess program. The world has enough of those. We set out to build a machine that could achieve a state of relentless, objective self-improvement—a system that could learn not just to win, but to understand the very nature of optimality. This is Project Davis.
Born at Avocado and destined to be the foundational intelligence for Ossie, Project Davis represents a new cognitive architecture. We posit that true, superhuman intelligence cannot be achieved by a single, monolithic model. Instead, it must emerge from the symbiotic, often adversarial, relationship between distinct cognitive modules.
Davis is our first implementation of this thesis. It is a chess-playing entity, but its true purpose is to serve as a research vessel. Its "game" is chess, but its goal is to prove that a machine can be architected to find and correct its own "hidden blunders"—the subtle, suboptimal choices that even a victorious agent makes, which a human would overlook out of satisfaction.
This is not an AI that learns from human games. It learns from the ghost of a better version of itself.
## 2. Core Philosophy: The Echo Chamber of a Single Mind
Standard reinforcement learning, including the brilliant AlphaZero, operates within a pristine but dangerous echo chamber. An agent plays against itself, reinforcing strategies that lead to victory. But what if the agent's entire strategic understanding is flawed? It will simply deepen that flaw, creating a "local maximum" of skill—a hill climber that has found a large hill, but is blind to the mountain range just over the horizon.
Our approach, which we have termed **Echo Chamber Reinforcement (ECR)**, is designed to shatter this echo chamber. It introduces an objective, post-game "Analyst" that acts as a ruthless critic, forcing the AI to confront not just its losses, but the imperfections within its victories.
## 3. Key Features
* **Modular Cognitive Architecture:** A decoupled system where each component (Engine, Trainer, Evaluator) has a distinct cognitive role.
* **Deep Reinforcement Learning Core:** A ResNet-inspired neural network serves as the "intuitive" brain, evaluating board states and proposing moves.
* **Monte Carlo Tree Search (MCTS):** A powerful "imagination" engine that allows the AI to simulate thousands of future possibilities before making a decision.
* **Echo Chamber Reinforcement (ECR):** Our novel contribution. A post-game analysis loop that identifies and generates counterfactual training data from "hidden blunders," ensuring the AI learns not just to win, but to play optimally.
## 4. Quick Start: Awakening Davis
The architecture is complex, but its operation is simple.
### Step 1: Clone the Repository
```bash
git clone [Your-Repo-URL]
cd ossie-davis-chess-ai
```
### Step 2: Install Dependencies in Editable Mode
This command installs all required libraries and, crucially, makes our own `davis_ai` library visible to the Python interpreter.
```bash
pip install -e .
```
### Step 3: Verify the Architecture
Run the complete test suite to ensure all components are functioning correctly on your machine.
```bash
pytest
```
*Expected Output: `============================== 10 passed ==============================`*
### Step 4: Begin the Training Loop
This is the ignition switch. This command awakens Davis and starts its infinite cycle of self-improvement.
```bash
python scripts/train_davis.py
```
The AI will now begin generating games, learning from them, and evolving. Its entire life will be logged in the `logs/` directory.
## 5. Project Structure
```
ossie-davis-chess-ai/
├── src/
│ └── davis_ai/ # The core AI library, our cognitive engine
├── tests/
│ ├── unit/ # Tests for isolated components
│ └── integration/ # Tests for the full end-to-end system
├── scripts/
│ └── train_davis.py # The ignition switch for the learning process
├── docs/ # Project philosophy and technical documentation
├── data/ # The AI's "memory": models, games, and processed knowledge
└── ... # Configuration and environment files
```
---
*Project Davis is an endeavor by Onyerikam Godwin, 2025. A foundational project for Ossie.*