SPB Git

Repository Public MIT

README.md 21.0 KB

ORIX Astra logo



ORIX Astra icon

# ORIX Astra

Every Intelligence. One Universe.

A native iPhone AI studio: open models that run on the device with MLX, Apple Intelligence where available,
and OpenAI, Anthropic, Google Gemini, xAI, OpenRouter or your own server with your own keys.

Author: Simon-Pierre Boucher

iOS Version Status author

Swift SwiftUI MLX Swift LM MLX Swift Foundation Models GRDB SwiftMath swift-markdown

tests providers models analytics account

commits last commit activity language languages size branches tags clones


# Contents

# What it is

ORIX Astra puts every model you are entitled to use behind one native interface, and keeps your data on your phone.

  • 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.
  • 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.
  • 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.

It is written entirely in Swift 6 and SwiftUI. There is no web view anywhere in the app.

# Screens

Real captures from the iOS Simulator, with real answers from live providers (2026-11-21 and 22).

Onboarding Chat Models
Onboarding A streamed answer with a typeset formula and a table The model library
Arena Agents Agent run
Three models compared side by side Agent profiles A completed agent run
Lab Usage and cost Settings (light)
The Lab hub Usage charts Settings in light mode

# State of the project

Version 1.0.0, build 2, on TestFlight for internal testing. What is true today, without rounding up:

Area State
Unit and contract tests 462 passing (core 47, providers 107, persistence 78, agents 163, local runtime 67)
UI tests 7 passing on the simulator, including a real model download from the mirror with checksum verification
Cloud providers All five, plus a custom endpoint, verified against the real services: streaming, tool round trips, image input, reasoning summaries
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
Physical iPhone Never run on one. No device was available during development. MLX does not run in the iOS Simulator
Apple Intelligence A multi-turn streamed conversation passed on macOS 27; generation failed in the iOS Simulator; unverified on an iPhone
Localisation English only; strings are localisable

The complete list of what was and was not verified is in docs/TEST_RESULTS.md.

# Features

# Chat

  • Streaming Markdown rendered natively: headings, nested lists, quotes, tables, links, syntax-highlighted code with copy and wrap, inline and display LaTeX.
  • Conversations as a tree: edit and resend, regenerate (optionally with another model), version arrows between branches, bookmarks.
  • 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.
  • Switch model in the middle of a conversation. Per-conversation instructions, parameters, context budget and truncation strategy.
  • Attach images, PDFs and text files. The first upload to each cloud provider asks for confirmation.
  • Search across titles and message text. Pin, archive, duplicate, rename, export as Markdown or JSON.
  • Dictation, with a plain statement of whether recognition is on the device.
  • The transcript follows new text only while you are at the end; scrolling up is never overridden.

# Models

  • 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.
  • Downloads with progress, pause, resume, cancel and retry; a disk-space check first; SHA-256 verification of every file; complete removal.
  • Provider keys with a connection test, masked display, replacement and removal.
  • Custom OpenAI-compatible endpoints. HTTPS by default; plain HTTP only when explicitly allowed, and only for addresses on your own network.
  • The provider's or the publisher's logo beside every model.

# Arena

  • One prompt, two to four models, independent streams with their own stop, retry and errors.
  • Measured time to first token, total time, tokens, and cost with its basis. Speed appears only when it is a meaningful measurement.
  • An upper-bound cost estimate before a run, with an optional budget.
  • Blind mode: models are "A, B, C" until you pick the one you prefer or reveal them.
  • The only "winner" is your own choice. The app never scores answer quality.
  • History and export as JSON, CSV or Markdown.

# Agents

  • Profiles with instructions, a model, a tool allowlist and budgets (steps, tool calls, tokens, cost, time).
  • 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.
  • 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.
  • A live timeline of steps, plans, tool calls and results, with warnings when retrieved content looks like an injection attempt.
  • No shell, no code execution, no access to other apps: the app says so.

# Lab

  • Prompt templates with variables and version history; presets.
  • Usage and cost charts from a local ledger.
  • On-device benchmarks (cold and warm) and a cloud latency probe.
  • A sanitized log of provider requests: status, request id, timings. Never headers, keys, prompts or answers.
  • A model explorer that shows every fact about a model with its source.
  • Memory you control, full data export, deletion by category.

