terminus-core

Dependency-free Python substrate for portable pathing, bootstrap, state, and local-LLM routing.

Who It Is For

Use terminus-core when you need code that survives relocation, nesting, and packaging without path breakage.

• Infrastructure and platform engineers building portable Python services.
• Local-first AI developers using Ollama without adding SDK dependencies.
• Teams that need deterministic startup, local telemetry, and contract drift checks.

Not a general AI framework. Not an orchestration platform. It is a portable infrastructure substrate.

60 Seconds: Understand, Compare, Try

Install:

pip install -e ".[test]"
pytest -q

Run the demo:

python examples/portable_demo.py

What you should see:

• Anchor-based path resolution instead of hardcoded paths.
• State and telemetry written through the same resolver.
• Ollama request that fails soft (error payload, not app crash) if service is unavailable.

Three Tiny Wins

1. Replace hardcoded paths

from terminus_core import PathResolver

paths = PathResolver.detect()
config_path = paths("ROOT", "config", "settings.json")

2. Portable bootstrap on any machine

from terminus_core import bootstrap, terminus

bootstrap()
log_path = terminus("STATE", "runtime.log")

3. Local Ollama routing without extra dependencies

from terminus_core import OllamaClient

client = OllamaClient(defaults={"reasoning": "qwen2.5-coder:7b"})
resp = client.generate(prompt="Summarize this file", model=client.get_model("reasoning"))
print(resp.success, resp.model, resp.error)

Why This Instead?

Need	Typical stack	terminus-core	Scope note
Portable root/path detection	rootutils	PathResolver anchors plus workspace marker detection	Focused on deterministic anchor resolution
.env loading and bootstrap	python-dotenv + custom startup glue	bootstrap and load_env in stdlib	No framework integration layer
Local Ollama requests	ollama-python	OllamaClient over urllib with fail-soft responses	Ollama only, intentionally narrow
Budget-aware model routing	litellm (broad provider abstraction)	TokenRouter with local-first/downshift policy	Local-first policy, not multi-cloud brokering

The Portability Problem It Solves

Most projects remove absolute paths but keep positional assumptions (flat siblings, fixed folder depth, fixed workspace roots). The system works until the project is nested, moved to another drive, or packaged differently.

terminus-core closes that last mile by resolving locations through logical anchors (ROOT, STATE, MEMORY_DB) instead of positional layout assumptions.

The Case for Deterministic Infrastructure

Most infrastructure failures are not algorithm failures. They are environment failures: path assumptions, dependency drift, and service coupling that appears only after relocation or packaging.

terminus-core addresses that risk directly:

1. PathResolver removes positional assumptions by resolving logical anchors (ROOT, STATE, MEMORY_DB).
2. StateManager keeps local telemetry and KV state portable, then verifies contracts via SHA-256 drift checks.
3. TokenRouter and OllamaClient support local-first inference with budget-aware routing and fail-soft behavior.
4. bootstrap provides deterministic startup without third-party bootstrap stacks.
5. The stdlib-only mandate reduces attack surface and dependency maintenance overhead.

For teams shipping production systems, this is a continuity decision as much as a developer-experience decision: move the project tree, keep operating.

Core Components

• PathResolver: Workspace detection plus anchor resolution.
• bootstrap: sys.path setup, environment loading, logging, and a terminus callable.
• StateManager: Telemetry log, namespaced KV state, SHA-256 contract drift detection.
• TokenRouter: Budget-aware local model selection and downshift planning.
• OllamaClient: stdlib transport with retries, fallback chains, and fail-soft response objects.

Drop-In Starter

Use the demo as a starter baseline, then swap your current file paths to anchors one module at a time.

• Starter script: examples/portable_demo.py
• Migration path: replace path literals with PathResolver or terminus calls first, then move state and LLM calls.

5-Minute Migration

1. Add terminus-core and call bootstrap in your entrypoint.
2. Replace hardcoded paths with terminus("ROOT", ...), terminus("STATE", ...), or PathResolver.detect().
3. Route local inference through OllamaClient and check response.success before consuming outputs.
4. Persist critical checkpoints with StateManager.set_state and add trace blocks around risky operations.

Copy-Paste: Unified Example

from terminus_core import PathResolver, StateManager, OllamaClient

paths = PathResolver.detect()
state = StateManager.detect()
client = OllamaClient(defaults={"reasoning": "qwen2.5-coder:7b"})

state.set_state("startup_root", str(paths("ROOT")))

with state.trace("demo", "local_inference"):
    result = client.generate(prompt="Return one sentence", model=client.get_model("reasoning"))

if result.success:
    print(result.output)
else:
    print("Ollama unavailable:", result.error)

Release and Adoption Checklist

• Publish package to PyPI and keep release notes current.
• Keep CHANGELOG updates small and frequent.
• Post one crisp comparison article: Why I built terminus-core instead of combining rootutils, dotenv, and Ollama tooling.
• Lead with a short relocation demo clip before architecture deep dives.

License

Dual licensed:

• AGPL-3.0-or-later for open-source usage.
• Commercial licensing available for closed-source or SaaS distribution (see COMMERCIAL_LICENSE.md).