Skip to content

AGENTS.md

Latest commit

 

History

History
85 lines (68 loc) · 5.55 KB

AGENTS.md

File metadata and controls

85 lines (68 loc) · 5.55 KB
Raw

AGENTS.md

Strata runs the Qwen3.8-Flash-Next mixture-of-experts model (and its Coder, Swift 1.5, Unsloth, Gyro and NVFP4 variants, and Qwen3.6-35B-A3B) on a normal PC: one NVIDIA or AMD graphics card plus system RAM on Windows or Linux, or an Apple Silicon Mac. Version 0.2.1, engine 0.1.46. It has three parts:

  • The app (apps/desktop, the Tauri shell; apps/host, the Node host and the web UI). It is for people who do not want a terminal. The installer has the engine inside.
  • The Terminal (strata.py, strata_cli/, strata_control/): the strata command. It sets up a model, serves it and watches it. Agents use this part.
  • The engine and the server (src/, include/, metal/, sycl/ for the C++/CUDA/HIP/SYCL/Metal engine; serve/ for the Python server with an OpenAI- and Anthropic-compatible API and a web page). setup.py, started by START-HERE.bat or setup.sh, is the older one-click installer from source.

Installing Strata for a user

Follow docs/AI_SETUP.md. For an agent that has a shell, the short version is:

  1. Install the Terminal. It needs no administrator rights.

    curl -fsSL https://github.com/Niko1221/Strata/releases/latest/download/install.sh | sh                  # Linux, Mac
irm https://github.com/Niko1221/Strata/releases/latest/download/install.ps1 | iex                         # Windows PowerShell

    On Windows, open a new terminal afterwards so that strata is on the PATH.

  2. Check what would happen. Nothing is changed:

    strata launch --plan --model q2_0

  3. Set up and serve without questions. It downloads the engine for the card and the model (tens of GB), starts the server, prints the addresses and returns. The server keeps running.

    strata launch --model q2_0 --yes --no-tui

    Useful flags (all of them: strata launch --help): --family, --model-path (files the user already has), --data-dir, --context 32k|64k|128k, --vision off|on|gpu|cpu, --parallel N, --gpu 0,1, --access local|lan|cloudflare|tailscale, --port, --api-key-env NAME, --new-key, --save-preset NAME, --output json. strata launch --status shows what is serving, strata launch --stop stops it, and strata launch --show-key prints the API key.

  4. Connect the user's apps: strata connect lists them, strata connect <app> --check sends one prompt and one tool call the way that app does.

Keep the server on 127.0.0.1 unless the user asks for more. Beyond it an API key is recommended: --access lan makes one for you, and --no-api-key serves without one (a warning, never a refusal; on a public tunnel the warning is stronger). The old route (clone the repository and run START-HERE.bat --yes or ./setup.sh --yes) still works and is the fallback when the Terminal cannot run. Strata's MCP server (docs/MCP_SERVER.md) offers the same steps as tools.

Working on the code

  • How the engine works, every measured number, the API and all settings: docs/DETAILS.md and the paper.
  • The Terminal: docs/TERMINAL.md and docs/TERMINAL_LAUNCH.md. The app, the packages and the update feed: packaging/README.md and packaging/UPDATES.md.
  • AMD (HIP) build and validation: docs/AMD_HIP.md; multi-GPU: docs/MULTI_GPU.md; Mac (Metal): docs/MAC.md.
  • Tests: the Terminal and Control tests are in tests/terminal (python -m pytest tests/terminal). The app's UI tests run with npm test in apps/host. Setup's own tests run without a GPU or downloads: python tools/test_setup_<name>.py (for example tools/test_setup_amd.py, tools/test_setup_choices.py).
  • Keep the docs' style: plain words, short sentences, written for non-technical users first. Give measured numbers with what they were measured on. Make no claim without a measurement.

Contributing a change or report

The rules are in CONTRIBUTING.md. Read it before you open an issue or a pull request, and follow it whether a person or an agent writes the text. The short version:

  • Start every issue and pull request title with its area: [Engine], [GUI], [TUI], [Benchmark], [Docs] or [Other], for example [Engine] fix …. A check on GitHub fails a pull request whose title has no area.
  • Search the open and closed issues and pull requests first, and add to a thread that already covers your point.
  • Agree the scope in an issue before a large feature, a refactor or a change to a default.
  • One problem per pull request. Lead with the problem and the result, then the approach, then the validation (passed, failed and not run, kept apart) and the limits.
  • A new feature is opt-in, and the default path stays byte-identical to the last release. Say how you checked.
  • Build every backend a file touches (CUDA, HIP, SYCL) before asking for review.
  • Change a default only where you measured it faster, and show the numbers with what they were measured on.
  • Never submit measurements, logs or reproduction steps you did not produce. Mark a finding from reading code as unconfirmed static analysis.
  • A report from hardware the maintainers do not have is welcome. Follow docs/COMMUNITY_BENCHMARKS.md, compare against a same-day run of the build you are testing, and say what you did not test.
  • Open test requests and the hardware that is wanted are listed in docs/TEST_REQUESTS.md.