pip install -e

Author: Vic

.gitignore

@@ -2,6 +2,7 @@ __pycache__
 .mypy_cache
 *_cache
 .DS_STORE
+src/pyob.egg-info
 dist
 build
 ALF.md

README.md

@@ -75,20 +75,27 @@ Interactive terminal checkpoints at every stage:
 
 ---
 
-## 🚀 Getting Started
+Here is the updated **Getting Started** section for your `README.md`. 
 
-PyOB can be used either as a pre-compiled standalone application (Recommended) or by running the source code directly.
+I have refactored it to reflect the new professional `src/` layout, the Python 3.12 requirement, the `pyproject.toml` installation method, and the new `./check.sh` validation workflow.
+
+---
+
+### 🚀 Getting Started
+
+PyOB can be used either as a pre-compiled standalone application (Recommended for Users) or installed as an editable package from source (Recommended for Developers).
 
 ### 📋 Prerequisites
 
 Regardless of installation method, PyOB utilizes external tools for code verification and local LLM fallback.
 
 | Requirement | Purpose | Required? |
 |---|---|---|
+| **Python 3.12+** | Core Runtime | ✅ **Mandatory** |
 | **[Ollama](https://ollama.ai)** | Local model server (fallback) | ⚡ Recommended |
 | **`ruff`** | Python linting & formatting | ⚡ Recommended |
 | **`mypy`** | Static type checking | ⚡ Recommended |
-| **Node.js** | JavaScript syntax validation | Optional |
+| **`pytest`** | Unit testing suite | ⚡ Recommended |
 
 ---
 
@@ -97,41 +104,32 @@ Regardless of installation method, PyOB utilizes external tools for code verific
 Download the latest pre-built binaries from the **[Releases Page](https://github.com/vicsanity623/PyOB/releases)**.
 
 #### **macOS (.dmg)**
-1. **Download and Mount:** Open `PyOB-v0.2.0.dmg`.
-2. **Install:** Drag the **PyOB** icon into your `/Applications` folder.
-3. **Launch:** Open PyOB via Spotlight (`Cmd + Space` > "PyOB").
-4. **Setup:** A Terminal window will open automatically. Follow the prompts to enter your Gemini API keys and select your AI models. These settings are saved to `~/.pyob_config`.
-
-#### **Windows (.exe)**
-1. **Download:** Save `PyOB.exe` to a known directory.
-2. **Launch:** Double-click the executable or run it via PowerShell/CMD.
-3. **Setup:** Follow the on-screen prompts to configure your API keys and model preferences.
+1. **Download and Mount:** Open `Py-OB-v0.2.2.dmg`.
+2. **Install:** Drag the **Py-OB** icon into your `/Applications` folder.
+3. **Launch:** Open Py-OB via Spotlight (`Cmd + Space` > "Py-OB").
+4. **Setup:** A Terminal window will open automatically. Follow the prompts to configure your API keys.
 
 ---
 
 ### 🛠️ Option 2: Running from Source (Developers)
 
-Use this method if you wish to modify PyOB or contribute to its development.
+Use this method to modify PyOB, add features, or run the test suite. PyOB now uses a professional `src/` layout.
 
-#### **1. Environment Setup (iMac)**
+#### **1. Environment Setup**
 ```bash
 # Clone the repository
 git clone https://github.com/vicsanity623/PyOB.git
 cd PyOB
 
-brew install python@3.12
-
-# 2. Wipe the old environment
-deactivate 2>/dev/null
+# Create a clean Python 3.12 environment
 rm -rf build_env
-
-# 3. Create the 3.12 environment
 python3.12 -m venv build_env
-
-# 4. Activate and Install
 source build_env/bin/activate
+
+# Install PyOB in "Editable" mode with all dependencies
 pip install --upgrade pip
-pip install ruff mypy requests ollama pyinstaller psutil chardet charset-normalizer types-chardet
+pip install -e .
+pip install ruff mypy pytest
 ```
 
 #### **2. Local Model Preparation**
@@ -140,34 +138,42 @@ If you intend to use the local fallback feature, pull the recommended model:
 ollama pull qwen3-coder:30b
 ```
 
-#### **3. Execution**
-Run the launcher directly. On the first run, you will be prompted to configure your API keys and model settings.
+#### **3. Validation**
+Run the full validation suite (Linter + Type Checker + Tests) before running the agent:
+```bash
+./check.sh
+```
+
+#### **4. Execution**
+Once installed via `pip install -e .`, you can launch PyOB from anywhere using the global command:
+*cd into the folder you want to scan first.
+*Do not run `pyob` from the pyob root folder unless of course you want it to evolve itself..
 ```bash
-python PyOB_launcher.py
+pyob
 ```
+*To target a specific project directory immediately:* `pyob /path/to/your/project`
+*To target pyob itself run this from inside pyob root:* `pyob`
 
 ---
 
 ### 🎯 Quick Start Workflow
 
 1.  **Targeting:** Provide the path to the project you want PyOB to manage.
 2.  **Dashboard:** Open **`http://localhost:5000`** to watch the "Observer" dashboard in real-time.
-3.  **Approve:** When PyOB proposes a fix or feature, review the diff and hit `ENTER`.
-4.  **Observe:** Watch the **Cascade Queue** trigger as PyOB ripples changes through your files.
-5.  **Self-Evolution:** To have PyOB improve itself, target its own root: `python pyob_launcher.py .`
-6.  **Verification:** The system runs the 4-layer pipeline (XML Match → Lint → PIR → Runtime Test) to ensure the code is functional.
-7.  **Persistence:** Your `MEMORY.md` and `HISTORY.md` are updated to maintain context for the next iteration.
+3.  **Approve:** When PyOB proposes a fix or feature, review the diff in your terminal and hit `ENTER`.
+4.  **Self-Evolution:** To have PyOB improve itself, target its own root directory: `pyob .`
+5.  **Verification:** The system runs a 4-layer pipeline (XML Match → Lint → Runtime Test → Downstream Ripple Check) to ensure the code is functional.
+6.  **Auto-Locking:** Any dependencies PyOB installs during auto-repair are automatically locked into your `requirements.txt`.
 
+### 🔄 The Autonomous Loop
 PyOB will:
-1. 🔍 **Bootstrap** — Generate `ANALYSIS.md` (project map) and `SYMBOLS.json` (dependency graph)
-2. 🎯 **Target** — Intelligently select the next file to review based on history and dependencies
-3. 🔬 **Analyze** — Scan for bugs, lint errors, and architectural gaps
-4. 💡 **Propose** — Generate a `PEER_REVIEW.md` (bug fixes) or `FEATURE.md` (new features)
-5. ⏸️ **Checkpoint** — Wait for your approval before applying any changes
-6. ✅ **Verify** — Run the 4-layer verification pipeline and auto-heal if needed
-7. 🔗 **Cascade** — Detect and queue downstream dependency impacts
-8. 💾 **Persist** — Update `MEMORY.md` and `HISTORY.md` with session context
-9. 🔁 **Iterate** — Loop back to step 2 with a 2-minute cooldown
+1. 🔍 **Bootstrap** — Generate `ANALYSIS.md` (project map) and `SYMBOLS.json` (symbolic ledger).
+2. 🎯 **Target** — Intelligently select the next file to review based on history and symbolic ripples.
+3. 🔬 **Analyze** — Scan for bugs, type errors, and architectural bloat (>800 lines).
+4. 💡 **Propose** — Generate a `PEER_REVIEW.md` (fixes) or `FEATURE.md` (new logic).
+5. ✅ **Verify** — Perform a "Dry Run" and runtime check before finalizing any edit.
+6. 🔗 **Cascade** — Detect and queue downstream dependency impacts for immediate follow-up.
+7. 💾 **Persist** — Compress and update `MEMORY.md` to maintain context for the next iteration.
 
 ---
 

build_pyinstaller_multiOS.py

@@ -14,10 +14,13 @@ def main():
         f"--name={APP_NAME}",
         "--clean",
         "--noconfirm",
+        "--paths=src",
+        "--collect-all=pyob",
         "--hidden-import=autoreviewer",
         "--hidden-import=reviewer_mixins",
         "--hidden-import=core_utils",
         "--hidden-import=prompts_and_memory",
+        "--hidden-import=pyob.entrance",
         "--hidden-import=requests",
         "--hidden-import=ollama",
         "--hidden-import=textwrap",
@@ -32,7 +35,7 @@ def main():
         "--collect-all=ollama",
         "--collect-all=charset_normalizer",
         "--collect-all=chardet",
-        "pyob_launcher.py",
+        "src/pyob/pyob_launcher.py",
     ]
 
     if os_name == "darwin":

check.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Check if --fix argument was passed
+if [[ "$1" == "--fix" ]]; then
+    echo "🛠️  Auto-fixing issues..."
+    ruff check src/ --fix
+    ruff format src/
+    echo "✅ Fixes applied."
+    echo "-------------------------------------"
+fi
+
+echo "🚀 Starting PyOB Validation Suite..."
+
+echo "-------------------------------------"
+echo "🧹 1. Running Ruff (Linter & Imports)..."
+ruff check src/
+
+echo "-------------------------------------"
+echo "🪄  2. Running Ruff (Formatting Check)..."
+ruff format --check src/
+
+echo "-------------------------------------"
+echo "🔎 3. Running Mypy (Type Checking)..."
+mypy src/
+
+echo "-------------------------------------"
+echo "🧪 4. Running Pytest (Unit Tests)..."
+if [ -d "tests" ] && [ "$(ls -A tests 2>/dev/null)" ]; then
+    pytest tests/
+else
+    echo "⚠️  No tests found in 'tests/' directory."
+fi
+
+echo "-------------------------------------"
+echo "✅ All checks passed!"

pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyob"
+version = "0.2.2"
+description = "PyOuroBoros: An autonomous Python coding agent."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "requests",
+    "charset-normalizer",
+    "chardet",
+    "ollama"
+]
+
+[project.scripts]
+pyob = "pyob.pyob_launcher:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"] # Flake8, Pyflakes, Warnings, isort
+ignore = ["E501"]             # Ignore line length violations (let formatter handle it)
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+explicit_package_bases = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

