circuitforge-core

Shared Python scaffold for privacy-first, self-hosted AI tools

---

Why circuitforge-core?

• Local inference first. The LLM router defaults to Ollama on localhost. Cloud APIs are a configurable fallback, not the default path. No telemetry, no round-trips you didn't ask for.
• VRAM-aware scheduling. The task scheduler and resource coordinator track GPU memory across concurrent services, allocate slots before loading models, and evict backends gracefully when VRAM is scarce.
• Consistent tier system across products. One tiers module handles Free / Paid / Premium / Ultra tiers, BYOK (bring your own key) unlocks, and local-vision capability gates — the same way in every product.
• Uniform developer experience. DB migrations, config validation, document ingestion, process management, and preference storage all share a single, tested implementation. Products extend, not reimplement.

---

Install

# From PyPI
pip install circuitforge-core

# Editable install from source (recommended for product development)
pip install -e /path/to/circuitforge-core

# With optional extras
pip install circuitforge-core[pdf]                  # PDF/DOCX/OCR document ingestion
pip install circuitforge-core[vector]               # SQLite-vec vector store
pip install circuitforge-core[text-transformers]    # Local transformer inference (cf-text)
pip install circuitforge-core[stt-faster-whisper]   # Speech-to-text via Faster Whisper
pip install circuitforge-core[tts-chatterbox]       # Text-to-speech via Chatterbox
pip install circuitforge-core[reranker-qwen3]       # Reranking via Qwen3
pip install circuitforge-core[community]            # PostgreSQL-backed community store
pip install circuitforge-core[manage]               # cf-manage CLI (Typer)
pip install circuitforge-core[dev]                  # All dev dependencies

---

Modules

Module	Status	Description
db	Implemented	SQLite connection factory and migration runner
llm	Implemented	LLM router with priority fallback chain (Ollama, vLLM, Anthropic, OpenAI-compatible)
tiers	Implemented	Tier system with BYOK and local-vision unlocks (Free / Paid / Premium / Ultra)
config	Implemented	Env validation and .env loader with startup fail-fast
hardware	Implemented	GPU/CPU detection, VRAM profiling, backend profile generation
documents	Implemented	PDF, DOCX, and image OCR ingestion into StructuredDocument
affiliates	Implemented	Affiliate URL wrapping with per-user opt-out and env-var fallback
preferences	Implemented	User preference store — local YAML with pluggable backend; dot-path get/set
tasks	Implemented	VRAM-aware LLM task scheduler; shared slot manager across services
manage	Implemented	Cross-platform product process manager (Docker and native modes)
resources	Implemented	VRAM allocation, eviction engine, GPU profile registry
text	Implemented	Text processing utilities and local transformer inference service
activitypub	Implemented	ActivityPub actor, inbox, delivery, and Lemmy federation primitives
audio	Implemented	Audio buffer, format conversion, resampling, and VAD (voice activity detection) gate
stt	Implemented	Speech-to-text service (Faster Whisper backend)
tts	Implemented	Text-to-speech service (Chatterbox backend)
musicgen	Implemented	Music generation service (AudioCraft/MusicGen backend)
reranker	Implemented	Result reranking — BGE, Qwen3, cross-encoder, and Cohere adapters
vector	Implemented	SQLite-vec vector store with pluggable embedding backend
api	Implemented	Shared API helpers — corrections and feedback endpoints
community	Implemented	Community feed and social store (PostgreSQL-backed)
platforms	Implemented	Platform-specific integrations (eBay)
cloud_session	Implemented	Cloud session management primitives
input	Implemented	Input handling — MediaPipe gesture recognition
job_quality	Implemented	Job listing quality scoring and signal extraction
vision	Stub	Vision router (moondream2 / SigLIP dispatch — planned)
wizard	Stub	First-run wizard base class — products subclass BaseWizard
pipeline	Stub	Staging queue base — products provide concrete schema

---

Usage: LLM Router

The LLM router reads a config file at ~/.config/circuitforge/llm.yaml, tries each backend in fallback order, and skips unreachable or disabled entries transparently.

from circuitforge_core.llm import LLMRouter

# Auto-detects from env vars when llm.yaml is absent:
# ANTHROPIC_API_KEY, OPENAI_API_KEY / OPENAI_BASE_URL, OLLAMA_HOST
router = LLMRouter()

response = router.complete(
    messages=[{"role": "user", "content": "Summarize this in one sentence."}],
    system="You are a concise assistant.",
)
print(response)

Example llm.yaml (Ollama local, Anthropic cloud fallback):

fallback_order:
  - ollama
  - anthropic

backends:
  ollama:
    type: openai_compat
    enabled: true
    base_url: http://localhost:11434/v1
    model: llama3.2:3b

  anthropic:
    type: anthropic
    enabled: true
    model: claude-haiku-4-5-20251001
    api_key_env: ANTHROPIC_API_KEY
    supports_images: true

---

Usage: Database + Migrations

from circuitforge_core.db import get_connection, run_migrations
from pathlib import Path

# Run product migrations on startup
run_migrations(db_path=Path("data/app.db"), migrations_dir=Path("db/migrations"))

# Get a connection anywhere in your app
with get_connection(Path("data/app.db")) as conn:
    conn.execute("INSERT INTO items (name) VALUES (?)", ("example",))

---

Used by

Product	Description
peregrine	Job search — discovery, cover letters, interview prep
snipe	Auction sniping — eBay trust scoring, bid timing
kiwi	Pantry tracker with barcode/receipt OCR and recipe suggestions
avocet	Email classifier training and benchmark harness
osprey	Government hold-line automation
linnet	Real-time tone annotation and voice transcription
pagepiper	PDF/rulebook RAG (retrieval-augmented generation) search

---

Contributing

circuitforge-core is MIT licensed. Contributions are welcome.

git clone https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core
cd circuitforge-core
pip install -e ".[dev]"
pytest

• New modules belong in circuitforge_core/<module>/ as a package, not a flat file
• Keep modules focused — extract when a module exceeds 400 lines
• All public functions need type annotations
• Tests live in tests/ — aim for 80% coverage on new code
• Use ruff for linting before submitting a PR

Open issues and PRs at: git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core

---

License

MIT — see LICENSE.

This is the fully open layer of the CircuitForge stack. Products built on top of circuitforge-core may carry different licenses (BSL 1.1 for AI features, proprietary for fine-tuned weights). The scaffold itself is and will remain MIT.

---

Humans own design, architecture, code review, testing, and verification. LLMs are part of our development workflow. Our positions on LLM use →