circuitforge-core: shared scaffold and AI services library #21

New issue

Open

opened 2026-03-25 10:00:52 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-03-25 10:00:52 -07:00

Owner

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.

## 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](https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core/issues/6) | `manage.py` cross-platform process manager (replaces `manage.sh`; enables Windows native self-hosting) | | [#15](https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core/issues/15) | Agent watchdog: persist known nodes + auto-reconnect after coordinator restart | | [#16](https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core/issues/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.

pyr0ball added the

priority:high

status:design

labels 2026-03-25 10:01:01 -07:00

pyr0ball added

status:active-dev

and removed

status:design

labels 2026-03-29 20:05:56 -07:00

pyr0ball changed title from ~~circuitforge-core: Extract shared scaffold from Peregrine~~ to circuitforge-core: shared scaffold and AI services library

2026-04-02 19:02:57 -07:00