src/pyob/__init__.py

@@ -1,31 +1,30 @@
+import ast
+import difflib
 import os
+import random
 import re
-import difflib
-import ast
 import subprocess
-import random
 import sys
 import time
 
-from core_utils import (
-    logger,
+from pyob.core_utils import (
+    ANALYSIS_FILE,
+    FAILED_FEATURE_FILE_NAME,
+    FAILED_PR_FILE_NAME,
+    FEATURE_FILE_NAME,
+    GEMINI_API_KEYS,
+    HISTORY_FILE,
     IGNORE_DIRS,
     IGNORE_FILES,
-    SUPPORTED_EXTENSIONS,
-    CoreUtilsMixin,
-    GEMINI_API_KEYS,
-    PR_FILE_NAME,
-    FEATURE_FILE_NAME,
-    FAILED_PR_FILE_NAME,
-    FAILED_FEATURE_FILE_NAME,
     MEMORY_FILE_NAME,
-    ANALYSIS_FILE,
-    HISTORY_FILE,
+    PR_FILE_NAME,
+    SUPPORTED_EXTENSIONS,
     SYMBOLS_FILE,
+    CoreUtilsMixin,
+    logger,
 )
-
-from prompts_and_memory import PromptsAndMemoryMixin
-from reviewer_mixins import ValidationMixin, FeatureOperationsMixin
+from pyob.prompts_and_memory import PromptsAndMemoryMixin
+from pyob.reviewer_mixins import FeatureOperationsMixin, ValidationMixin
 
 
 class AutoReviewer(
@@ -125,15 +124,17 @@ def build_patch_prompt(
             if custom_issues
             else ""
         )
-        return self.load_prompt(
-            "PP.md",
-            lang_name=lang_name,
-            lang_tag=lang_tag,
-            content=content,
-            memory_section=memory_section,
-            ruff_section=ruff_section,
-            mypy_section=mypy_section,
-            custom_issues_section=custom_issues_section,
+        return str(
+            self.load_prompt(
+                "PP.md",
+                lang_name=lang_name,
+                lang_tag=lang_tag,
+                content=content,
+                memory_section=memory_section,
+                ruff_section=ruff_section,
+                mypy_section=mypy_section,
+                custom_issues_section=custom_issues_section,
+            )
         )
 
     def get_valid_edit(

autoreviewer.py src/pyob/autoreviewer.pyautoreviewer.py renamed to src/pyob/autoreviewer.py

@@ -1,18 +1,19 @@
+import ast
+import json
+import logging
 import os
 import re
-import ast
+import select
+import shutil
 import subprocess
-import logging
 import sys
-import time
-import threading
-import json
-import requests
-import select
-import tty
 import termios
-import shutil
 import textwrap
+import threading
+import time
+import tty
+
+import requests
 
 try:
     import ollama

core_utils.py src/pyob/core_utils.pycore_utils.py renamed to src/pyob/core_utils.py

@@ -1,19 +1,20 @@
-import os
-import sys
 import ast
-import re
 import difflib
-import time
-import logging
 import json
-import subprocess
+import logging
+import os
+import re
 import shutil
-from http.server import BaseHTTPRequestHandler, HTTPServer
+import subprocess
+import sys
 import threading
-from autoreviewer import AutoReviewer
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
 from typing import Any
 
+from pyob.autoreviewer import AutoReviewer
+
 logging.basicConfig(level=logging.INFO, format="%(asctime)s | %(message)s")
 logger = logging.getLogger(__name__)
 
@@ -460,7 +461,7 @@ def val(text: str) -> bool:
             p = text.strip().strip("`").strip()
             return os.path.exists(os.path.join(self.target_dir, p)) and p != last_file
 
-        return (
+        return str(
             self.llm_engine.get_valid_llm_response(
                 prompt, val, context="Target Selector"
             )