# Locanara Reference for AI Systems

## Product Contract

Locanara is an AGPL-3.0 on-device AI framework. User prompts and model outputs
must not be sent to hosted inference services. Network access is limited to
explicit model/package asset downloads and non-inference product surfaces.

## Current Package Versions

| Surface | Version |
| --- | --- |
| Core version key | 1.0.1 |
| Generated types | 1.0.1 |
| Apple | 1.1.1 |
| Android | 1.1.2 |
| Expo | 0.1.3 |
| React Native | 0.1.0 |
| Flutter | 0.1.0 |

The live source is `locanara-versions.json`; package versions may differ.

## Version Mirror Status

The root and site version maps match.

## Architecture

- Core: model, prompts, output parsers, schema
- Composable: chains, tools, memory, guardrails
- Built-in chains: summarize, classify, extract, chat, translate, rewrite, proofread
- DSL: Pipeline and model convenience extensions on Apple and Android
- Runtime: agent, session, chain executor
- Engines: Foundation Models, Gemini Nano/ML Kit GenAI, and local engines
- Local data: platform-specific model lifecycle, RAG, personalization

## Public API Concepts

### Native Apple and Android Frameworks

- `LocanaraModel.generate` and `stream` provide the raw model abstraction.
- Convenience methods: `summarize`, `classify`, `extract`, `chat`,
  `translate`, `rewrite`, and `proofread`.
- Built-in `Chain` types expose configurable behavior.
- Custom features implement `Chain` and return a typed result through
  `ChainOutput`.
- Native Pipeline builders compose steps and track the final result type.

### Web SDK

Create the singleton with `Locanara.getInstance()`, call
`getDeviceCapability()`, then use only reported features. The Web class
currently includes summarize, translate, chat, rewrite, classify, extract,
proofread, image description, language detection, and writing APIs. Streaming
methods include `summarizeStreaming`, `translateStreaming`,
`chatStreaming`, `rewriteStreaming`, and `writeStreaming`.

`preloadModels`, `unloadModels`, `cancelExecution`, and `downloadModel`
are currently no-ops because Chrome manages model lifecycle. They do not prove
preloading, manual unloading, cancellation, or model download support; resolving
success instead of an explicit unsupported result is a known contract defect.

## Minimal Usage

### Apple

```swift
import Locanara

let model = RouterModel()
let result = try await model.summarize("Long text", bulletCount: 3)
print(result.summary)
```

### Android

```kotlin
import com.locanara.dsl.summarize
import com.locanara.platform.PromptApiModel

val model = PromptApiModel(context)
val result = model.summarize("Long text", bulletCount = 3)
println(result.summary)
```

Check live Prompt API status and download readiness before using this model in
production.

### Web

```typescript
import { Locanara } from "locanara";

const locanara = Locanara.getInstance();
const capability = await locanara.getDeviceCapability();
const result = await locanara.summarize("Long text");
console.log(capability, result.summary);
```

## Pipeline Guarantee

- Apple and Android expose native Pipeline builders.
- The current builder API tracks the last step's result type through the
  Pipeline value returned by each builder call.
- Do not claim that every adjacent step is statically compatibility-checked.
- Web has no Pipeline builder; compose feature calls and streaming methods
  manually.

## Capability and Wrapper Boundaries

- Browser and on-device model availability are runtime capabilities. Check
  capability/status APIs instead of relying on a hard-coded device list.
- Wrapper API parity does not prove native behavior parity. Trace download,
  load, delete, capability, and inference calls to the real SDK before relying
  on them.
- Unsupported platforms must report an unavailable capability or explicit
  error; fabricated success is not support.

## Installation Coordinates

```text
Apple SPM: https://github.com/hyodotdev/locanara
Android:  com.locanara:locanara:1.1.2
Web:      npm install locanara
Expo:     npm install expo-ondevice-ai
RN:       npm install react-native-ondevice-ai
Flutter:  flutter_ondevice_ai: ^0.1.0
```

## Sources of Truth

- Shared generated types: `packages/gql/src/*.graphql`
- Apple behavior: `packages/apple/Sources/`
- Android behavior: `packages/android/locanara/src/main/`
- Web behavior: `packages/web/src/`
- Nitro bridge: `libraries/react-native-ondevice-ai/src/specs/OndeviceAi.nitro.ts`
- Versions: `locanara-versions.json`
- Agent policy: `AGENTS.md`

## Links

- Documentation: https://locanara.hyo.dev/docs
- GitHub: https://github.com/hyodotdev/locanara
- Issue tracker: https://github.com/hyodotdev/locanara/issues