mia-core

Reusable local-first fitness coaching library. SQLite + RAG + pluggable LLM backends.

Modularity is the primary design goal. This package has no dependencies on the React Native app or the RL training pipeline. You can embed it in any Python environment — CLI tools, web backends, Jupyter notebooks, or other mobile frameworks.

Install

pip install -e .

# With llama.cpp backend
pip install -e ".[llama]"

# With transformers backend (for DGX training)
pip install -e ".[transformers]"

# Dev dependencies
pip install -e ".[dev]"

Quick Start

import sqlite3
from mia_core import schema
from mia_core.backends import LlamaCppBackend
from mia_core.rag import DefaultContextBuilder
from mia_core import prompts

# 1. Init database
conn = sqlite3.connect("fitness.db")
schema.apply_schema(conn)

# 2. Create LLM backend
backend = LlamaCppBackend(
    binary_path="/usr/local/bin/llama-cli",
    model_path="models/qwen-3b.gguf",
)

# 3. Ingest a coach plan
from mia_core import ingest
template_id = ingest.ingest_coach_plan(conn, "Bench Press, 5x5 @ 185", backend)

# 4. Build context and suggest targets
workout = schema.get_workout_with_exercises(conn, template_id)
builder = DefaultContextBuilder()
context = builder.build(conn, workout_id=template_id)

prompt = prompts.suggest_targets_prompt(workout, context)
output = backend.generate(prompt)
targets = prompts.parse_json_array(output)

Architecture

Module	Purpose	Depends On
schema	SQLite CREATE TABLE + CRUD helpers	stdlib only
llm	LLMBackend protocol	stdlib only
backends	Concrete implementations (LlamaCpp, Transformers, Mock)	Optional extras
data_source	Protocol for any data store	stdlib only
data_sources.sqlite	SQLiteDataSource implementation	schema
rag	Legacy ContextBuilder (deprecated, use rag_api)	rag_api
prompts	Pure functions: prompt text + JSON parsers	stdlib only
ingest	Coach text/CSV → structured workout	schema, prompts, llm

RAG API (new)

from mia_core.data_sources.sqlite import SQLiteDataSource
from mia_core.rag_api import RAGPipeline
from mia_core.backends import LlamaCppBackend

source = SQLiteDataSource(conn)  # or your own DataSource
backend = LlamaCppBackend(binary_path="...", model_path="...")

pipeline = RAGPipeline(data_source=source, backend=backend)
result = pipeline.suggest_targets(workout_id=1)

print(result.parsed)      # list of target dicts
print(result.context)     # full context gathered
print(result.raw_output)  # raw LLM response

RAGPipeline is data-store agnostic. Implement the DataSource protocol for PostgreSQL, REST APIs, flat files, etc.

from mia_core.data_source import DataSource

class MyDataSource:
    def get_workout_template(self, workout_id: int) -> dict: ...
    def get_recent_workouts(self, limit=5, days=14) -> list[dict]: ...
    def get_athlete_context(self, date=None) -> dict | None: ...
    def get_exercise_reference(self, exercise_id: int) -> dict | None: ...
    def get_periodization_block(self, workout_id: int) -> dict | None: ...

Backends

• LlamaCppBackend: Subprocess to llama.cpp main (GGUF). For iPhone/on-device.
• TransformersBackend: HuggingFace in-process. For DGX training/validation.
• MockBackend: Deterministic canned responses. For tests.

License

Apache 2.0