diff --git a/sdk/building-apps.mdx b/sdk/building-apps.mdx index 461ed7a..e6c4f54 100644 --- a/sdk/building-apps.mdx +++ b/sdk/building-apps.mdx @@ -48,7 +48,9 @@ from truffile.app_runtime import ( ) ``` -The source lives in `truffile/app_runtime/` in the repo and ships with the installed package. Once you `pip install truffile`, the same runtime is importable from app code running on your device. +The runtime ships in the installed package. Truffile release builds stage it +from Truffle's runtime source before packaging, so released wheels contain the +complete app-authoring API used by generated apps. There are two other entry points that import the same names: @@ -64,7 +66,7 @@ All three forms resolve to the same objects. Pick whichever reads best for you. The fastest way to start: ```bash -truffile create my-app +truffile create my-app --type foreground ``` ```text @@ -72,7 +74,6 @@ truffile create my-app Files: → truffile.yaml → my_app_foreground.py - → my_app_background.py → icon.png Next: truffile validate ./my-app @@ -82,9 +83,11 @@ Flags: - `truffile create ` — set the name, prompt for base path - `truffile create --path ` — set name and base path +- `truffile create --type foreground|background|hybrid` — choose the app shape - `truffile create` — fully interactive -The generated `my_app_foreground.py` and `my_app_background.py` are stubs using the real SDK classes. Delete whichever you don't need — the app type is inferred from which `foreground` / `background` sections you keep in `truffile.yaml`. +The default remains `hybrid`. When you pass `--type`, Truffile writes only the +matching entrypoints, manifest sections, and copy-file steps. --- diff --git a/sdk/cli.mdx b/sdk/cli.mdx index 94242c9..45bd250 100644 --- a/sdk/cli.mdx +++ b/sdk/cli.mdx @@ -21,15 +21,18 @@ Most workflows can be driven with explicit arguments, which makes them easy to test in CI or from another agent: ```bash -truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID" -truffile list devices +truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID" --json --non-interactive +truffile list devices --json truffile list apps --json -truffile load all -truffile create my-app --path ./apps -truffile validate ./apps/my-app -truffile deploy ./apps/my-app --dry-run --json +truffile load all --json +truffile create my-app --type foreground --path ./apps --json --non-interactive +truffile validate ./apps/my-app --json +truffile deploy ./apps/my-app --dry-run --json --non-interactive +# after the user approves deployment and replacing an installed copy truffile deploy ./apps/my-app --json --non-interactive --replace -truffile delete my-app +truffile delete my-app --dry-run --json --non-interactive +# after the user confirms the exact deletion plan +truffile delete my-app --yes --json --non-interactive truffile chat "Summarize my installed apps" --json --quiet --timeout 60 truffile infer "Say pong" --json --no-stream --quiet truffile infer --list-models --json @@ -237,7 +240,7 @@ truffile infer | `--model ` | Pre-select a model | | `--system ` | Set an initial system prompt | | `--no-stream` | Disable streaming (get the full response at once) | -| `--no-tools` | Disable built-in tools (`web_search`, `web_fetch`) | +| `--no-default-tools` | Disable built-in tools (`web_search`, `web_fetch`) | | `--mcp ` | Connect an MCP server at startup (can be repeated) | ```bash @@ -393,10 +396,12 @@ truffile create truffile create my-app # in a specific directory -truffile create my-app --path ./apps +truffile create my-app --type foreground --path ./apps ``` -Creates a scaffold with `truffile.yaml`, foreground/background entry points, and a default icon. +Use `--type foreground`, `--type background`, or `--type hybrid`. The default is +`hybrid` for compatibility. The scaffold contains only the selected entrypoints, +matching manifest sections, and a default icon. ### Validate an app @@ -443,25 +448,24 @@ truffile list devices # devices you have saved credentials for ### Delete apps -```bash -# interactive picker -truffile delete - -# delete all apps -truffile delete all +For scripts and agents, identify an app by its stable name, slug, or UUID, +preview the exact target, ask the user to confirm that plan, and only then pass +`--yes`: -# delete by index (1-based, as shown in the app list) -truffile delete 1 2 3 - -# comma-separated works too -truffile delete 1,3,5 - -# pipe selection -echo "all" | truffile delete -echo "1 2" | truffile delete +```bash +truffile list apps --json +truffile delete my-app --dry-run --json --non-interactive +# after the user confirms the exact app shown above +truffile delete my-app --yes --json --non-interactive ``` -If you pass indices that are out of range or invalid, the CLI falls back to the interactive picker (when running in a terminal). +For normal human use, `truffile delete` opens an interactive picker and asks +for confirmation. Numeric indices and `all` remain available interactively, +but automated workflows should use a stable name, slug, or UUID because list +ordering can change. + +Non-interactive deletion without a selection or without `--yes` returns a +structured error and does not mutate the device. ### List models @@ -499,14 +503,15 @@ Both modes let you talk to models on your Truffle, but they serve different purp | `truffile scan` | Scan network for Truffle devices | | `truffile connect ` | Connect to a device | | `truffile disconnect [device\|all]` | Disconnect and clear credentials | -| `truffile create [name] [--path ]` | Scaffold a new app | +| `truffile create [name] [--path ] [--type foreground\|background\|hybrid]` | Scaffold a new app | | `truffile validate [path]` | Validate app config and sources | | `truffile deploy [path]` | Deploy app to connected device | | `truffile deploy --dry-run` | Show deploy plan without changes | | `truffile deploy --interactive` | Deploy with interactive terminal | | `truffile list apps` | List installed apps | | `truffile list devices` | List connected devices | -| `truffile delete [all\|1 2 3]` | Delete apps (interactive, by index, or all) | +| `truffile delete --dry-run --json --non-interactive` | Preview an exact app deletion plan | +| `truffile delete --yes --json --non-interactive` | Delete an app after explicit confirmation | | `truffile models` | List models on connected device | | `truffile chat [--resume]` | Agent chat REPL | | `truffile infer [--model M] [--system S]` | Raw inference REPL | diff --git a/sdk/inference.mdx b/sdk/inference.mdx index 3503a22..524afe2 100644 --- a/sdk/inference.mdx +++ b/sdk/inference.mdx @@ -11,10 +11,27 @@ For the interactive CLI experience (`truffile infer`), see the [CLI guide](/sdk/ --- +## Find the device host + +Your computer must be able to reach the Truffle on the same network. Run: + +```bash +truffile scan --json --non-interactive +``` + +Use an address returned in `devices[].addresses`, or use the device name as an +mDNS host such as `truffle-1234.local`. + +```bash +export TRUFFLE_HOST=truffle-1234.local +``` + +--- + ## List Models ```bash -curl -sS http:///if2/v1/models | python -m json.tool +curl -sS "http://$TRUFFLE_HOST/if2/v1/models" | python -m json.tool ``` Or via the CLI: @@ -28,7 +45,7 @@ truffile models ## Chat Completions ```bash -curl -sS http:///if2/v1/chat/completions \ +curl -sS "http://$TRUFFLE_HOST/if2/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "", @@ -38,6 +55,38 @@ curl -sS http:///if2/v1/chat/completions \ }' ``` +### Python client + +`httpx` is installed with Truffile. This example lists the available models, +uses the first returned model ID, and sends one non-streaming request: + +```python +import os + +import httpx + +base_url = f"http://{os.environ['TRUFFLE_HOST']}/if2/v1" + +models_response = httpx.get(f"{base_url}/models", timeout=15) +models_response.raise_for_status() +models = models_response.json()["data"] +if not models: + raise RuntimeError("No inference models are available on this Truffle") + +model = models[0].get("id") or models[0]["uuid"] +response = httpx.post( + f"{base_url}/chat/completions", + json={ + "model": model, + "messages": [{"role": "user", "content": "Reply with pong."}], + "stream": False, + }, + timeout=120, +) +response.raise_for_status() +print(response.json()["choices"][0]["message"]["content"]) +``` + ### Request body | Field | Type | Description | diff --git a/sdk/installation.mdx b/sdk/installation.mdx index 36510ec..a4aa8a8 100644 --- a/sdk/installation.mdx +++ b/sdk/installation.mdx @@ -6,8 +6,8 @@ description: "Install the Truffile SDK to chat with and deploy apps to your Truf ## Prerequisites - Python 3.12 or higher -- A Truffle¹ device -- The [Symphony desktop client](/client/overview), with your device already onboarded +- A Truffle¹ device when you are ready to connect, chat, run inference, or deploy +- The [Symphony desktop client](/client/overview), with your device onboarded before connecting ## Agent setup prompt @@ -20,11 +20,10 @@ Use explicit CLI commands and explain what you are doing as you go. Requirements: - Make sure Python 3.12 or newer is available. Prefer `python3.12` when present; otherwise use the newest `python3`/`python` that is >=3.12. -- Prefer `uv` if it is installed. If `uv` is not installed, use the standard library `venv` module. -- Create a local virtual environment named `.venv`. -- Activate/use that virtual environment for all Python and pip commands. -- Install Truffile with `pip install truffile`; if it is already installed, make sure it is upgraded to the latest version. -- Verify the install with `truffile --help`. +- If `uv` is installed, create `.venv` with `uv venv --python 3.12 .venv` and install with `uv pip install --python .venv/bin/python --upgrade truffile`. +- Otherwise create `.venv` with the standard library and install with `.venv/bin/python -m pip install --upgrade pip truffile`. +- Use `.venv/bin/python` and `.venv/bin/truffile` for all Python and Truffile commands. +- Verify the install with `.venv/bin/truffile --help`. - Run `truffile load all` so the bundled skills and example apps are copied into this workspace under `./truffile/skills` and `./truffile/examples`. - Do not require a Truffle device to finish setup. If no device is connected yet, tell me that I first need to onboard my Truffle through the Symphony desktop client at https://docs.truffle.net/client/overview, then get my User ID from Symphony > Settings, then run `truffile scan` and `truffile connect --user-id `. During `truffile connect`, I must approve the new session on my Truffle device. @@ -63,7 +62,7 @@ The prompt works because Truffile is CLI-first: every core workflow has explicit Verify: ```bash - python3 --version + python3.12 --version ``` @@ -86,63 +85,70 @@ The prompt works because Truffile is CLI-first: every core workflow has explicit Verify: ```bash - python3 --version + python3.12 --version ``` -## Set up a virtual environment +## Create the virtual environment and install Truffile + +Use uv when it is available. Both paths below call the environment directly, so +they do not depend on shell activation. - + + macOS / Linux: + ```bash - python3 -m venv .venv + uv venv --python 3.12 .venv + uv pip install --python .venv/bin/python --upgrade truffile ``` - - - ```bash - source .venv/bin/activate - ``` - - - ```powershell - .venv\Scripts\Activate.ps1 - ``` - - + Windows PowerShell: + + ```powershell + uv venv --python 3.12 .venv + uv pip install --python .venv\Scripts\python.exe --upgrade truffile + ``` - - If you prefer [uv](https://github.com/astral-sh/uv) for faster package management: + + macOS / Linux: ```bash - # install uv if you don't have it - curl -LsSf https://astral.sh/uv/install.sh | sh - - # create and activate a venv - uv venv - source .venv/bin/activate # macOS / Linux - # or - .venv\Scripts\Activate.ps1 # Windows + python3.12 -m venv .venv + .venv/bin/python -m pip install --upgrade pip truffile + ``` + + Windows PowerShell: + + ```powershell + py -3.12 -m venv .venv + .venv\Scripts\python.exe -m pip install --upgrade pip truffile ``` -## Install Truffile +## Verify the installation -With your environment activated: +macOS / Linux: ```bash -pip install truffile +.venv/bin/truffile --version +.venv/bin/truffile help +.venv/bin/truffile load all --json +.venv/bin/truffile doctor --json ``` -Verify the installation: +Windows PowerShell: -```bash -truffile help +```powershell +.venv\Scripts\truffile.exe --version +.venv\Scripts\truffile.exe help +.venv\Scripts\truffile.exe load all --json +.venv\Scripts\truffile.exe doctor --json ``` -You should see the Truffile welcome panel listing every command (`scan`, `connect`, `deploy`, `chat`, `infer`, and the rest). If you see the panel, you're ready to go. +`truffile doctor --json` may report `device_required` after a successful local installation. That means the CLI is ready, but a Truffle has not been paired in this environment yet. Before connecting from Truffile, onboard your device through the Symphony desktop client. Download Symphony from [the client overview](/client/overview), complete device onboarding, then copy your User ID from **Symphony → Settings**. `truffile connect` will ask for that User ID and then you must approve the new session on your Truffle device.