Metadata-Version: 2.4
Name: terminus-core
Version: 0.2.0
Summary: Dependency-free Python substrate for portable pathing, bootstrap, state telemetry, and local-LLM routing.
Author-email: Joseph Goulette <webmaster.gewey@gmail.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/gewey/terminus-core
Project-URL: Repository, https://github.com/gewey/terminus-core
Keywords: llm,ollama,routing,telemetry,state,path-resolution,portable,zero-dependency,bootstrap,drift-detection
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# terminus-core

[![PyPI version](https://img.shields.io/pypi/v/terminus-core.svg)](https://pypi.org/project/terminus-core/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://github.com/gewey/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:

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

Run the demo:

```bash
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

```python
from terminus_core import PathResolver

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

### 2. Portable bootstrap on any machine

```python
from terminus_core import bootstrap, terminus

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

### 3. Local Ollama routing without extra dependencies

```python
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

```python
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).

