Deployment Guide - codex-ml v0.2.0¶
Last Updated: 2026-07-11 Version: v0.2.0
Last Updated: 2026-07-11 Version: 2.0 Package: codex-ml Audience: Maintainers, DevOps engineers, production operators, users deploying the Cognitive Brain package
Table of Contents¶
- Overview
- Pre-Release Checklist
- Release Process
- Post-Release Verification
- Profile Selection Guide
- Monitoring & Observability
- Rollback Procedures
- Troubleshooting
Overview¶
This guide provides comprehensive deployment procedures for the Cognitive Brain package (codex-ml). The package is distributed in three profiles:
| Profile | Size | Use Case | Dependencies | Installation Time |
|---|---|---|---|---|
| core | 8-15 MB | Lightweight, offline, edge devices | Minimal (stdlib + hydra, pydantic) | < 2 min |
| runtime | 20-35 MB | Production ML inference, APIs | torch, transformers, ray[serve], fastapi | 5-8 min |
| full | 100+ MB | Development, testing, experimentation | All (core + runtime + dev tools) | 10-15 min |
Key Guarantees¶
- Reproducible: All dependencies locked in
uv.lock - Offline-Capable: Core profile works without network
- Verified: Hash-checked manifests and SBOMs included
- Secure: CVE governance and network policy enforcement
- Tested: Smoke tests for all profile combinations
Pre-Release Checklist¶
Timeline: 1-2 days before release Owner: Release manager or maintainer with PyPI credentials
Governance Gates (Auto-verified)¶
- P0 Gate: Lock/profile alignment verified
- Confirm
.codex/PROFILE_DRIFT_AUDIT.jsonexists - Confirm
.codex/PROFILE_DEPENDENCY_MANIFEST.mdexists -
Command:
python scripts/ci/check_profile_drift.py -
P1 Gate: Meta-tensor safety and SBOM verified
- Confirm
sbom.jsonor.codex/sbom.jsonexists - Confirm no meta-tensor initialization errors in tests
-
Command:
pytest tests/test_meta_tensor_safety.py -
P2 Gate: Deployment automation ready
- Confirm
.github/workflows/release-to-pypi.ymlexists - Confirm
.github/workflows/smoke-tests-deployment.ymlexists - Confirm
.github/workflows/pre-release-validation.ymlexists
Code Quality Gates¶
- All tests passing:
pytest tests/ -x - No type errors:
mypy src/ - No security alerts:
bandit -r src/ - No new CVEs:
pip-audit
Release Preparation¶
-
Version bumped in
pyproject.toml -
CHANGELOG.md updated with release notes
-
Release notes prepared (for GitHub release)
- Create file:
release-notes-0.1.0.md -
Include: Features, security fixes, installation instructions, known issues
-
git tag prepared (not yet pushed)
Infrastructure Ready¶
- PyPI credentials configured in GitHub Secrets
- Secret:
PYPI_API_TOKEN -
Test:
twine checkon a test build -
Build environment validated
-
Offline install tested (on all three profiles)
Documentation Ready¶
- Deployment guide reviewed (this document)
- Rollback procedures documented (see below)
- Known issues captured in release notes
- Migration guide prepared (if breaking changes)
Release Process¶
Timeline: ~15-20 minutes Owner: Release manager Prerequisites: All pre-release checklist items complete
Step 1: Create Pre-Release Validation PR (5 min)¶
- Create branch:
release/v0.2.0-prepare -
Commit changes:
git checkout -b release/v0.2.0-prepare # Bump version sed -i 's/version = "[^"]*"/version = "0.1.0"/' pyproject.toml # Update changelog (already done, but verify) # Edit CHANGELOG.md git add pyproject.toml CHANGELOG.md git commit -m "chore: Prepare v0.2.0 release" git push origin release/v0.2.0-prepare -
Open PR:
release/v0.2.0-preparemain - Wait for pre-release-validation.yml to verify:
- Version bumped
- CHANGELOG updated
-
All gates passing
-
Get code review and merge
Step 2: Create and Push Release Tag (5 min)¶
Once PR merged to main:
# Fetch latest main
git fetch origin
git checkout origin/main
# Create annotated tag
git tag -a v0.2.0 -m "Release v0.2.0 - Cognitive Brain v0.2.0-final"
# Push tag - this triggers release-to-pypi.yml
git push origin v0.2.0
Step 3: Monitor Release Workflow (10 min)¶
In GitHub Actions, monitor: Release to PyPI workflow
Watch for these steps:
- Pre-release checks (1-2 min)
- Gate verification: P0, P1, P2
- Version validation
-
Expected output: All gates verified
-
Build wheels (3-5 min)
- Multi-platform build
-
Expected output: 3 wheels × 3 platforms = 9 artifacts
-
Generate manifest (1-2 min)
- Hash calculation
-
Expected output:
RELEASE_MANIFEST.jsonwith SHA256 hashes -
Generate SBOM (1-2 min)
- Software bill of materials
-
Expected output: SBOM files for each profile
-
Verify manifest (1 min)
- Hash verification
-
Expected output: Manifest verified
-
Publish to PyPI (2-3 min)
- Upload wheels
-
Expected output: "Successfully uploaded codex-ml-0.2.1-py3-none-any.whl"
-
Create GitHub release (1 min)
- Release notes
- Asset upload
- Expected output: GitHub release created with wheels, manifest, SBOM
Failure scenarios:
- Pre-release checks fail: Gates not met
-
Action: Resolve missing gates, update version, push new tag
-
Build fails: Platform-specific issue
-
Action: Review build logs, fix issue, delete tag, push new tag
-
PyPI upload fails: Credentials or network issue
-
Action: Verify
PYPI_API_TOKENsecret, retry release workflow -
Smoke tests fail: Package doesn't install correctly
- Action: See Rollback Procedures
Post-Release Verification¶
Timeline: 5-10 minutes after release Owner: Release manager
Immediate Verification (< 1 min)¶
# Verify package on PyPI
curl -s https://pypi.org/pypi/codex-ml/0.1.0/json | jq .info.version
# Should output: "0.1.0"
Installation Test (2-3 min per profile)¶
Test on clean machine or in docker:
# Test core profile
python -m venv test-core
source test-core/bin/activate
pip install codex-ml[core]==0.2.1
python -c "from cognitive_brain.ooda import OODALoop; print(' Core profile works')"
# Test runtime profile
python -m venv test-runtime
source test-runtime/bin/activate
pip install codex-ml[runtime]==0.2.1
python -c "import torch; print(' Runtime profile works')"
# Test full profile
python -m venv test-full
source test-full/bin/activate
pip install codex-ml[full]==0.2.1
python -c "import pytest; print(' Full profile works')"
Smoke Test Verification (< 2 min)¶
Check GitHub Actions: Smoke Tests - Deployment Verification workflow
All 12 test combinations should pass: - Python 3.12, core, with-ml - Python 3.12, core, without-ml - Python 3.12, runtime, with-ml - Python 3.12, runtime, without-ml - Python 3.12, full, with-ml - Python 3.12, full, without-ml - Python 3.13, [same 6 combinations]
Monitoring Setup (5-10 min)¶
- Enable download statistics:
- Visit: https://pypi.org/project/codex-ml/#history
-
Monitor daily downloads over next 7 days
-
Setup alerts:
-
Create monitoring dashboard:
- Location:
.codex/RELEASE_METRICS_v0.2.0.json - Contents: Build duration, sizes, test results, download stats
Profile Selection Guide¶
Profile: Core¶
When to use: - Lightweight deployments (< 50 MB total) - Offline environments or air-gapped networks - Edge devices with limited resources - CI/CD pipelines that only need OODA loop - Containers where size matters
Installation:
What's included: - Essential OODA loop APIs - Configuration management (hydra, omegaconf) - Data validation (pydantic) - CLI tools - Offline-first design
What's NOT included: - ML libraries (torch, transformers) - ML inference capabilities - Development tools (pytest, mypy) - Optional extras
Performance: - Installation: < 2 minutes - Startup: < 500 ms - Memory footprint: < 100 MB - Network calls: None (if used correctly)
Verification:
Profile: Runtime¶
When to use: - Production ML inference services - API deployments (FastAPI, Flask) - Pattern recognition in production - Ray serve workers - AWS Lambda / GCP Cloud Functions
Installation:
What's included: - Core profile + all of: - PyTorch (torch) - Transformers (HuggingFace) - Datasets library - Ray[serve] for distributed inference - FastAPI for REST APIs - Network-enabled APIs
What's NOT included: - Development tools (pytest, mypy, notebooks) - Experimental features - Debug utilities
Performance: - Installation: 5-8 minutes - Startup: 2-5 seconds (first load slower due to model loading) - Memory footprint: 2-4 GB (with loaded models) - Network calls: Required (downloads models, connects to inference servers)
Verification:
Profile: Full¶
When to use: - Local development - Testing and QA - Building custom extensions - Contributing to the project - Research and experimentation
Installation:
What's included: - Runtime profile + all of: - pytest (test runner) - mypy (type checking) - black (code formatter) - ruff (linter) - sphinx (documentation) - jupyter (notebooks) - All development dependencies
What's NOT included: - CI/CD tools (typically installed separately) - Documentation build dependencies (optional)
Performance: - Installation: 10-15 minutes - Startup: 5-10 seconds - Memory footprint: 4-6 GB - Network calls: Yes (model downloads, online docs)
Verification:
Phase Objects (Planned Execution Tracks)¶
What Are Phase Objects?¶
Phase Objects are planned execution tracks included in the codex-ml package. They define multi-track deployment plans for complex operations:
- Track A-G: Sequential execution phases (A B C D E F G)
- Tasks PR: Comprehensive task roadmap (99.6 KB, 3,193 lines)
- Batch Segments: Segmented data batches for parallel processing
Accessing Phase Objects¶
Phase objects are automatically included in all installation profiles (core, runtime, full) and can be accessed via the codex_plans module:
# List all available plans
from codex_plans import list_plan_documents
plans = list_plan_documents()
for plan in plans:
print(f" {plan.name} ({plan.stat().st_size} bytes)")
Expected output:
Tasks_PR_2459.md (99647 bytes)
track_A.md (1587 bytes)
track_B.md (1462 bytes)
track_C.md (1979 bytes)
track_D.md (1695 bytes)
track_E.md (2494 bytes)
track_F.md (2902 bytes)
track_G.md (3673 bytes)
Reading a Phase Plan¶
from pathlib import Path
from codex_plans import list_plan_documents
plans = list_plan_documents()
with open(plans[0]) as f:
content = f.read()
print(f"Plan: {plans[0].name}")
print(f"Lines: {len(content.splitlines())}")
print("\n" + content[:500] + "...")
Use Cases¶
Development: - Reference implementation roadmaps - Understand deployment phasing strategy - Track multi-phase execution plans
CI/CD Integration: - Programmatically read phase definitions - Trigger phase-based workflows - Track execution state across phases
Documentation: - Generate deployment timelines - Create phase execution reports - Publish guidance for multi-phase operations
Monitoring & Observability¶
Release Metrics Collection¶
After release, the workflow automatically creates .codex/RELEASE_METRICS_v0.2.0.json:
{
"version": "0.1.0",
"released_at": "2026-07-07T15:30:00Z",
"metrics": {
"build_duration_seconds": 420,
"wheel_sizes": {
"core": 8500000,
"runtime": 25000000,
"full": 105000000
},
"smoke_tests": {
"total": 12,
"passed": 12,
"failed": 0,
"duration_seconds": 180
},
"pypi_upload_duration": 45
},
"artifacts": {
"wheels": 9,
"manifest": 1,
"sbom": 3
}
}
Download Statistics¶
Monitor PyPI downloads:
# Get last 7 days of downloads
curl -s "https://pypistats.org/api/packages/codex-ml/recent?period=week" | jq .data
Expected pattern: - Day 1-2: Slow (initial adopters) - Day 3-7: Growth (if announced) - Week 2+: Steady state
Key Metrics to Watch¶
| Metric | Expected | Alert If |
|---|---|---|
| Installation success rate | > 99% | < 98% |
| Core profile installs | 30-40% | < 20% |
| Runtime profile installs | 40-50% | < 30% |
| Full profile installs | 10-20% | > 25% |
| Average install time | 3-5 min | > 10 min |
| Issues reported | 0-2 | > 5 in first week |
Monitoring Commands¶
# Check installation stats
pip show codex-ml | grep Version
# Verify all profiles available
pip index versions codex-ml
# Check for yanked versions
curl -s https://pypi.org/pypi/codex-ml/json | jq .releases
Rollback Procedures¶
See: Rollback Checklist for detailed step-by-step procedures
Quick Rollback (< 5 minutes)¶
If critical issues found in first 2 hours:
# Quick rollback script
python scripts/deploy/rollback_release.py \
--version v0.2.0 \
--reason "Critical bug in runtime profile" \
--restore-version v0.2.0
# This:
# 1. Marks v0.2.0 as yanked on PyPI
# 2. Deletes the git tag locally and remotely
# 3. Restores v0.2.0 as latest on PyPI
# 4. Creates GitHub release noting rollback
# 5. Sends notifications to maintainers
When to Rollback¶
- Core profile doesn't import (immediate)
- OODA loop crashes on initialization (immediate)
- Network policy violated in core (immediate)
- Smoke tests fail for > 1 profile (within 30 min)
- Critical security vulnerability found (within 24 hours)
- Performance regression > 50% (discuss first)
- Optional dependency issues (non-blocking)
Troubleshooting¶
Issue: pip install codex-ml[core] fails with network error¶
Symptom: Error like "Could not fetch URL" or "No matching distribution"
Cause: PyPI network issue or package not yet indexed
Solution:
Issue: ImportError: No module named 'cognitive_brain'¶
Symptom: After install, imports fail
Cause: Package not properly installed or wrong profile
Solution:
# Verify installation
pip show codex-ml
# Verify location
python -c "import cognitive_brain; print(cognitive_brain.__file__)"
# Try reinstall
pip uninstall -y codex-ml
pip install codex-ml[core]==0.2.1
# Check Python path
python -c "import sys; print('\n'.join(sys.path))"
Issue: CLI commands (codex-ml, codex-ml-cli, codex-cli) fail with ModuleNotFoundError¶
Symptom:
Cause: The CLI module requires aries_serpent_core which wasn't included in older package builds. This was fixed in v0.2.0+.
Solution:
# Upgrade to v0.2.0 or later
pip install --upgrade codex-ml>=0.2.1
# Verify CLI works
codex-ml --help
# Or use the working smoke CLI
codex-smoke --help
If upgrade is not possible:
Issue: Runtime profile is 2GB, too large for production¶
Symptom: Storage space issues, slow deployments
Cause: Full ML dependencies including models
Solution:
# Use core profile instead
pip uninstall codex-ml
pip install codex-ml[core]==0.2.1
# If ML needed, use Docker with layer caching
# or AWS SageMaker (pre-cached)
# Or use custom lightweight profile (future)
Issue: Offline install fails: "No matching version found"¶
Symptom: Error with wheelhouse, missing transitive deps
Cause: Lockfile may be incomplete for offline use
Solution:
# Use the provided offline bootstrap script
scripts/deploy/bootstrap_offline.py \
--wheelhouse wheelhouse_core/ \
--profile core \
--python-version 3.12
Issue: Network calls detected in core profile¶
Symptom: Code makes HTTP requests despite core profile
Cause: Code not using AllowNetworkCalls context manager
Solution:
# Enable network call detection
export DETECT_NETWORK_CALLS=1
# Run code that imports cognitive_brain
python your_script.py
# Check logs for network call warnings
FAQ¶
Q: How do I know which profile to use?
A: Start with core if you only need OODA loop. Upgrade to runtime if you need ML. Use full for development.
Q: Can I install multiple profiles together?
A: Yes, they're compatible:
Q: What if I accidentally use full in production?
A: It will work, but wastes 100+ MB of disk space and install time. Consider optimization pass.
Q: Can I downgrade from runtime to core?
A: Yes, downgrade is safe:
Q: How long is v0.2.0 supported?
A: Until v0.2.0 is released (typically 6-12 months). See Support Policy.
Local Documentation Site Deployment¶
This section covers deployment of the documentation site to local development environments (127.0.0.1:8000).
Quick Start¶
# Step 1: Install MkDocs and plugins
pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin \
mkdocstrings[python] mkdocs-git-revision-date-localized-plugin
# Step 2: Start local server
cd /home/runner/work/_codex_/_codex_
mkdocs serve
# Step 3: Open browser
# Navigate to http://127.0.0.1:8000
Local Development Workflow¶
For Documentation Changes:
# Terminal 1: Start MkDocs server (hot-reload enabled)
mkdocs serve
# Terminal 2: Edit documentation in your editor
# Changes automatically reload in browser
# Edit: docs/path/to/file.md
# Result: Live preview at http://127.0.0.1:8000/path/to/file
Configuration Validation¶
Before deploying locally, verify the mkdocs.yml configuration:
# Check configuration syntax
mkdocs build --dry-run
# Full build with strict validation
mkdocs build --strict
# Output shows any configuration issues
# If no errors: Documentation is ready to serve
Testing Checklist¶
Use this checklist to validate the local deployment:
- Server Start:
mkdocs serveruns without errors - Home Page: http://127.0.0.1:8000 loads correctly
- Navigation: Sidebar navigation opens/closes properly
- Theme Toggle: Dark/light mode toggle works
- Search: Search box appears and is functional
- Internal Links: All documentation links work
- Diagrams: Mermaid diagrams render correctly
- Code Blocks: Copy button appears on code examples
- Mobile View: Site is responsive on mobile (test with browser dev tools)
- Performance: Page loads in < 2 seconds
Performance Optimization¶
Enable Caching (faster rebuilds):
# MkDocs automatically caches:
# - Plugin output
# - Generated pages
# - Static assets
# To rebuild without cache:
mkdocs build --clean
# To force cache invalidation:
rm -rf .cache/
mkdocs serve
Build Time Benchmarks:
Initial build: 15-30 seconds (full)
Subsequent builds: 2-5 seconds (incremental)
Single file change: < 1 second (hot-reload)
Troubleshooting Local Deployment¶
Issue: "Port 8000 is already in use"
# Find process using port 8000
lsof -i :8000
# Kill process
kill -9 <PID>
# Or use alternate port
mkdocs serve -a 127.0.0.1:8001
Issue: "Module not found" error
# Ensure all dependencies are installed
pip install -r requirements-docs.txt
# Or install individually
pip install mkdocs-material mkdocs-mermaid2-plugin
Issue: Diagrams not rendering (showing code block instead)
# Check Mermaid plugin is enabled in mkdocs.yml
# Verify fence is correct:
# Correct: ```mermaid
# Wrong: ```diagram
# Check markdown file has correct syntax:
mkdocs build --verbose
Issue: Changes not reflecting in browser
# Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
# Or clear browser cache:
# DevTools > Application > Cache > Clear
# If still not working, restart server:
# Press Ctrl+C to stop mkdocs serve
# Then run: mkdocs serve again
Issue: Search not working
# Search requires build to complete
# Ensure no build errors:
mkdocs build
# Then restart serve:
mkdocs serve
# Search index is now available
Deployment to GitHub Pages¶
For production deployment to https://aries-serpent.github.io/codex/:
# 1. Commit changes
git add docs/ mkdocs.yml
git commit -m "docs: update documentation"
# 2. Push to main (triggers automatic deployment)
git push origin main
# 3. GitHub Actions automatically:
# - Builds the site
# - Validates links
# - Deploys to GitHub Pages
# - Runs health checks
# - Reports status
# 4. Verify deployment succeeded
# Check Actions tab on GitHub for workflow status
# Site available at: https://aries-serpent.github.io/_codex_/
Environment Variables¶
Optional configuration via environment variables:
# Control MkDocs behavior
export MKDOCS_SITE_URL=https://aries-serpent.github.io/_codex_/
export MKDOCS_REPO_URL=https://github.com/Aries-Serpent/_codex_
# Enable strict mode (fail on warnings)
export MKDOCS_STRICT=true
# Control plugin behavior
export MKDOCS_PLUGINS_MERMAID_VERSION="10.4.0"
Advanced Usage¶
Building Static Site:
# Generate static HTML (site/ directory)
mkdocs build
# Output: site/
# Contains all HTML, CSS, JavaScript, assets
# Can be deployed to any static host
Custom Theme Features:
# Material theme features (in mkdocs.yml):
# - navigation.instant (XHR page loading)
# - navigation.tracking (URL updates)
# - navigation.tabs (top-level tabs)
# - search.suggest (search suggestions)
# - content.code.copy (copy code button)
# All features are pre-configured
# See mkdocs.yml for complete list
Documentation Site Architecture¶
127.0.0.1:8000/
/ # Home page
/evolution/ # Evolution Center
/tokens/ # Token Management
/architecture/ # Architecture docs
/deployment/ # Deployment guides
/guides/ # How-to guides
/search/ # Full-text search
/assets/ # CSS, JS, images
/health # Health check endpoint
All pages accessible via sidebar navigation
Search available in top navigation bar
Dark/light mode toggle in top right
Related Documentation¶
- mkdocs.yml - Site configuration
- .github/workflows/pages-mkdocs.yml - Deployment workflow
- LANE_4_DEPLOYMENT_ALIGNMENT_REPORT.md - Comprehensive alignment report
Contacts & Escalation¶
- Release Manager: @mbaetiong
- DevOps: @[devops-team]
- Security Issues: security@[organization]
- Incident Response: [incident-channel]
- Documentation: See
.codex/LANE_4_DEPLOYMENT_ALIGNMENT_REPORT.md
Document Version: 2.0 Last Updated: 2026-07-11 Next Review: 2026-08-11