Prometheus Platform

This is the main, full project documentation for Prometheus.

It explains:

• what the project does end-to-end,
• what runs by default,
• what optional native subsystems exist (including C/C++),
• install/uninstall and verification,
• architecture boundaries,
• and next steps from here.

---

1) Executive summary

Prometheus is a local-first engineering platform centered on a capability model.

Core behavior:

1. Boot runtime services (core/bootstrap.py)
2. Register capabilities (hardware, firmware, recovery, AI, security, engineering)
3. Expose those capabilities through:
   • CLI (prometheus / python prometheus.py)
   • HTTP API (backend/main.py)
   • assistant tools (assistant/tools/*)
   • automation actions (automation/actions/*)
4. Run with simulated hardware by default; use real device backends when present

Primary operator surfaces:

• CLI: prometheus --help
• API health: GET /health
• API docs: GET /docs

---

2) Do we really use C/C++?

Yes, but optionally.

Prometheus runs without C/C++ by default using deterministic simulated hardware backends. If native HAL libraries are present, hardware managers switch to real backends automatically.

How this works:

• hardware/hal/ctypes_bridge.py loads shared libraries from cpp/build/hal/...
• hardware/usb/manager.py attempts from hardware.hal.ctypes_bridge import UsbTransport
• hardware/serial/manager.py attempts from hardware.hal.ctypes_bridge import SerialTransport
• On import/load failure, managers log fallback and use simulated devices

So you can use Prometheus heavily without touching C/C++, because simulation and Python-level hardware APIs are always available.

---

3) Runtime architecture (what actually boots)

Boot entrypoint: core/bootstrap.py

Boot sequence:

1. Initialize DB
2. Build platform components (event bus, capability manager, APIs)
3. Register capability families:
   • hardware
   • recovery
   • AI
   • distributed
   • engineering
   • intelligence
   • security
4. Register assistant tool capabilities
5. Inject CapabilityApi into automation action dispatchers
6. Register plugins and agents
7. Start scheduler (unless safe-mode)

Main container services registered include:

• platform_service, delta_service, epsilon_service, omega_service
• capability_api, plugin_api, agent_api, device_api
• knowledge_engine, memory_api, reasoning_api
• hardware_hal, hardware_session_manager, hardware_diagnostics
• workflow runtime bindings

---

4) Key project modules by responsibility

4.1 Core runtime

• core/config.py - process config from env defaults
• core/database.py - SQLAlchemy engine/session
• core/container.py - service container
• core/capabilities.py - capability registration and execution authorization
• core/bootstrap.py - complete runtime wiring

4.2 Service layer

• services/platform_service.py - high-level orchestration API
• services/capability_registry.py - base hardware capability registration
• services/hardware_capabilities.py - transport capability registration
• services/epsilon_service.py - HAL/session/diagnostics/recovery integration
• services/security_capabilities.py - security capability surface
• services/ai_capabilities.py - AI capability surface

4.3 Hardware layer

• hardware/usb, hardware/serial, hardware/adb, hardware/fastboot managers
• permission policies per transport (permissions.py)
• hardware/drivers/* for transport and device-family drivers
• hardware/hal/ctypes_bridge.py for optional native transport bridge

4.4 Automation + assistant boundary

• automation/actions/*.py - internal action dispatchers
• assistant/tools/*.py - plugin-capability descriptors + executors
• both route through registered capabilities in normal runtime paths

4.5 API surface

backend/main.py exposes:

• system: health/status/stats/jobs/resources/baseline
• capabilities: discover/execute/history/health
• plugins/agents/memory/knowledge/workflows
• device + ownership + gamma/delta/epsilon/omega flows
• assistant/providers and command dispatch
• SSE event stream (/events)

4.6 CLI surface

prometheus_cli/main.py commands include:

• status, demo, test
• install, extensions, new, pack, verify
• usb, serial, adb
• launch (backend + optional distributed/cloud/frontend components)

---

5) Language/runtime layers

Prometheus is multi-runtime, but the default install path is Python-first.

5.1 Python (primary and required)

• orchestration, API, CLI, capability execution, automation, assistant tools

5.2 C/C++ HAL (optional acceleration/real hardware bridge)

• source: cpp/
• HAL CMake: cpp/hal/CMakeLists.txt
• provides shared libs loaded by Python ctypes bridge
• optional: system works without these libraries

5.3 Go components (optional)

• go/ and cloud/ subsystems
• started via prometheus launch flags (--distributed, --cloud, --all)

5.4 Rust/Zig artifacts (present, not required for baseline install)

• crates/ and zig/ exist in repo
• helper scripts exist under scripts/build_rust_extensions.*
• not required for the standard Python install/uninstall path

---

6) Installation and uninstallation

6.1 Install scripts

Windows:

• Install: .\scripts\install_prometheus.ps1
• Uninstall: .\scripts\uninstall_prometheus.ps1

Common options:

• -Editable (install editable mode)
• -Python "C:\Path\python.exe" (specific interpreter)
• uninstall with -RemoveVenv to delete .venv-prometheus

macOS/Linux:

• Install: bash scripts/install_prometheus.sh
• Uninstall: bash scripts/uninstall_prometheus.sh

Environment switches:

• PYTHON_BIN, VENV_PATH, EDITABLE=1, REMOVE_VENV=1

6.2 Install verification

Minimum sanity check:

1. prometheus --help
2. GET /health after starting server
3. GET /docs

---

7) Testing and quality model

7.1 Core suites

• unit/integration tests under tests/
• transport capability tests (ADB/Serial/USB and others)
• bootstrap and API smoke coverage

7.2 Hardware regression matrix

• tests/hardware_regression/
• per-device/per-transport validations
• firmware sub-suite under tests/hardware_regression/firmware/

7.3 Stress/soak

• tests/hardware_stress/
• serial stability, flash cycles, concurrent sessions

7.4 Physical-device gating

• tests marked @pytest.mark.physical
• executed only when PROMETHEUS_RUN_PHYSICAL=1

---

8) SDK + boundary policy

Internal policy:

• dispatchers should route via CapabilityApi (not direct hardware imports)
• approved exceptions documented in architecture/module-spec.md

Notable approved exceptions include:

• sdk/usb.py, sdk/serial.py, sdk/adb.py, sdk/fastboot.py
• engineering/device_simulator.py
• logger cross-cutting usage in engineering modules

---

9) Operational playbook

9.1 Start modes

• CLI only: prometheus status
• API server: python prometheus.py --server
• minimal services: python prometheus.py --safe-mode
• full launcher: python -m prometheus_cli launch --all

9.2 Health and introspection

• /health - runtime and component health
• /status - summarized platform state
• /capabilities - discover registered capabilities
• /system/services - service container registry
• /events - SSE stream of platform events

9.3 Common failure categories

1. packaging/import issues (missing modules in wheel)
2. missing host binaries (Go/npm/native libs)
3. permission mismatch in capability execution
4. optional native HAL not found (falls back to simulation)

---

10) Next steps from here (project plan)

Phase 1: Release correctness and trust (immediate)

1. Add CI pipeline stage:
   • run install script
   • run prometheus --help
   • run uninstall script
2. Add artifact checks:
   • verify wheel contains core, services, hardware, backend, prometheus_cli
3. Add release checklist updates in docs and workflow

Deliverable: every release proves clean install/run/uninstall.

Phase 2: Documentation hardening (short term)

1. Split this file into user/developer/operator task guides
2. Add endpoint map generated from backend routes
3. Add capability map generated from registered capabilities at boot
4. Add simulation-vs-real-hardware troubleshooting guide

Deliverable: no ambiguity about default runtime vs optional components.

Phase 3: Runtime boundary completion

1. Complete SDK boundary audit for remaining modules
2. Remove legacy direct-hardware fallback after one stable cycle
3. Add startup assertion tests ensuring expected capabilities exist

Deliverable: consistent capability-first dispatch across runtime.

Phase 4: Hardware confidence expansion

1. Extend regression matrix and fixture realism
2. Add flake tracking for stress tests and enforce thresholds
3. Add physical-lab nightly gated pipeline

Deliverable: predictable reliability under concurrency and long-running use.

Phase 5: Productization

1. Versioned install bundles + release notes
2. First-run diagnostic command for environment validation
3. Extension ecosystem docs and signed-package workflows

Deliverable: easier onboarding and safer extension adoption.

---

11) Definition of done for future milestones

A milestone is complete only when:

1. behavior is implemented and documented
2. install/uninstall is validated on a fresh environment
3. relevant tests pass (unit + regression + stress subset)
4. capability permission behavior is verified
5. operational runbook updates are included