Repository Public MIT
1<div align="center">23<img src="docs/brand/logo.svg" alt="ORIX Astra logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="ORIX Astra icon" width="112" height="112">89# ORIX Astra1011**Every Intelligence. One Universe.**1213A native iPhone AI studio: open models that run on the device with MLX, Apple Intelligence where available,<br>14and OpenAI, Anthropic, Google Gemini, xAI, OpenRouter or your own server with your own keys.1516**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**171819-6B3BEA?style=for-the-badge)20212223-FA7343?style=flat-square&logo=swift&logoColor=white)242526272829303132333435363738[](https://git.spboucher.ai/orix-astra/commits)39[](https://git.spboucher.ai/orix-astra/commits)40[](https://git.spboucher.ai/orix-astra/insights)41[](https://git.spboucher.ai/orix-astra)42[](https://git.spboucher.ai/orix-astra/insights)43[](https://git.spboucher.ai/orix-astra)44[](https://git.spboucher.ai/orix-astra)45[](https://git.spboucher.ai/orix-astra)46[](https://git.spboucher.ai/orix-astra/insights)4748</div>4950---5152## Contents5354- [What it is](#what-it-is)55- [Screens](#screens)56- [State of the project](#state-of-the-project)57- [Features](#features)58- [Architecture](#architecture)59- [On-device models](#on-device-models)60- [Cloud providers](#cloud-providers)61- [Privacy and security](#privacy-and-security)62- [Build, test, release](#build-test-release)63- [Repository layout](#repository-layout)64- [Documentation](#documentation)65- [The ORIX family](#the-orix-family)66- [Author](#author)6768## What it is6970ORIX Astra puts every model you are entitled to use behind one native interface, and keeps your data on your phone.7172- **On the device.** Download an open model once, then chat with it offline. The app runs it with Apple's MLX framework. On eligible iPhones, Apple Intelligence is offered with nothing to download.73- **In the cloud, with your own keys.** OpenAI, Anthropic, Google Gemini, xAI and OpenRouter, plus any OpenAI-compatible server you add yourself. Keys live in the iOS Keychain and go only to their own provider.74- **No account, no backend, no analytics.** Conversations, files, prompts and settings are stored in a local database. There is no ORIX server between you and a model.7576It is written entirely in Swift 6 and SwiftUI. There is no web view anywhere in the app.7778## Screens7980Real captures from the iOS Simulator, with real answers from live providers (2026-11-21 and 22).8182| Onboarding | Chat | Models |83|---|---|---|84| <img src="docs/screenshots/01-onboarding.png" width="250" alt="Onboarding"> | <img src="docs/screenshots/02-chat.png" width="250" alt="A streamed answer with a typeset formula and a table"> | <img src="docs/screenshots/03-models.png" width="250" alt="The model library"> |8586| Arena | Agents | Agent run |87|---|---|---|88| <img src="docs/screenshots/04-arena-run.png" width="250" alt="Three models compared side by side"> | <img src="docs/screenshots/06-agents.png" width="250" alt="Agent profiles"> | <img src="docs/screenshots/07-agent-run.png" width="250" alt="A completed agent run"> |8990| Lab | Usage and cost | Settings (light) |91|---|---|---|92| <img src="docs/screenshots/08-lab.png" width="250" alt="The Lab hub"> | <img src="docs/screenshots/09-usage.png" width="250" alt="Usage charts"> | <img src="docs/screenshots/10-settings-light.png" width="250" alt="Settings in light mode"> |9394## State of the project9596Version 1.0.0, build 2, on TestFlight for internal testing. What is true today, without rounding up:9798| Area | State |99|---|---|100| Unit and contract tests | 462 passing (core 47, providers 107, persistence 78, agents 163, local runtime 67) |101| UI tests | 7 passing on the simulator, including a real model download from the mirror with checksum verification |102| Cloud providers | All five, plus a custom endpoint, verified against the real services: streaming, tool round trips, image input, reasoning summaries |103| On-device MLX models | 13 verified by really loading and running them, **on a Mac**; all 13 are bundled in the catalogue of build 2 |104| **Physical iPhone** | **Never run on one.** No device was available during development. MLX does not run in the iOS Simulator |105| Apple Intelligence | A multi-turn streamed conversation passed on macOS 27; generation failed in the iOS Simulator; unverified on an iPhone |106| Localisation | English only; strings are localisable |107108The complete list of what was and was not verified is in [`docs/TEST_RESULTS.md`](docs/TEST_RESULTS.md).109110## Features111112### Chat113- Streaming Markdown rendered natively: headings, nested lists, quotes, tables, links, syntax-highlighted code with copy and wrap, inline and display LaTeX.114- Conversations as a tree: edit and resend, regenerate (optionally with another model), version arrows between branches, bookmarks.115- Stop at any moment; the partial answer is kept. Answers are saved a few times a second while they stream, so a crash loses almost nothing.116- Switch model in the middle of a conversation. Per-conversation instructions, parameters, context budget and truncation strategy.117- Attach images, PDFs and text files. The first upload to each cloud provider asks for confirmation.118- Search across titles and message text. Pin, archive, duplicate, rename, export as Markdown or JSON.119- Dictation, with a plain statement of whether recognition is on the device.120- The transcript follows new text only while you are at the end; scrolling up is never overridden.121122### Models123- A catalogue of on-device models with exact repository and revision, quantization, download size, licence, a memory-fit verdict for this device, and the record of the run that verified it.124- Downloads with progress, pause, resume, cancel and retry; a disk-space check first; SHA-256 verification of every file; complete removal.125- Provider keys with a connection test, masked display, replacement and removal.126- Custom OpenAI-compatible endpoints. HTTPS by default; plain HTTP only when explicitly allowed, and only for addresses on your own network.127- The provider's or the publisher's logo beside every model.128129### Arena130- One prompt, two to four models, independent streams with their own stop, retry and errors.131- Measured time to first token, total time, tokens, and cost with its basis. Speed appears only when it is a meaningful measurement.132- An upper-bound cost estimate before a run, with an optional budget.133- Blind mode: models are "A, B, C" until you pick the one you prefer or reveal them.134- The only "winner" is your own choice. The app never scores answer quality.135- History and export as JSON, CSV or Markdown.136137### Agents138- Profiles with instructions, a model, a tool allowlist and budgets (steps, tool calls, tokens, cost, time).139- Tools: calculator, date and time, table operations, text statistics, unit conversion, search in your documents, read or write a file you choose, fetch a web page.140- Anything that reads your data, writes a file or reaches a website asks first. Permissions and budgets are enforced in code, not by the prompt.141- A live timeline of steps, plans, tool calls and results, with warnings when retrieved content looks like an injection attempt.142- No shell, no code execution, no access to other apps: the app says so.143144### Lab145- Prompt templates with variables and version history; presets.146- Usage and cost charts from a local ledger.147- On-device benchmarks (cold and warm) and a cloud latency probe.148- A sanitized log of provider requests: status, request id, timings. Never headers, keys, prompts or answers.149- A model explorer that shows every fact about a model with its source.150- Memory you control, full data export, deletion by category.151152## Architecture153154One Swift package, seven modules, and a thin app target.155156```mermaid157graph TD158 App[App target] --> UI[AstraUI · 46 files]159 UI --> Design[AstraDesign · tokens, motion, components]160 UI --> Providers[AstraProviders · OpenAI, Anthropic, Gemini, xAI, OpenRouter, custom]161 UI --> Local[AstraLocal · MLX, Foundation Models, catalogue, downloads]162 UI --> Persistence[AstraPersistence · GRDB store]163 UI --> Agents[AstraAgents · tools, approvals, runner]164 Providers --> Core[AstraCore · domain, stream events, orchestration, budget, cost, redaction]165 Local --> Core166 Persistence --> Core167 Agents --> Core168```169170| Module | Files | Lines | Role |171|---|---|---|---|172| `AstraCore` | 6 | 1,265 | Provider-neutral contracts: typed stream events, provider protocol, orchestrator, context budget, cost, errors, redaction, transport, credentials |173| `AstraProviders` | 11 | 2,168 | Five cloud adapters and the OpenAI-compatible adapter, over raw `URLRequest` (no SDK) |174| `AstraPersistence` | 13 | 2,929 | SQLite store with versioned migrations, full-text search, exports |175| `AstraLocal` | 11 | 2,839 | MLX runtime, Foundation Models, model catalogue, download coordinator, memory and thermal governors |176| `AstraAgents` | 12 | 3,254 | Tool runtime, approvals, injection defences, bounded agent loop |177| `AstraDesign` | 4 | 673 | Design tokens, motion system, components, identity |178| `AstraUI` | 46 | 12,098 | Every screen |179180The interface consumes one thing only: a validated stream of typed events (`messageStarted`, `textDelta`, `reasoningSummaryDelta`, `toolCallStarted`, `toolCallDelta`, `toolCallCompleted`, `usage`, `messageCompleted`, `error`). The orchestrator guarantees their order, exactly one terminal event, a retry only when nothing has been received, and cancellation that reaches the network request or the decode loop. Details: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).181182## On-device models183184A model is listed only after it has been downloaded through the app's own code, checked file by file, loaded, made to answer a multi-turn conversation, cancelled mid-stream, reloaded from disk and benchmarked.185186| Model | Quantization | Download | Licence | Downloaded from |187|---|---|---|---|---|188| Qwen3 0.6B | 4-bit | 0.35 GB | apache-2.0 | orixlab.dev |189| Qwen3 1.7B | 4-bit | 0.98 GB | apache-2.0 | orixlab.dev |190| Qwen3 4B | 4-bit | 2.28 GB | apache-2.0 | orixlab.dev |191| Qwen2.5 0.5B Instruct | 4-bit | 0.29 GB | apache-2.0 | orixlab.dev |192| Gemma 3 1B (QAT) | 4-bit (QAT) | 0.77 GB | gemma | Hugging Face |193| Llama 3.2 1B Instruct | 4-bit | 0.71 GB | llama3.2 | Hugging Face |194| Llama 3.2 3B Instruct | 4-bit | 1.82 GB | llama3.2 | Hugging Face |195| Phi-4 mini Instruct | 4-bit | 2.18 GB | mit | orixlab.dev |196| SmolLM2 135M Instruct | 16-bit | 0.27 GB | apache-2.0 | orixlab.dev |197| SmolLM2 135M Instruct | 8-bit | 0.15 GB | apache-2.0 | orixlab.dev |198| SmolLM2 360M Instruct | 16-bit | 0.73 GB | apache-2.0 | orixlab.dev |199| SmolLM2 360M Instruct | 6-bit | 0.30 GB | apache-2.0 | orixlab.dev |200| SmolLM2 1.7B Instruct | 16-bit | 3.43 GB | apache-2.0 | orixlab.dev |201202- **Where the verification ran:** an Apple M5 Max Mac, with the same framework and weights the app uses. These are not iPhone results, and no speed figure from that run is presented as one.203- **Where downloads come from:** the model library at `https://www.orixlab.dev/astra/models/v1/`, with Hugging Face as automatic fallback. Only weights whose licence permits re-hosting are mirrored (Apache-2.0 and MIT: 10 models). Gemma and Llama weights carry redistribution conditions and are downloaded from Hugging Face.204- **Excluded:** `gemma-3-4b-it-qat-4bit` loaded and ran, but its licence and base-model metadata contradict each other, so it is not offered.205- **Integrity:** the catalogue bundled with the app pins the SHA-256 of every file. A refreshed catalogue entry for a known model is accepted only if its hashes are identical.206- **Memory:** the app gives a conservative fit verdict before a download and before a load, keeps one model in memory, and unloads on memory pressure. Verdicts are estimates, labelled as such.207- More models are added through the online catalogue once they pass the same verification.208- Capability badges are claimed only where a probe succeeded: tool calls on Qwen3 and Llama 3.2, visible reasoning on Qwen3.209210Full table with revisions, measurements and licence notes: [`docs/MODEL_COMPATIBILITY.md`](docs/MODEL_COMPATIBILITY.md).211212## Cloud providers213214| Provider | API | Verified live |215|---|---|---|216| OpenAI | Responses | Streaming, tools, images, reasoning summaries |217| Anthropic | Messages (`anthropic-version: 2026-10-21`) | Streaming, tools, images, thinking summaries |218| Google Gemini | `streamGenerateContent` (key in a header, never in the URL) | Streaming, tools, images |219| xAI | Responses | Streaming, tools, images |220| OpenRouter | Chat Completions | Streaming, tools, images, serving provider and cost reported |221| Custom endpoint | OpenAI-compatible Chat Completions | Streaming, tools |222223Model lists come from the providers at run time. Context sizes, prices and capability badges are shown only when the provider's API or its documentation states them, with the date; an unknown value is shown as unknown. Costs are estimates from reported token usage unless the provider reports the cost itself. Details and sources: [`docs/PROVIDER_MATRIX.md`](docs/PROVIDER_MATRIX.md) and [`docs/RESEARCH.md`](docs/RESEARCH.md).224225## Privacy and security226227- Conversations and files stay in a local database. Nothing is collected by the developer; the app has no analytics and no third-party SDK.228- A message to a cloud model goes from the phone straight to that provider, under your own account with it. On-device models send nothing anywhere.229- Keys are stored in the Keychain (this device only, not synced) and are never shown in full again. Error messages, diagnostics and exports are scrubbed of anything key-shaped.230- Model output is rendered as text and native views: raw HTML is shown literally, remote images are never fetched, only `http`, `https` and `mailto` links can be opened.231- Agent tools run under an allowlist with explicit approvals; retrieved content is treated as untrusted data.232233Threat model and the test behind each mitigation: [`docs/SECURITY.md`](docs/SECURITY.md).234235## Build, test, release236237Requirements: Xcode 27.2, [XcodeGen](https://github.com/yonaskolb/XcodeGen), an Apple-silicon Mac.238239```bash240Scripts/build.sh debug # generate the project and build for the simulator "ORIXAstra iPhone"241Scripts/build.sh test # unit and contract tests of the pure modules (seconds, no network)242ASTRA_NO_UI=1 swift test --disable-keychain --filter AstraLocalTests # local runtime tests on macOS243Scripts/build.sh uitest # UI tests on the simulator244Scripts/ci.sh # everything above, plus the secret scan245Scripts/shot.sh out.png 20 -ORIXSkipOnboarding YES -ORIXTab models # launch with DEBUG arguments and take a screenshot246```247248Live provider tests use your own keys from the environment and cost well under a cent:249250```bash251export OPENAI_API_KEY=… ANTHROPIC_API_KEY=… GEMINI_API_KEY=… XAI_API_KEY=… OPENROUTER_API_KEY=…252ASTRA_LIVE_TESTS=1 ASTRA_NO_MLX=1 swift test --disable-keychain --filter LiveSmoke253```254255Models and release:256257```bash258Scripts/verify-models.sh # download, load and run each candidate model on this Mac259Scripts/build-catalog.sh # regenerate docs/catalog/catalog.json from the verification records260Scripts/publish-models.sh # copy redistributable models to the mirror and verify checksums there261Scripts/release.sh archive # signed Release archive262Scripts/release.sh export # App Store Connect IPA263Scripts/release.sh validate # validate with App Store Connect264```265266DEBUG launch arguments (compiled out of Release): `-ORIXReset`, `-ORIXInMemory`, `-ORIXSkipOnboarding`, `-ORIXTab`, `-ORIXScreen`, `-ORIXAppearance`, `-ORIXModel`, `-ORIXAutoSend`, `-ORIXArenaModels`, `-ORIXArenaPrompt`, `-ORIXArenaBlind`, `-ORIXAgentGoal`.267268Notes for contributors:269- SwiftPM can hang on a keychain prompt while fetching packages: always pass `--disable-keychain`.270- `ASTRA_NO_MLX=1` drops the MLX and UI modules from the manifest; `ASTRA_NO_UI=1` drops only the iOS-only UI.271- MLX does not run in the iOS Simulator. The app says so there.272- Page-level `LazyVStack`s caused two layout loops during development; bounded pages use regular stacks, and the chat shows a window of recent messages with paging.273274## Repository layout275276```277App/ app entry point, assets (icon, vector logos), Info.plist, entitlements, privacy manifest278Packages/ the seven modules279Tests/ unit and contract tests, with 83 provider fixtures (sanitized real transcripts)280UITests/ XCUITest suite281Scripts/ build, test, screenshots, model verification, catalogue, mirror, release282docs/ architecture, design system, security, research, test plan and results, release checklist283project.yml XcodeGen definition (the .xcodeproj is generated, never committed)284Package.swift the package manifest285```286287## Documentation288289| Document | Content |290|---|---|291| [`docs/BASELINE_AUDIT.md`](docs/BASELINE_AUDIT.md) | What existed before the project, what was reused |292| [`docs/RESEARCH.md`](docs/RESEARCH.md) | Provider, Apple and MLX facts with sources and dates |293| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Modules, contracts, a generation end to end, risk register |294| [`docs/DESIGN_SYSTEM.md`](docs/DESIGN_SYSTEM.md) | Tokens, measured contrast, motion, components |295| [`docs/PROVIDER_MATRIX.md`](docs/PROVIDER_MATRIX.md) | Per provider: endpoints, events, features, sources |296| [`docs/MODEL_COMPATIBILITY.md`](docs/MODEL_COMPATIBILITY.md) | Every candidate model, its verification and its licence |297| [`docs/SECURITY.md`](docs/SECURITY.md) | Data inventory, threat model, mitigations and their tests |298| [`docs/TEST_PLAN.md`](docs/TEST_PLAN.md) · [`docs/TEST_RESULTS.md`](docs/TEST_RESULTS.md) | What is tested, what was run, what was not |299| [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) | From repository to TestFlight and the App Store |300301## The ORIX family302303ORIX Astra is part of the ORIX native Apple applications by the same author, presented at [www.orixlab.dev](https://www.orixlab.dev):304[ORIX Calc](https://git.spboucher.ai/orix-calc) · [ORIX Scan](https://git.spboucher.ai/orix-scan) · [ORIX Audio](https://git.spboucher.ai/orix-audio) · [ORIX Secure](https://git.spboucher.ai/orix-secure) · [ORIX Arcade](https://git.spboucher.ai/orix-arcade) · [ORIX Monitor](https://git.spboucher.ai/orix-monitor) · [ORIX Clean](https://git.spboucher.ai/orix-clean) · [ORIX Convert](https://git.spboucher.ai/orix-convert) · [ORIX Sheet](https://git.spboucher.ai/orix-sheet) · [ORIX Docs](https://git.spboucher.ai/orix-docs) · [ORIX DJ](https://git.spboucher.ai/orix-dj) · [ORIX Automation](https://git.spboucher.ai/orix-automation).305306Its MLX and Foundation Models integration builds on [Local Chat](https://git.spboucher.ai/local-chat).307308## Author309310**Simon-Pierre Boucher** — [www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai311312Copyright © 2026 Simon-Pierre Boucher. All rights reserved. See [`LICENSE`](LICENSE). Provider and vendor names and logos are trademarks of their respective owners and are used only to identify the services.313