scaledthought 0.0.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaledThought Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,63 @@
 # scaledthought
 
-The CLI for [ScaledThought](https://scaledthought.com): headless open-model inference run by your agent.
+The CLI for [ScaledThought](https://scaledthought.com): headless, OpenAI-compatible inference for
+open-weight models, hosted in the US or Canada. It's built for coding agents: it never prompts, prints
+JSON when stdout isn't a terminal, and every error is one JSON line on stderr with a non-zero exit.
 
-**Not launched yet.** This release only reserves the name. Running it prints a notice and exits; it makes no network calls.
+Agents: the full setup protocol is at <https://scaledthought.com/llms.txt>.
+
+```bash
+npx -y scaledthought@latest init --region us   # or: --region ca (data stays in Canada)
+```
+
+`init` creates an account, writes `ST_API_KEY` and `ST_BASE_URL` to `./.env` (mode 0600), adds `.env` to
+`.gitignore`, and prints the account, its credit balance (`balance_usd`, `needs_credits`), the models live in your
+region, `next_command` and `next_steps`.
+Running it again is safe. If a key already exists it returns `"already_initialized": true` and the
+account status instead of creating a second account.
+
+If you arrived through a `scaledthought.com/go/<code>` link, its instructions add `--source <code>` (a campaign code
+such as `a-rd`, stored on the new account so we know which campaign worked). It's optional, and a value that isn't a
+code is dropped with a warning rather than failing `init`. On some US campaigns the human can copy an opt-in prompt
+ending in `(ad click <token>)`; the `/go` instructions then tell the agent to add `--ad-click <token>` (the token is
+in the prompt, never in the link). A malformed token is dropped with a warning, and the flag is ignored outside `us`.
+Turn ad measurement off at any time with `account ad-measurement off` (nothing about the account is then sent to any
+ad platform). `account` and `account ad-measurement` print `ad_measurement` (true only when something about the
+account could be sent: a `us` account that signed up with an ad click and hasn't opted out; always false in `ca`) and
+`ad_measurement_opt_out` (the stored preference). Neither flag is a secret.
+
+Inference is prepaid, and a new account has no credits: until your human pays, completions return
+`402 insufficient_credits`. So the first thing after `init` is a top-up your human approves:
+
+```bash
+npx -y scaledthought@latest billing topup --amount-usd 5  # prints approval_url and topup_id
+# show your human the approval_url, exactly as printed; they pay by card
+npx -y scaledthought@latest billing wait                  # returns once they've paid; on topup_pending run it again
+```
+
+`billing wait` returns within about 90 seconds (`--timeout-s` to change it), under Claude Code's default 2-minute
+shell timeout. Prefer it to `billing topup --wait`: an agent's shell tool usually shows a command's output only when it
+ends, so the link would reach the human only after the payment it is waiting for.
+
+```bash
+npx -y scaledthought@latest models --live                 # models serving in your region now
+npx -y scaledthought@latest chat -m auto "Reply with OK"  # one real completion
+npx -y scaledthought@latest mcp                           # `claude mcp add …` command + JSON config
+npx -y scaledthought@latest account                       # plan, region, spend
+npx -y scaledthought@latest account ad-measurement off    # opt out of ad measurement
+```
+
+Other commands: `keys list|create|rotate|revoke|revoke-self` (`keys create --expires-in 30d --scopes inference --child`, `keys rotate <id> --grace 24h`), `usage`, `billing status|topup|wait|auto-reload|transactions`, `batches …`,
+`fine-tune …`, `benchmarks <id>`, `status` (with your account's notices when a key is set), `doctor` (setup check),
+`webhooks add <url> [--events …]|list|remove <id>` (signed callbacks), `transcribe <file>` (speech to text, `--translate` for English,
+`--format srt|vtt|text|verbose_json`) and `speak -o out.mp3 "text"` (text to speech, streamed to the file; US
+only for now) and `realtime --model <id> --input question.wav --output reply.wav` (one spoken turn over the realtime
+WebSocket; mono 16-bit 24 kHz WAV; paid from prepaid credits). Add `--help` to any of them.
+
+Use the key from any OpenAI SDK: `base_url = $ST_BASE_URL`, `api_key = $ST_API_KEY`.
+
+- Keys are read from `ST_API_KEY` or `./.env`, never from flags.
+- The key's prefix (`st_us_…` / `st_ca_…`) picks the region's hosts. Requests never cross regions.
+- Errors look like `{"error":{"code":"…","message":"…","hint":"…"}}`. Exit code 2 means bad usage, 1 anything else.
+
+Before the first credit purchase an account has lower limits: 60 requests/min per key and up to 5 keys.