pyr0ball opened issue Circuit-Forge/roadmap#21

pyr0ball
Wed, 25 Mar 2026 10:00:52 -0700

21#circuitforge-core: Extract shared scaffold from Peregrine#

circuitforge-core

Shared scaffold, AI service layer, and infrastructure library packaged as a local editable Python library for reuse across all CircuitForge products.

Active development. Current release: v0.3.0 (2026-04-02).

Shipped Modules

Module | Contents | Since
circuitforge_core.db | SQLite connection, migration runner | v0.1.0
circuitforge_core.config | Config schema, env var loading, per-user isolation | v0.1.0
circuitforge_core.tiers | Tier definitions, BYOK/vision unlock logic, feature gates | v0.1.0
circuitforge_core.llm | LLM router — fallback chain, BYOK, vision-aware, cf-orch allocation | v0.1.0
circuitforge_core.vision | Visual model routing stub | v0.1.0
circuitforge_core.wizard | First-run onboarding stub | v0.1.0
circuitforge_core.pipeline | Background task runner stub | v0.1.0
circuitforge_core.tasks | Shared task scheduler with VRAM budgeting | v0.2.0
circuitforge_core.resources | cf-orch orchestrator (coordinator + agent), GPU monitor, eviction engine | v0.2.0
circuitforge_core.resources.docuvision | FastAPI service wrapping ByteDance/Dolphin-v2 (~8 GB VRAM) | v0.3.0
circuitforge_core.hardware | detect_hardware(), VRAM tier ladder, generate_profile() → llm.yaml | v0.3.0
circuitforge_core.documents | ingest(image_bytes) → StructuredDocument; docuvision + LLM fallback | v0.3.0

Open

Issue | What
#6 | manage.py cross-platform process manager (replaces manage.sh; enables Windows native self-hosting)
#15 | Agent watchdog: persist known nodes + auto-reconnect after coordinator restart
#16 | Ollama: adopt-if-running ProcessSpec mode + VRAM accounting in cf-orch

Current Consumers

Peregrine — db, llm, tiers, config (shims), task scheduler, cf-orch VRAM leases

Kiwi — llm, tiers; documents pipeline earmarked for receipt/recipe OCR (Phase 2)

Snipe — llm, tiers

Avocet — llm, tiers

Osprey — llm (planned)

Installation Pattern

circuitforge-core/   # sibling directory
peregrine/
snipe/
kiwi/

In each product: pip install -e ../circuitforge-core
In Docker builds: COPY circuitforge-core/ into build context before install.

Private PyPI Graduation

Once the API stabilizes across three or more products, publish to a private PyPI index (Forgejo packages or devpi).

License

Private — shared internal dependency only.