adding-a-shared-template-utility

Adding a Shared Template Utility

Overview

fused_render/templates/shared/ is where ONE copy of a helper lives when both a built-in template and an arbitrary user .py need it — appenv.py (env facts: home dir, mounts, origin) and fused_ai.py (the Python client for fused.ai) are the two that exist today. It looks like an ordinary shared-code folder. It is not: every file in it runs as a subprocess with no guarantee the fused_render package is importable, and both consumer shapes (a template shipped inside the app, a user file anywhere on disk) have to resolve the same import identically. The rules below are currently scattered across appenv.py's and fused_ai.py's own docstrings and SPEC PY-15/PY-19 — write them down here instead of re-deriving them per contribution.

Where it goes, and how each consumer reaches it

• A built-in template (fused_render/templates/<name>/*.py) reaches it with the established relative dance:

  import sys, os
  sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "shared"))
  import appenv
  

  This only works because the template physically lives inside templates/, one level above shared/.
• A user .py, anywhere on disk, just does import fused_ai (or import appenv) with no path setup at all. Both execution engines append templates/shared onto that module's own sys.path before it runs — see "Path seeding" below — so the import resolves the same way import pandas does.

Stdlib only — not a style preference

A user .py may run inside a hermetic uv venv built from ITS OWN pyproject.toml (PY-16) and containing exactly what that manifest declares, nothing unioned in from a baseline. A shared utility that imports requests, or anything beyond the standard library, would need every app that ever imports it to declare that dependency in its own manifest — which no contributor adding a shared helper is in a position to arrange, and which silently breaks the first app that doesn't. json, os, socket, time, urllib are fine; a third-party package is not.