# Architecture

One Swift package, seven modules, and a thin app target.

graph TD
    App[App target] --> UI[AstraUI · 46 files]
    UI --> Design[AstraDesign · tokens, motion, components]
    UI --> Providers[AstraProviders · OpenAI, Anthropic, Gemini, xAI, OpenRouter, custom]
    UI --> Local[AstraLocal · MLX, Foundation Models, catalogue, downloads]
    UI --> Persistence[AstraPersistence · GRDB store]
    UI --> Agents[AstraAgents · tools, approvals, runner]
    Providers --> Core[AstraCore · domain, stream events, orchestration, budget, cost, redaction]
    Local --> Core
    Persistence --> Core
    Agents --> Core
Module Files Lines Role
AstraCore 6 1,265 Provider-neutral contracts: typed stream events, provider protocol, orchestrator, context budget, cost, errors, redaction, transport, credentials
AstraProviders 11 2,168 Five cloud adapters and the OpenAI-compatible adapter, over raw URLRequest (no SDK)
AstraPersistence 13 2,929 SQLite store with versioned migrations, full-text search, exports
AstraLocal 11 2,839 MLX runtime, Foundation Models, model catalogue, download coordinator, memory and thermal governors
AstraAgents 12 3,254 Tool runtime, approvals, injection defences, bounded agent loop
AstraDesign 4 673 Design tokens, motion system, components, identity
AstraUI 46 12,098 Every screen

The 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.

# On-device models

A 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.

Model Quantization Download Licence Downloaded from
Qwen3 0.6B 4-bit 0.35 GB apache-2.0 orixlab.dev
Qwen3 1.7B 4-bit 0.98 GB apache-2.0 orixlab.dev
Qwen3 4B 4-bit 2.28 GB apache-2.0 orixlab.dev
Qwen2.5 0.5B Instruct 4-bit 0.29 GB apache-2.0 orixlab.dev
Gemma 3 1B (QAT) 4-bit (QAT) 0.77 GB gemma Hugging Face
Llama 3.2 1B Instruct 4-bit 0.71 GB llama3.2 Hugging Face
Llama 3.2 3B Instruct 4-bit 1.82 GB llama3.2 Hugging Face
Phi-4 mini Instruct 4-bit 2.18 GB mit orixlab.dev
SmolLM2 135M Instruct 16-bit 0.27 GB apache-2.0 orixlab.dev
SmolLM2 135M Instruct 8-bit 0.15 GB apache-2.0 orixlab.dev
SmolLM2 360M Instruct 16-bit 0.73 GB apache-2.0 orixlab.dev
SmolLM2 360M Instruct 6-bit 0.30 GB apache-2.0 orixlab.dev
SmolLM2 1.7B Instruct 16-bit 3.43 GB apache-2.0 orixlab.dev
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • More models are added through the online catalogue once they pass the same verification.
  • Capability badges are claimed only where a probe succeeded: tool calls on Qwen3 and Llama 3.2, visible reasoning on Qwen3.

Full table with revisions, measurements and licence notes: docs/MODEL_COMPATIBILITY.md.

# Cloud providers

Provider API Verified live
OpenAI Responses Streaming, tools, images, reasoning summaries
Anthropic Messages (anthropic-version: 2026-10-21) Streaming, tools, images, thinking summaries
Google Gemini streamGenerateContent (key in a header, never in the URL) Streaming, tools, images
xAI Responses Streaming, tools, images
OpenRouter Chat Completions Streaming, tools, images, serving provider and cost reported
Custom endpoint OpenAI-compatible Chat Completions Streaming, tools

Model 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 and docs/RESEARCH.md.

# Privacy and security

  • Conversations and files stay in a local database. Nothing is collected by the developer; the app has no analytics and no third-party SDK.
  • 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.
  • 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.
  • 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.
  • Agent tools run under an allowlist with explicit approvals; retrieved content is treated as untrusted data.

Threat model and the test behind each mitigation: docs/SECURITY.md.

# Build, test, release

Requirements: Xcode 27.2, XcodeGen, an Apple-silicon Mac.

