A modern Python template with uv, tox & a real CLI

Ready-to-develop structure (pyproject, tox, pre-commit), a docs/ site for GitHub Pages, and a typed CLI: osassis.

$ git clone <repo_url>
$ cd os_assistant
$ uv sync
$ pre-commit install
$ cp .env.example .env
$ python setup_and_pull_general.py
$ osassis chat

What you get

Clean project setup

pyproject.toml with sensible defaults; update fields then ship. No setup drama.

uv workflow

Fast env + deps (uv). Works cross-platform; plays nice with CI.

Quality gates

tox runs pytest, ruff, mypy. Pre-commit keeps diffs clean.

Docs-ready

Serves GitHub Pages from docs/. Start static now; grow to CI build later.

Quickstart

Prerequisites

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install

Clone and enter:
```
git clone <repo_url>
cd os_assistant
```
Sync deps (creates venv):
```
uv sync
```
Tip: uv run <script.py> auto-syncs if needed.
Install pre-commit hooks:
```
pre-commit install
```
Configure environment:
Linux/macOS
```
cp .env.example .env
```
Windows (CMD)
```
copy .env.example .env
```
Edit .env → set MODEL_BASE_URL (your ngrok link), e.g.:
```
MODEL_BASE_URL=https://your-ngrok-link.ngrok.io
```
Setup & pull models:
```
python setup_and_pull_general.py
```
Script: loads .env, sets OLLAMA_HOST from MODEL_BASE_URL, runs ollama pull for required models.

CLI usage — `osassis`

Interactive Chat

osassis chat

System Tracing

Start tracing file system events in a directory:

osassis trace start file_system --dir path/to/watch

View trace logs with time filtering:

osassis trace show file_system --start "yesterday" --end "now"

Clear logs for a tracing domain:

osassis trace clear file_system

Build (dev editable)

Editable install via uv pip:

uv pip install -e .

We also use make as a simple task runner (check the Makefile).

Testing with tox

tox creates isolated envs and runs pytest, ruff, and mypy:

make tox

CI badges

FAQ

Do I need to run uv sync before every command?

No — uv run will sync on demand. Running uv sync once sets everything up.

What’s the setup_and_pull_general.py script doing?

Loads .env, exports OLLAMA_HOST from MODEL_BASE_URL, and pulls required models via ollama pull.

Where do docs come from?

This page is served from docs/ on GitHub Pages. Add more static pages under docs/ as you grow.