Little Box

Little Box is a privacy-first conversation workspace for chat, writing, translation, coding help, and document reading. One Vite client runs in the browser, as an installed progressive web app, and inside a Capacitor Android shell. People bring their own model keys. Conversation state and parsed files stay on the device unless a feature explicitly calls the network.

The picture above is the product illustration shipped with this folder. The running client is not a React or Python service. It is the Vite application in this repository, package littleaibox, version 3.0.7. The live site is littleaibox.com.

npm install
npm run dev
npm run build

predev and prebuild run scripts/copy-i18n.mjs before Vite. Put model keys in the application UI. Do not commit them.

Voice input, task presets, mind maps, and an optional research mode live in the same client. Share pages, policy pages, and subscription screens are routes, not a second product.

flowchart LR
  surface[Browser, PWA, or Android] --> client[Vite client]
  client --> local[Parsers and IndexedDB]
  client --> origin[littleaibox.com]
  origin --> spare[pages.dev fallback]

On the public website, relative API calls stay on that site. On Android, and on localhost, 127.0.0.1, or ::1, src/api-config.js rewrites API traffic.

A path counts as API traffic when it starts with /api/, /auth/, /image-proxy, or /image-get, or when the method is not GET or HEAD and the path is /.

$$ O = \langle o_{\mathrm{preferred}},\ \texttt{https://littleaibox.com},\ \texttt{https://littleaibox.pages.dev} \rangle $$

The preferred value is kept only when it is already one of those two hosts. The client tries the list in order. Status 502, 503, or 504, or a thrown network error, advances to the next origin. Any other status returns immediately. The first successful response is written to localStorage under preferred_api_origin.

flowchart TD
  call[API call from native or localhost] --> list[Walk the origin list]
  list --> ok{Response ok?}
  ok -->|yes| remember[Store preferred_api_origin]
  ok -->|502, 503, 504 or network error| next[Try the next origin]
  next --> list
  ok -->|other status| stop[Return that response]

Two user-supplied keys are supported. Older records may keep both inside custom_api_key as a comma-separated pair. Newer records keep the second key in custom_api_key_t. Sanitized copies of the user object delete both fields before they are stored for display. A hint flag records only that a key exists, not the key itself.

src/relay-models.js turns a relay id into a label. A leading models/ is removed. The first token selects the brand.

Adjacent numeric tokens become one dotted number, so 3 and 5 read as 3.5. A token shaped like v2 becomes V2.

The marks above are the icons already stored under public/ai_icons/. They are labels for the relay, not proof that a particular host is configured.

An Office fraction node f becomes LaTeX. The numerator and denominator are the OMML children num and den.

$$ \texttt{f}(\mathrm{num},\mathrm{den}) \mapsto \frac{\mathrm{num}}{\mathrm{den}} $$

The same converter in src/file-parsers/mathUtils.js emits the rest of the common Office math forms.

Property tags that end in Pr, and the ignored presentation tags listed in that file, contribute no text. Replies can then be drawn with Mermaid (src/mermaid-renderer.js), Vega-Lite (src/vega-renderer.js), or a markmap mind map (src/mindmap-mode.js). Mind map scripts load from /libs/d3.min.js, /libs/markmap-lib.js, /libs/markmap-view.js, and /libs/markmap-toolbar.js.

While a reply streams, image URLs are scanned on a 30 millisecond timer.

$$ \Delta t_{\mathrm{stream}} = 30,\mathrm{ms} $$

The scanner in src/stream-image-runtime.js accepts Markdown images and bare URLs whose path ends in png, jpg, jpeg, webp, gif, bmp, svg, or avif.

IndexedDB database LittleAIBoxDB is version 2. It has two object stores.

$$ \mathrm{chats}(\mathrm{userId}) = \begin{cases} \mathrm{chatsData} & \text{when the record exists} \\ \mathrm{null} & \text{when the read fails or the record is missing} \end{cases} $$

getChatsFromDB returns null on failure instead of throwing. saveChatsToDB writes the whole chat blob for that user. clearChatsStore removes every user, not one conversation.

Pending work that must survive a reload uses src/sync-queue.js. The storage key adds the user id when one is present.

$$ k(\mathrm{base},\mathrm{user}) = \begin{cases} \mathrm{base} & \text{if no user id is set} \\ \mathrm{base},\Vert,\texttt{"_"},\Vert,\mathrm{user} & \text{otherwise} \end{cases} $$

A saved queue is { items, order }. upsertQueueItem writes the item and appends the id only when it is not already in order. removeQueueItem deletes the item and drops that id from the order. An empty queue removes the localStorage key. If a newer per-user key is missing and a legacy key still holds data, the loader copies the legacy value and deletes the old key.

The service worker is src/sw-custom.js, injected by Vite PWA. A precached file may be at most 4 MiB.

$$ 4 \times 1024^{2} = 4,194,304 \text{ bytes} $$

One day is (86,400) seconds. The runtime rules in vite.config.js are:

GET /api/chats/ and GET /auth/me may use the network-first cache. Mutations do not. Favicon and apple-touch icons are left out of the precache glob.

The production build minifies with Terser, runs two compress passes, drops console and debugger, and stamps __APP_BUILD_ID__.

$$ \mathrm{buildId} = \mathrm{APP_BUILD_ID} \lor \mathrm{VERCEL_GIT_COMMIT_SHA} \lor \mathrm{CF_PAGES_COMMIT_SHA} \lor \mathrm{GITHUB_SHA} \lor \mathrm{ISO\ time} $$

The first of those values that is set wins. Vendor modules are split into a vendor chunk. The chunk-size warning starts at 700 kB.

src/entitlements.js is the only place these numbers are defined. monthly, quarterly, and yearly all normalize to the plan code pro. A missing or unknown code stays unset.

Character and rich-document decisions look at hasPaidKey first, then an active subscription, then the free row. Chat and cloud-sync decisions look at a paid tier together with a custom key before they look at the subscription. A custom key that is not on the paid tier still lifts the chat ceiling to at least 25:

$$ L_{\mathrm{chat}} = \begin{cases} \infty & \text{if the tier is paid and a custom key is present} \\ \max(L_{\mathrm{base}}, 25) & \text{if a custom key is present} \\ L_{\mathrm{base}} & \text{otherwise} \end{cases} $$

(L_{\mathrm{base}}) is 60 when a subscription is active and 15 otherwise. Image count ignores the key and follows only the subscription: 10 or 5.

src/apk-update-manager.js reads download HTML for links whose file name matches LittleAIBox_v plus a dotted number plus .apk. Each candidate is compared with the best one seen so far. The compare splits on dots, parses each part as an integer, and treats a missing or non-numeric part as 0.

$$ c(a,b) = \begin{cases} 1 & \text{if the first differing part of } a \text{ is greater} \\ -1 & \text{if the first differing part of } a \text{ is smaller} \\ 0 & \text{if every part matches} \end{cases} $$

The longer string wins the length of the walk. 1.2 and 1.2.0 therefore compare equal. The native client repeats the check on this interval:

$$ 15 \times 60 \times 1000 = 900,000,\mathrm{ms} $$

A file name is reduced to its last path segment before that match, so a slash or backslash cannot smuggle a directory into the saved name.

src/router.js maps the address bar to a route name. Identifiers are encoded on the way out and decoded on the way in. An empty path is home. The history state uses __labRoot so the shell can tell its own entries from the browser's.

Temporary chats and saved chats share the settings and subscription shapes. Only the first segment changes, from chat to temp_chat.

Interface strings ship in public/locales/ for English, Spanish, French, Japanese, Korean, Simplified Chinese, and Traditional Chinese. Longer notes in those languages also sit under docs/. scripts/copy-i18n.mjs runs before both dev and build, so a locale edit is copied before Vite sees it. The English brief in this file is the source to read first.

A saved language in localStorage (selectedLanguage) or sessionStorage (guest_selectedLanguage) is applied before the page paints. When neither is set, the document language is English.

There is no separate test script in package.json. Behavior that must stay stable is pinned by the modules cited above: origin order, store keys, entitlement numbers, cache ages, and the version compare.

The mark and the model icons are assets already shipped with the client. The illustration is the picture placed in this folder. The diagrams were drawn for this brief from api-config.js, db.js, entitlements.js, apk-update-manager.js, vite.config.js, and the file parsers.