bash
Scripts/build.sh debug            # generate the project and build for the simulator "ORIXAstra iPhone"
Scripts/build.sh test             # unit and contract tests of the pure modules (seconds, no network)
ASTRA_NO_UI=1 swift test --disable-keychain --filter AstraLocalTests   # local runtime tests on macOS
Scripts/build.sh uitest           # UI tests on the simulator
Scripts/ci.sh                     # everything above, plus the secret scan
Scripts/shot.sh out.png 20 -ORIXSkipOnboarding YES -ORIXTab models     # launch with DEBUG arguments and take a screenshot

Live provider tests use your own keys from the environment and cost well under a cent:

bash
export OPENAI_API_KEY=… ANTHROPIC_API_KEY=… GEMINI_API_KEY=… XAI_API_KEY=… OPENROUTER_API_KEY=…
ASTRA_LIVE_TESTS=1 ASTRA_NO_MLX=1 swift test --disable-keychain --filter LiveSmoke

Models and release:

bash
Scripts/verify-models.sh          # download, load and run each candidate model on this Mac
Scripts/build-catalog.sh          # regenerate docs/catalog/catalog.json from the verification records
Scripts/publish-models.sh         # copy redistributable models to the mirror and verify checksums there
Scripts/release.sh archive        # signed Release archive
Scripts/release.sh export         # App Store Connect IPA
Scripts/release.sh validate       # validate with App Store Connect

DEBUG launch arguments (compiled out of Release): -ORIXReset, -ORIXInMemory, -ORIXSkipOnboarding, -ORIXTab, -ORIXScreen, -ORIXAppearance, -ORIXModel, -ORIXAutoSend, -ORIXArenaModels, -ORIXArenaPrompt, -ORIXArenaBlind, -ORIXAgentGoal.

Notes for contributors:

  • SwiftPM can hang on a keychain prompt while fetching packages: always pass --disable-keychain.
  • ASTRA_NO_MLX=1 drops the MLX and UI modules from the manifest; ASTRA_NO_UI=1 drops only the iOS-only UI.
  • MLX does not run in the iOS Simulator. The app says so there.
  • Page-level LazyVStacks caused two layout loops during development; bounded pages use regular stacks, and the chat shows a window of recent messages with paging.

# Repository layout

text
App/                 app entry point, assets (icon, vector logos), Info.plist, entitlements, privacy manifest
Packages/            the seven modules
Tests/               unit and contract tests, with 83 provider fixtures (sanitized real transcripts)
UITests/             XCUITest suite
Scripts/             build, test, screenshots, model verification, catalogue, mirror, release
docs/                architecture, design system, security, research, test plan and results, release checklist
project.yml          XcodeGen definition (the .xcodeproj is generated, never committed)
Package.swift        the package manifest

# Documentation

Document Content
docs/BASELINE_AUDIT.md What existed before the project, what was reused
docs/RESEARCH.md Provider, Apple and MLX facts with sources and dates
docs/ARCHITECTURE.md Modules, contracts, a generation end to end, risk register
docs/DESIGN_SYSTEM.md Tokens, measured contrast, motion, components
docs/PROVIDER_MATRIX.md Per provider: endpoints, events, features, sources
docs/MODEL_COMPATIBILITY.md Every candidate model, its verification and its licence
docs/SECURITY.md Data inventory, threat model, mitigations and their tests
docs/TEST_PLAN.md · docs/TEST_RESULTS.md What is tested, what was run, what was not
docs/RELEASE_CHECKLIST.md From repository to TestFlight and the App Store

# The ORIX family

ORIX Astra is part of the ORIX native Apple applications by the same author, presented at www.orixlab.dev: ORIX Calc · ORIX Scan · ORIX Audio · ORIX Secure · ORIX Arcade · ORIX Monitor · ORIX Clean · ORIX Convert · ORIX Sheet · ORIX Docs · ORIX DJ · ORIX Automation.

Its MLX and Foundation Models integration builds on Local Chat.

# Author

Simon-Pierre Boucher — www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai

Copyright © 2026 Simon-Pierre Boucher. All rights reserved. See LICENSE. Provider and vendor names and logos are trademarks of their respective owners and are used only to identify the services.

Files main
Menu

Theme