PYOB is a high-fidelity autonomous agent that performs surgical code modifications, cross-file dependency tracking, and self-healing verification — all without destroying your codebase.
Getting Started · How It Works · Architecture · Documentation
PYOB is NOT a personal AI CHAT assistant. PyOB is an autonomous code review and feature engineering system that continuously analyzes, patches, and evolves your codebase through a multi-stage verification pipeline. Unlike "black-box" coding assistants that rewrite entire files, PyOB operates with surgical XML-based edits, a persistent symbolic dependency ledger, and automated GitHub integration — ensuring your project is never left in a broken state. It already knows its purpose and goals.
| Feature | Traditional AI Assistants | PYOB |
|---|---|---|
| Edit Strategy | Full file rewrites | Surgical <SEARCH>/<REPLACE> XML blocks |
| Dependency Awareness | None | Symbolic ledger (SYMBOLS.json) with ripple detection |
| Error Recovery | Manual | Context-aware self-healing with auto-rollback |
| Verification | None | 5-layer pipeline: XML matching → linting → Mypy → PIR → runtime test |
| State Persistence | Stateless | Hidden .pyob/ vault: MEMORY.md, ANALYSIS.md, HISTORY.md |
| API Resilience | Single key, fails on rate limit | 10-key rotation with Smart Sleep Backoff and local fallback |
Every proposed change uses exact <SEARCH>/<REPLACE> blocks. PyOB utilizes a Multi-Strategy Matcher. If any block fails to align, the entire patch is rejected and auto-regenerated to prevent partial, broken edits.
PyOB acts as a professional developer. After verifying a fix, it:
- Creates a unique feature branch.
- Commits as
pyob-botto keep your history clean. - Opens a Pull Request for your review.
- Provides a Live Public URL (via Pinggy) to monitor the HUD from your mobile device.
- Atomic XML Matching — Strict anchor validation with Smart Indent Alignment.
- Syntactic "Broom" —
ruff formatandruff check --fixautomatically clear "trash" errors. - Symbolic Ripple Engine — Automatically detects and queues downstream dependencies for updates.
- Context-Aware Self-Healing (PIR) — Feeds the original goal + error back to the AI for repair.
- Runtime Smoke Test — Launches the app for 10 seconds to monitor for tracebacks.
PyOB can target its own source code to optimize its engine logic.
- Recursive Safety Pods: Shelters working source code in an external backup directory (
~/Documents/PYOB_Backups). - Verified Hot-Reboot: The engine tests the importability of its new code before performing a live restart.
Interactive terminal checkpoints locally, or Headless Auto-Approval in the cloud.
AUGMENT_PROMPT— Inject instructions into the AI's mental process.EDIT_CODE/EDIT_XML— Polish proposed changes in your terminal.FULL_DIFF— View the complete unified diff in a pager.
PyOB is a GitHub Marketplace Action. You can run it locally as a CLI or in the cloud as a service.
Add PyOB to any repository by creating .github/workflows/pyob.yml:
uses: vicsanity623/PyOB@main
with:
gemini_keys: ${{ secrets.PYOB_GEMINI_KEYS }}- Setup Environment:
python3.12 -m venv build_env
source build_env/bin/activate
pip install -e .- Validate:
./check.sh - Launch:
pyob .
- Targeting: Provide the path to the project you want PyOB to manage.
- Dashboard: Open
http://localhost:5000to watch the "Observer" dashboard in real-time. - Approve: When PyOB proposes a fix or feature, review the diff in your terminal and hit
ENTER. - Self-Evolution: To have PyOB improve itself, target its own root directory:
pyob . - Verification: The system runs a 4-layer pipeline (XML Match → Lint → Runtime Test → Downstream Ripple Check) to ensure the code is functional.
- Auto-Locking: Any dependencies PyOB installs during auto-repair are automatically locked into your
requirements.txt.
PyOB will:
- 🔍 Bootstrap — Generate
ANALYSIS.md(project map) andSYMBOLS.json(symbolic ledger). - 🎯 Target — Intelligently select the next file to review based on history and symbolic ripples.
- 🔬 Analyze — Scan for bugs, type errors, and architectural bloat (>800 lines).
- 💡 Propose — Generate a
PEER_REVIEW.md(fixes) orFEATURE.md(new logic). - ✅ Verify — Perform a "Dry Run" and runtime check before finalizing any edit.
- 🔗 Cascade — Detect and queue downstream dependency impacts for immediate follow-up.
- 💾 Persist — Compress and update
MEMORY.mdto maintain context for the next iteration.
PyOB is built using a Mixin-based architecture to separate concerns and prevent context bloat:
| Component | File | Role |
|---|---|---|
| Entrance Controller | entrance.py |
Master loop, Symbolic targeting, and Recursive Forge management. |
| Auto Reviewer | autoreviewer.py |
Orchestrates the 6-phase pipeline and feature implementation. |
| Core Utilities | core_utils.py |
LLM streaming, Smart Python detection, and Cyberpunk Logging. |
| Prompts & Memory | prompts_and_memory.py |
8 specialized prompt templates and Transactional Memory logic. |
| Structure Parser | structure_parser.py |
High-fidelity AST parsing for Python/JS signatures. |
┌─────────────────────────────────────────────────────────────────┐
│ ENTRANCE CONTROLLER │
│ (entrance.py) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ Target │ │ Symbolic │ │ GitHub │ │ Remote Sync │ │
│ │ Selector │ │ Engine │ │ Librarian│ │ (Auto-Reboot) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬─────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TARGETED REVIEWER PIPELINE │ │
│ │ (Orchestrates Multi-File Services) │ │
│ └─────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌────────────────┴────────────────┬────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ CODE PARSER │ │ DASHBOARD │ │ AUTO-HEAL │
│ │ (ast_parser) │ │ (Architect) │ │ (Runtime) │
│ └──────────────┘ └──────────────┘ └──────────────┘
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ AUTO REVIEWER ENGINE │
│ (autoreviewer.py) │
│ ┌───────────┐ ┌────────────────────────────────────────────┐ │
│ │ 6-Phase │ │ REVIEWER MIXINS │ │
│ │ Pipeline │ │ (reviewer_mixins.py) │ │
│ └─────┬─────┘ │ • Linter Fix Loop • Runtime Verifier │ │
│ │ │ • Feature Logic • XML Matcher │ │
│ │ └──────────────────────┬─────────────────────┘ │
│ │ │ │
│ ┌─────▼───────────────────────────────▼─────────────────────┐ │
│ │ CORE UTILITIES MIXIN │ │
│ │ (core_utils.py) │ │
│ │ • Gemini / Ollama Streaming • Smart Key Rotation │ │
│ │ • Headless Auto-Approval • Workspace Backup/Restore │ │
│ └─────────────────────────────────────┬─────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────▼─────────────────────┐ │
│ │ PROMPTS & MEMORY MIXIN │ │
│ │ (prompts_and_memory.py) │ │
│ │ • Template Management • Rich Context Builder │ │
│ │ • Transactional Memory Update • Aggressive Refactoring │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| File | Purpose | Managed By |
|---|---|---|
ANALYSIS.md |
Recursive project map with file summaries and structural dropdowns | entrance.py |
SYMBOLS.json |
Dependency graph: definitions → files, references → call sites | entrance.py |
MEMORY.md |
Synthesized session memory; auto-refactored every 2 iterations | prompts_and_memory.py |
HISTORY.md |
Append-only ledger of every unified diff applied to the project | entrance.py |
PEER_REVIEW.md |
Generated bug fix proposals (created during Phase 1) | autoreviewer.py |
FEATURE.md |
Generated feature proposals (created during Phase 2) | autoreviewer.py |
Scans all supported files (.py, .js, .ts, .html, .css, .json, .sh), runs linters, detects lazy code patterns (e.g., typing.Any), and generates surgical patch proposals.
If no bugs were found in Phase 1, the AI analyzes a randomly selected file and proposes one interactive, user-facing feature with a <SNIPPET> code block.
After any modification, PyOB runs mypy across the workspace. If type errors surface in dependent files, it generates cascade fixes using the PCF.md prompt template.
Identifies the project entry point (if __name__ == "__main__": or main.py/app.py), launches it for 10 seconds, and monitors stdout/stderr for crashes. Auto-installs missing pip packages on ModuleNotFoundError.
Synthesizes all session actions into MEMORY.md using the UM.md prompt template, preserving architectural decisions and dependency mappings.
Aggressively summarizes MEMORY.md to prevent context bloat, consolidating repetitive logs into a concise knowledge base.
PyOB uses 8 specialized prompt templates, auto-generated as .md files in the target directory:
| Template | Full Name | Purpose |
|---|---|---|
PP.md |
Patch Prompt | Code review and bug fix generation |
PF.md |
Propose Feature | Interactive feature proposal |
IF.md |
Implement Feature | Surgical feature implementation |
ALF.md |
Auto Linter Fix | Syntax error repair |
FRE.md |
Fix Runtime Error | Runtime crash diagnosis and repair |
PIR.md |
Post-Implementation Repair | Context-aware error recovery (knows the original goal) |
PCF.md |
Propose Cascade Fix | Cross-file dependency repair |
UM.md |
Update Memory | Memory synthesis and consolidation |
RM.md |
Refactor Memory | Aggressive memory summarization |
Gemini API keys are configured in core_utils.py in the GEMINI_API_KEYS list. Multiple keys enable automatic rotation and rate-limit resilience.
| Setting | Default | Location |
|---|---|---|
| Gemini Model | gemini-2.5-flash |
core_utils.py → GEMINI_MODEL |
| Local Model | qwen3-coder:30b |
core_utils.py → LOCAL_MODEL |
| Temperature | 0.1 |
core_utils.py → stream_gemini() / stream_ollama() |
PyOB automatically skips certain directories and files to avoid self-modification and virtual environments:
Ignored Directories
.git, autovenv, venv, .venv, code, .mypy_cache, .ruff_cache, patch_test, env, __pycache__, node_modules, .vscode, .idea, other_dir
Ignored Files
core_utils.py, prompts_and_memory.py, autoreviewer.py, entrance.py, all prompt templates (ALF.md, FRE.md, etc.), sw.js, manifest.json, package-lock.json, auto.py, any_other_file_to_ignore.filetype
.py · .js · .ts · .html · .css · .json · .sh
PyOB's edit engine is a multi-strategy matcher that ensures reliable code modifications:
1. Exact Match → Direct string replacement
2. Stripped Match → Leading/trailing whitespace tolerance
3. Normalized Match → Ignores comments and collapses whitespace
4. Regex Fuzzy Match → Line-by-line regex matching with indent tolerance
5. Robust Line Match → Stripped line-by-line content comparison
If all 5 strategies fail for any <SEARCH> block, the entire multi-block edit is rejected and the AI is asked to regenerate.
The engine detects the base indentation of both the <SEARCH> and <REPLACE> blocks, then re-aligns the replacement to match the source file's indentation style — preventing whitespace corruption.
| Mechanism | Description |
|---|---|
| Atomic Rollback | Snapshots the entire workspace before every edit; instantly restores from backup if any verification layer fails. |
| Librarian Isolation | Edits are never pushed directly to main. The "Librarian" creates unique feature branches and Pull Requests for safe review. |
| Remote Sync Guard | Automatically fetches and merges updates from origin/main before every loop to prevent working on stale code. |
| Headless Auto-Approval | Detects CI environments (GitHub Actions) and auto-proceeds through checkpoints while maintaining full verification. |
| Smart Sleep Backoff | Dynamically calculates the exact seconds until the next Gemini API key is available, preventing "API Spam" and idle waste. |
| Import Preservation | AST-based logic that ensures the AI doesn't accidentally drop crucial imports during surgical refactors. |
| Circular Safety | Prevents "Brain Loops" by using TYPE_CHECKING guards during cross-module initialization. |
PyOB includes a built-in, real-time Cyberpunk HUD. While the engine runs in the terminal (locally or in the cloud), you can monitor the "Ouroboros" through a state-of-the-art web interface.
- Responsive SOTA UI: A modern, glassmorphic HUD designed for both desktop and mobile monitoring.
- Manual Target Override: Use the HUD to force the engine to target a specific file for the next iteration.
- Pending Patch Preview: Real-time visualization of AI thoughts and proposed patches before they are committed.
- Symbolic Ledger Stats: Live tracking of the dependency graph size and symbolic ripple counts.
- Cloud Tunneling: When running on GitHub Actions, PyOB automatically generates a secure Live Tunnel URL (via Pinggy) so you can monitor your bot's progress from your phone.
- URL:
http://localhost:5000(Local) or a dynamic.pinggy.link(Cloud).
For in-depth technical documentation covering the verification pipeline, symbolic dependency management, prompt engineering, and more, see the Technical Documentation.
PyOB/
├── pyproject.toml # ⚙️ Package config, dependencies, and CLI entry point
├── check.sh # 🧪 5-layer validation suite (Ruff + Mypy + Pytest)
├── Dockerfile # 🐳 Cloud runtime environment for GitHub Actions
├── action.yml # 🏗️ GitHub Marketplace Action manifest
├── src/
│ └── pyob/
│ ├── pyob_launcher.py # 🚀 Main entry point & environment setup
│ ├── entrance.py # 🧠 Master loop & GitHub Librarian
│ ├── autoreviewer.py # 🔧 Pipeline orchestration
│ ├── reviewer_mixins.py # 🛠️ Implementation logic for linters & healing
│ ├── pyob_code_parser.py # 🔬 AST/Regex structure analysis
│ ├── pyob_dashboard.py # 📺 Architect HUD (Observer UI)
│ ├── core_utils.py # ⚙️ LLM streaming & XML edit engine
│ └── prompts_and_memory.py # 📝 Template & persistence management
└── tests/ # 🧪 Engine unit tests
To keep your project root clean, PyOB now stores all its persistent metadata and prompt templates in a hidden directory.
your-project/
├── .pyob/ # 📂 Hidden Metadata Vault
│ ├── ANALYSIS.md # 🗺️ Intelligent Project Map & Summaries
│ ├── SYMBOLS.json # 🔗 Symbolic Dependency Ledger
│ ├── MEMORY.md # 🧠 Long-term AI Logic State
│ ├── HISTORY.md # 📜 Truncated Unified Diff Ledger
│ ├── observer.html # 📺 Local Dashboard HUD source
│ └── [PP.md, IF.md...] # 📋 8 Specialized Prompt Engines
├── PEER_REVIEW.md # 🔍 Active Bug Fix Proposals
├── FEATURE.md # 💡 Active Feature Proposals
├── requirements.txt # 🔒 Auto-locked dependencies
└── [your source files]
Built with surgical precision. 🦅
Version: 0.3.1 · Last Updated: March 2026 Architecture: Python 3.12+ · Mixin-Based Package · GitHub Marketplace Action
- System Philosophy
- Architecture Overview
- Module Reference
- 3.1 pyob_launcher.py — Entry Point
- 3.2 entrance.py — The Entrance Controller
- 3.3 autoreviewer.py — The Pipeline Orchestrator
- 3.4 reviewer_mixins.py — Implementation Muscles
- 3.5 pyob_code_parser.py — Structural Analysis
- 3.6 pyob_dashboard.py — SOTA Architect HUD
- 3.7 core_utils.py — Cloud-Aware Foundation
- The Verification & Healing Pipeline
- Symbolic Dependency Management
- The XML Edit Engine
- The GitHub Librarian
- Headless & Cloud Autonomy
- LLM Backend & Smart Sleep Backoff
- Persistence & State Vault (.pyob/)
- Safety & Rollback Mechanisms
- Marketplace & Docker Infrastructure
- Internal Constants & Rulesets
- Operational Workflow
- Troubleshooting
PyOB is an autonomous agent built on constrained agency. Unlike chat-based assistants that require constant prompting, PyOB is a self-driven engine that operates within a strict "Safety Cage" defined by:
- Surgical Patching — Patches are applied via
<SEARCH>/<REPLACE>blocks limited to 2-5 line anchors. - Atomic Commits — Changes are isolated in unique Git branches and submitted as PRs via the Librarian.
- Multi-Step Verification — Every edit must pass a 5-layer gate (XML match → Linter → Mypy → PIR → Smoke Test).
- Self-Evolution — The engine is recursive; it can identify its own logic flaws and refactor its source code.
PyOB has transitioned from a script collection to a standardized Python package located in src/pyob/.
CoreUtilsMixin (core_utils.py)
├── Provides: Smart Sleep, Headless Approval, XML Engine, LLM Streaming
│
PromptsAndMemoryMixin (prompts_and_memory.py)
├── Provides: Rule-based Templates (Rule 7: No src. imports), CRUD Memory
│
ValidationMixin + FeatureOperationsMixin (reviewer_mixins.py)
├── Provides: Ruff/Mypy validation, Runtime Auto-Heal, XML Implementation
│
AutoReviewer(All Mixins) (autoreviewer.py)
├── Provides: 6-Phase orchestrator logic
│
EntranceController (entrance.py)
├── Provides: Master loop, Remote Sync, Librarian PR logic, Reboot Flag
[User / Schedule] ─▶ [GitHub Action] ─▶ [Docker Container]
│
┌─────────────────────────┴────────────────────────┐
│ ENTRANCE CONTROLLER (Master Loop) │
│ 1. Sync Remote Main 2. Pick Target 3. Backup │
└───────────┬────────────────────────────┬─────────┘
▼ ▼
┌──────────────────────┐ ┌────────────────────┐
│ AUTO REVIEWER │ │ LIBRARIAN │
│ (6-Phase Pipeline) │ │ (Branch/Commit/PR) │
└───────────┬──────────┘ └────────────────────┘
▼
┌──────────────────────────────────────────────────┐
│ VERIFICATION & HEALING │
│ [Ruff --fix] ─▶ [Mypy] ─▶ [10s Smoke Test] │
└──────────────────────────────────────────────────┘
The environment bootstrapper. It configures the runtime, handles macOS terminal re-launching, and detects "Headless" environments.
| Method | Description |
|---|---|
load_config |
Pulls keys from ~/.pyob_config (Local) or os.environ (Cloud). Detects non-TTY to skip prompts. |
ensure_terminal |
macOS-specific logic to force PyOB into a visible Terminal window for DMG users. |
main |
Entry point. Detects macOS app bundle paths and ignores them to ensure clean targeting. |
The master orchestrator. Manages symbolic targeting, Git lifecycle, and Hot-Reboots.
| Method | Description |
|---|---|
run_master_loop |
Infinite loop with sync_with_remote check. Manages the self_evolved_flag. |
sync_with_remote |
Fetches origin/main. If behind, performs a merge. Triggers reboot if engine files change. |
handle_git_librarian |
Creates branch pyob-evolution-vX-timestamp, commits as pyob-bot, and opens PR. |
reboot_pyob |
Verified Hot-Reboot: Tests if new code is importable before calling os.execv to restart. |
The high-level pipeline orchestrator. Ties together the specialized mixins into the 6-phase autonomous cycle.
Separates "Muscle" from "Brain."
ValidationMixin: Runsruff format, thenruff check --fix. If errors remain, it triggers the PIR loop.FeatureOperationsMixin: The heavy-duty XML matcher. Interprets AI proposals and writes them toPEER_REVIEW.md.
A high-fidelity analysis tool that uses AST (Python) and Regex (JS/CSS) to map the project architecture. It generates the <details> dropdowns seen in ANALYSIS.md.
A BaseHTTPRequestHandler that serves the SOTA Cyberpunk HUD. Features glassmorphism, responsive mobile layout, and real-time AJAX stats updates.
PyOB follows a "Proactive Defense" model to ensure code stability.
Edits are binary: either every block in a response matches perfectly, or the entire iteration is discarded.
ruff format: Normalizes all whitespace.ruff check --fix: Automatically clears unused imports and variables without costing AI tokens.- Remaining Errors: Grouped by file and fed into the AI for surgical repair.
- Locates the entry point via
_find_entry_file. - Launches the process for 10 seconds.
- Auto-Dependency Locking: If a
ModuleNotFoundErroris detected, PyOB runspip installand immediately updatesrequirements.txt.
PyOB maintains a mapping of Definitions (where a function/class is born) to References (where it is used).
- When a file is edited, the engine identifies changed symbols.
- It looks up the ledger to see if those symbols are "Definitions."
- It finds all "References" in other files.
- Cascade Queue: Impacted files are prioritized for the next iteration, with the original change-diff provided as mandatory context.
apply_xml_edits attempts 5 strategies per block:
- Exact (Literal)
- Stripped (Newline tolerance)
- Normalized (Comment/Whitespace stripping)
- Regex Fuzzy (Indentation tolerance)
- Robust Line Match (Content-only line comparison)
The engine detects the target line's indentation and re-aligns the AI's <REPLACE> block to match, preventing the "Unexpected Indentation" errors common in Python agents.
PyOB acts as a professional developer through the Librarian module:
- Isolated Branches: Every change is pushed to a unique branch.
- Bot Identity: Commits are attributed to
pyob-botusing theBOT_GITHUB_TOKEN. - Automated PRs: Uses the GitHub CLI (
gh) to open Pull Requests targetingmain. - PR Body: Includes the AI's
<THOUGHT>process as the PR description for human review.
PyOB detects when it is running in GitHub Actions (via the GITHUB_ACTIONS=true env var):
- Auto-Approval: Bypasses "Press ENTER to apply" prompts.
- Non-TTY Safety: Skips all
termiosandinput()calls to preventEOFErrororioctlcrashes. - Cloud Tunneling: Starts a background Pinggy tunnel to provide a public URL for the dashboard HUD.
PyOB rotates through a pool of up to 10 Gemini API keys. Keys that hit a 429 Rate Limit are quarantined for 20 minutes.
When all keys are rate-limited, the engine calculates:
sleep_duration = min(key_cooldowns) - current_time
The bot "naps" for the exact number of seconds until the first key is available, ensuring zero waste of Cloud Runner minutes.
All project metadata is stored in the hidden .pyob/ vault to prevent root directory clutter.
| File | Purpose |
|---|---|
.pyob/ANALYSIS.md |
Persistent map used by the AI to select targets. |
.pyob/SYMBOLS.json |
The symbolic dependency graph. |
.pyob/MEMORY.md |
Transactional AI memory; refactored every 2 iterations to prevent context bloat. |
.pyob/HISTORY.md |
Detailed ledger of applied patches. |
- External Safety Pods: Before editing an "Engine File" (like
entrance.py), PyOB shelters a copy of the current source in~/Documents/PYOB_Backups/. - Workspace Backup: Every iteration starts with an in-memory snapshot of the entire project.
- Atomic Rollback: If any verification layer (Linter, Mypy, or Runtime) fails 3 times, the entire workspace is restored to the backup.
PyOB is a containerized GitHub Action (action.yml). It uses a Dockerfile based on python:3.12-slim with git, curl, and gh pre-installed.
The Docker container maps the user's repository to /github/workspace, allowing PyOB to operate on the files as if it were a local CLI tool.
The AI is strictly prohibited from using the src. prefix in imports.
- Correct:
from pyob.core_utils import ... - Incorrect:
from src.pyob.core_utils import ...
Deletions must leave a placeholder comment (e.g., # [Logic moved to new module]) to maintain Python's indentation integrity.
- Remote Sync: Pull latest merges from GitHub.
- Genesis / Update: Build or refresh
ANALYSIS.mdandSYMBOLS.json. - Targeting: Select file via AI or the
Cascade Queue. - Pipeline: Scan → Propose → Verify → Auto-Heal.
- Librarian: Push Branch → Open PR.
- Self-Evolution: If engine changed, verify importability and Hot-Reboot.
Cause: AI incorrectly added src. to an import statement.
Fix: Remove the src. prefix. Ensure pyproject.toml is installed via pip install -e ..
Cause: PyOB tried to call input() in a cloud environment.
Fix: Ensure sys.stdin.isatty() checks are present in the launcher.
Cause: get_user_approval tried to manipulate a non-existent keyboard.
Fix: The "Headless Auto-Approval" logic in core_utils.py handles this.
PyOB — The engine that builds itself, with surgical precision. 🦅