diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml
index 8ece14b..3898939 100644
--- a/.github/workflows/desktop.yml
+++ b/.github/workflows/desktop.yml
@@ -271,7 +271,7 @@ jobs:
- platform: ubuntu-22.04
# Verbose so a linuxdeploy (AppImage) failure shows its cause.
args: '--verbose'
- - platform: macos-14
+ - platform: macos-15
args: '--target universal-apple-darwin'
- platform: windows-latest
args: ''
@@ -307,7 +307,7 @@ jobs:
# `xcrun` is preinstalled on macOS runners, hence placement before the
# toolchain steps rather than next to "Configure Apple signing".
- name: Preflight Apple notarization credentials
- if: matrix.platform == 'macos-14'
+ if: matrix.platform == 'macos-15'
env:
CERT: ${{ secrets.APPLE_CERTIFICATE }}
A_ID: ${{ secrets.APPLE_ID }}
@@ -411,7 +411,7 @@ jobs:
with:
# macOS builds a universal app; Windows ARM64 also builds the x64
# locus_rust wheel for its emulated Python backend.
- targets: ${{ matrix.platform == 'macos-14' && 'aarch64-apple-darwin,x86_64-apple-darwin' || matrix.platform == 'windows-11-arm' && 'x86_64-pc-windows-msvc' || '' }}
+ targets: ${{ matrix.platform == 'macos-15' && 'aarch64-apple-darwin,x86_64-apple-darwin' || matrix.platform == 'windows-11-arm' && 'x86_64-pc-windows-msvc' || '' }}
- name: Rust cache
uses: swatinem/rust-cache@v2
@@ -444,7 +444,7 @@ jobs:
OLLAMA_TARGET: ${{ matrix.target }}
run: |
cd frontend/src-tauri/scripts && chmod +x download-ollama.sh
- if [[ "${{ matrix.platform }}" == "macos-14" ]]; then
+ if [[ "${{ matrix.platform }}" == "macos-15" ]]; then
# Tauri builds each architecture first, then bundles the universal
# app. Ollama's darwin archive already contains both slices, so
# download it once and supply all three names Tauri looks for.
@@ -473,7 +473,7 @@ jobs:
run: |
cd frontend/src-tauri/scripts
case "${{ matrix.platform }}" in
- macos-14)
+ macos-15)
./download-uv.sh universal-apple-darwin
for arch in aarch64 x86_64; do
cp ../binaries/uv-universal-apple-darwin "../binaries/uv-${arch}-apple-darwin"
diff --git a/.github/workflows/installer-integration.yml b/.github/workflows/installer-integration.yml
index 515fffc..741a30e 100644
--- a/.github/workflows/installer-integration.yml
+++ b/.github/workflows/installer-integration.yml
@@ -85,7 +85,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- os: [macos-14, macos-15]
+ os: [macos-15]
steps:
- uses: actions/checkout@v7
diff --git a/README.md b/README.md
index f62c5d0..5b251ac 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,8 @@ Locus is that stack. It is a framework for local-first personal AI, built around
## What Locus can do
- **Chat on your PC:** talk to a local AI model in the desktop app, your browser, or the terminal, by typing or by voice.
+- **Attach files and images:** drop documents (PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, HTML, CSV, code, plain text and more) or images into a chat and ask about them. Images need a vision model such as `qwen3.5` or `gemma3`.
+- **Search the web:** turn on **Web search** and Locus looks up your question online first, reads the top pages, and answers with numbered links to its sources. It's off until you turn it on, since it sends your question to a search engine.
- **Work with your files:** read and write files and PDFs, search your own documents, run code in a sandbox, and remember facts between conversations.
- **Connect your apps:** Gmail, Outlook, Google Calendar, Google Drive, Dropbox, Notion, Obsidian, GitHub, Slack and more, each only after you sign in.
- **Reply on messaging apps:** run it as a bot on Telegram, Slack, Discord, WhatsApp, Teams, Signal, email, SMS and about 25 other channels.
@@ -188,6 +190,7 @@ Full documentation—including Docker deployment, cloud engines, development set
- **Local by default:** models run on your machine through Ollama or another local engine. Nothing goes to a cloud model unless you add your own API key.
- **No analytics:** Locus ships with no analytics destination, so no usage data is sent anywhere. See [telemetry](https://aryanjsx.github.io/Locus/telemetry/) for details.
+- **Attachments stay local:** attached files are read by Locus on your machine and kept in the app's own storage. Web search is off by default; when you turn it on, only your question goes to the search engine, never your files.
- **Opt-in connections:** email, calendar, messaging and other services only work after you connect them, and the data you index stays on your machine.
- **Approval for risky actions:** shell commands and similar tools go through an approval step first.
diff --git a/docs/leaderboard.md b/docs/leaderboard.md
index d8b7d49..9cb0b5a 100644
--- a/docs/leaderboard.md
+++ b/docs/leaderboard.md
@@ -7,8 +7,8 @@ hide:
See how the Locus community saves money, energy, and compute by running AI locally instead of using cloud providers.
-!!! info "Win a Mac Mini!"
- Opt in to share your savings from the Locus browser app or desktop app for a chance to win a Mac Mini. Your data is fully anonymous — no email, no IP, no hardware info.
+!!! info "Sharing is opt-in"
+ You can choose to share your savings from the Locus browser app or desktop app. Nothing is shared unless you opt in.
diff --git a/docs/telemetry.md b/docs/telemetry.md
index 937b612..ee89943 100644
--- a/docs/telemetry.md
+++ b/docs/telemetry.md
@@ -49,22 +49,16 @@ changed. Configurations without an analytics setting now default to off.
Local performance telemetry and Savings Leaderboard participation remain
separate settings.
-In the browser and desktop apps, the existing **Share Your Savings** dialog
-offers explicit buttons without a checkbox. Displaying or closing the dialog
-does not enable analytics. Confirm with **Enable analytics only** or
-**Enable analytics & enter giveaway**, or use **Continue without sharing**
-to turn analytics off. A saved UI choice takes effect immediately in both
-the frontend and the running backend.
-
-Joining the leaderboard requires a display name and contact email submitted
-with savings to the configured Supabase leaderboard. Analytics preferences
-send only the on/off choice to the local server; names and emails are not
-attached to PostHog usage events by this form. The existing Mac mini
-promotion concerns leaderboard participation, not analytics consent.
-Use **Enter giveaway only** to join with analytics off; submitting the
-name/email form with Enter also uses that option. Stopping leaderboard
-updates and disabling usage analytics are separate actions. Stopping updates
-does not delete previously submitted entries from Supabase.
+The browser and desktop apps don't ask about analytics on first launch.
+The first-launch dialog only asks for your name, so Locus knows what to call
+you; it's saved on your computer in `~/.locus/USER.md` and never sent
+anywhere.
+
+Joining the Savings Leaderboard, from the Savings dashboard, requires a
+display name and contact email submitted with savings to the configured
+Supabase leaderboard. It's separate from usage analytics, and names and
+emails are never attached to analytics events. Stopping leaderboard updates
+doesn't delete previously submitted entries from Supabase.
## What we collect
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index caf7f55..c2d9acc 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -13,10 +13,10 @@ import { SetupScreen } from './components/SetupScreen';
import { Toaster } from './components/ui/sonner';
import { useAppStore } from './lib/store';
import { fetchModels, fetchServerInfo, fetchSavings, submitSavings, isTauri } from './lib/api';
-import { OptInModal } from './components/OptInModal';
+import { ProfileModal } from './components/ProfileModal';
import { UpdateChecker } from './components/Desktop/UpdateChecker';
import { track, hashId } from './lib/analytics';
-import { offerAnalyticsChoice } from './lib/analytics-invitation';
+import { fetchProfile, offerProfilePrompt } from './lib/profile';
export default function App() {
const [setupDone, setSetupDone] = useState(!isTauri());
@@ -42,10 +42,9 @@ export default function App() {
const optInDisplayName = useAppStore((s) => s.optInDisplayName);
const optInEmail = useAppStore((s) => s.optInEmail);
const optInAnonId = useAppStore((s) => s.optInAnonId);
- const optInModalSeen = useAppStore((s) => s.optInModalSeen);
- const optInModalOpen = useAppStore((s) => s.optInModalOpen);
- const setOptInModalOpen = useAppStore((s) => s.setOptInModalOpen);
- const markOptInModalSeen = useAppStore((s) => s.markOptInModalSeen);
+ const profileModalOpen = useAppStore((s) => s.profileModalOpen);
+ const setProfileModalOpen = useAppStore((s) => s.setProfileModalOpen);
+ const setProfile = useAppStore((s) => s.setProfile);
const savings = useAppStore((s) => s.savings);
// Apply theme class to
@@ -118,13 +117,12 @@ export default function App() {
return () => clearInterval(interval);
}, [optInEnabled, optInDisplayName, optInEmail, optInAnonId]); // eslint-disable-line react-hooks/exhaustive-deps
- // Wait for desktop setup before fetching identity or marking the dialog seen.
- useEffect(() => offerAnalyticsChoice({
- ready: setupDone,
- sharingModalSeen: optInModalSeen,
- open: () => setOptInModalOpen(true),
- markSharingModalSeen: markOptInModalSeen,
- }), [setupDone, optInModalSeen, setOptInModalOpen, markOptInModalSeen]);
+ // Once the backend is up, load the user's name and ask for it once.
+ useEffect(() => {
+ if (!setupDone) return;
+ fetchProfile().then(setProfile).catch(() => {});
+ offerProfilePrompt({ ready: setupDone, open: () => setProfileModalOpen(true) });
+ }, [setupDone, setProfile, setProfileModalOpen]);
// Fire model_changed when the user switches models. First mount is
// not a "change" — only emit when both prev and current are real and
@@ -195,8 +193,8 @@ export default function App() {
{commandPaletteOpen &&
}
- {optInModalOpen && (
-
setOptInModalOpen(false)} />
+ {profileModalOpen && (
+ setProfileModalOpen(false)} />
)}
>
);
diff --git a/frontend/src/components/Chat/AttachmentChip.tsx b/frontend/src/components/Chat/AttachmentChip.tsx
new file mode 100644
index 0000000..b4bf301
--- /dev/null
+++ b/frontend/src/components/Chat/AttachmentChip.tsx
@@ -0,0 +1,77 @@
+import { AlertCircle, FileText, Loader2, X } from 'lucide-react';
+import { formatBytes } from '../../lib/attachments';
+import type { AttachmentMeta } from '../../types';
+
+interface Props {
+ name: string;
+ meta?: AttachmentMeta;
+ status?: 'reading' | 'ready' | 'error';
+ error?: string;
+ onRemove?: () => void;
+}
+
+/** One attached file: a thumbnail or file icon, its name, and what it is. */
+export function AttachmentChip({ name, meta, status = 'ready', error, onRemove }: Props) {
+ const problem = status === 'error' ? error : meta?.kind === 'unsupported' ? meta.note : undefined;
+ const detail =
+ status === 'reading'
+ ? 'Reading...'
+ : status === 'error'
+ ? "Couldn't read"
+ : meta
+ ? [meta.format, formatBytes(meta.size), meta.truncated ? 'long, will be shortened' : '']
+ .filter(Boolean)
+ .join(' · ')
+ : '';
+
+ return (
+
+ {meta?.thumbnail ? (
+
+ ) : (
+
+ {status === 'reading' ? (
+
+ ) : problem ? (
+
+ ) : (
+
+ )}
+
+ )}
+
+
+ {name}
+
+
+ {detail}
+
+
+ {onRemove && (
+
+
+
+ )}
+
+ );
+}
diff --git a/frontend/src/components/Chat/InputArea.tsx b/frontend/src/components/Chat/InputArea.tsx
index d0b2855..541f5c0 100644
--- a/frontend/src/components/Chat/InputArea.tsx
+++ b/frontend/src/components/Chat/InputArea.tsx
@@ -1,5 +1,5 @@
import { useState, useRef, useCallback, useEffect } from 'react';
-import { Send, Square, Paperclip, Search } from 'lucide-react';
+import { Send, Square, Paperclip, Search, Globe } from 'lucide-react';
import { toast } from 'sonner';
import { useAppStore, generateId } from '../../lib/store';
import { streamChat, streamResearch } from '../../lib/sse';
@@ -11,8 +11,18 @@ import {
resolveChatEngine,
} from '../../lib/chat-telemetry';
import { MicButton } from './MicButton';
+import { AttachmentChip } from './AttachmentChip';
import { useSpeech } from '../../hooks/useSpeech';
+import {
+ apiAttachmentFields,
+ deletePayloads,
+ MAX_FILE_BYTES,
+ MAX_FILES_PER_MESSAGE,
+ readAttachments,
+ savePayload,
+} from '../../lib/attachments';
import type {
+ AttachmentMeta,
ChatMessage,
MessageTelemetry,
ResearchSearchTrace,
@@ -21,6 +31,15 @@ import type {
ToolCallInfo,
} from '../../types';
+/** A file in the input box: being read by the server, ready, or failed. */
+interface PendingAttachment {
+ key: string;
+ name: string;
+ status: 'reading' | 'ready' | 'error';
+ meta?: AttachmentMeta;
+ error?: string;
+}
+
// While Deep Research is toggled on, poll connected sources for sync
// progress so we can surface "Searching over N items — sync in progress"
// next to the toggle. Polling is gated on `enabled` so toggling DR off
@@ -100,7 +119,76 @@ export function InputArea() {
const modelLoading = useAppStore((s) => s.modelLoading);
const deepResearch = useAppStore((s) => s.deepResearch);
const setDeepResearch = useAppStore((s) => s.setDeepResearch);
+ const webSearch = useAppStore((s) => s.webSearch);
+ const setWebSearch = useAppStore((s) => s.setWebSearch);
+ const setLastAssistantWebSearch = useAppStore((s) => s.setLastAssistantWebSearch);
const corpusSync = useResearchCorpusSync(deepResearch);
+
+ const [pending, setPending] = useState([]);
+ const [dragging, setDragging] = useState(false);
+ const fileInputRef = useRef(null);
+ const readyAttachments = pending.filter((p) => p.status === 'ready' && p.meta);
+ const attachmentsReading = pending.some((p) => p.status === 'reading');
+
+ const addFiles = useCallback(async (incoming: File[]) => {
+ let files = incoming;
+ if (files.length === 0) return;
+ const room = MAX_FILES_PER_MESSAGE - pending.filter((p) => p.status !== 'error').length;
+ if (room <= 0) {
+ toast.error(`Attach at most ${MAX_FILES_PER_MESSAGE} files per message.`);
+ return;
+ }
+ if (files.length > room) {
+ toast.error(`Only the first ${room} file(s) were added (${MAX_FILES_PER_MESSAGE} per message).`);
+ files = files.slice(0, room);
+ }
+ for (const f of files.filter((f) => f.size > MAX_FILE_BYTES)) {
+ toast.error(`${f.name} is larger than 25 MB.`);
+ }
+ files = files.filter((f) => f.size <= MAX_FILE_BYTES);
+ if (files.length === 0) return;
+
+ const keys = files.map(() => generateId());
+ setPending((prev) => [
+ ...prev,
+ ...files.map((f, i) => ({ key: keys[i], name: f.name, status: 'reading' as const })),
+ ]);
+ try {
+ const results = await readAttachments(files);
+ await Promise.all(results.map((res) => savePayload(res.meta.id, res.payload)));
+ setPending((prev) =>
+ prev.map((p) => {
+ const i = keys.indexOf(p.key);
+ return i === -1 ? p : { ...p, status: 'ready', meta: results[i]?.meta };
+ }),
+ );
+ } catch (err: any) {
+ const message = err?.message || 'Could not read the file.';
+ toast.error(message);
+ setPending((prev) =>
+ prev.map((p) => (keys.includes(p.key) ? { ...p, status: 'error', error: message } : p)),
+ );
+ }
+ }, [pending]);
+
+ const removePending = useCallback((key: string) => {
+ setPending((prev) => {
+ const item = prev.find((p) => p.key === key);
+ if (item?.meta) void deletePayloads([item.meta.id]);
+ return prev.filter((p) => p.key !== key);
+ });
+ }, []);
+
+ // Web search and Deep Research are separate modes; turning one on turns
+ // the other off.
+ const toggleWebSearch = () => {
+ setWebSearch(!webSearch);
+ if (!webSearch && deepResearch) setDeepResearch(false);
+ };
+ const toggleDeepResearch = () => {
+ setDeepResearch(!deepResearch);
+ if (!deepResearch && webSearch) setWebSearch(false);
+ };
const isCurrentChatStreaming = streamState.isStreaming && streamState.conversationId === activeId;
const {
@@ -173,13 +261,24 @@ export function InputArea() {
const sendMessage = useCallback(async () => {
const content = input.trim();
- if (!content || streamState.isStreaming) return;
+ const attachments = readyAttachments.map((p) => p.meta!);
+ if ((!content && attachments.length === 0) || streamState.isStreaming) return;
+ if (attachmentsReading) {
+ toast.error('Wait for the attached files to finish reading.');
+ return;
+ }
if (!selectedModel) {
toast.error('Pick a model first (⌘K)');
return;
}
+ if (deepResearch && attachments.length > 0) {
+ toast.error("Deep Research can't use attached files. Turn it off to ask about them.");
+ return;
+ }
+ const searchWeb = webSearch && !deepResearch;
setInput('');
+ setPending([]);
let convId = activeId;
if (!convId) {
@@ -191,15 +290,20 @@ export function InputArea() {
role: 'user',
content,
timestamp: Date.now(),
+ ...(attachments.length > 0 ? { attachments } : {}),
};
addMessage(convId, userMsg);
- // Build API messages before adding assistant placeholder
+ // Build API messages before adding assistant placeholder. Attachment
+ // content is read back from IndexedDB for every message that has some.
const currentMessages = useAppStore.getState().messages;
- const apiMessages = currentMessages.map((m) => ({
- role: m.role,
- content: m.content,
- }));
+ const apiMessages = await Promise.all(
+ currentMessages.map(async (m) => ({
+ role: m.role,
+ content: m.content,
+ ...(m.role === 'user' ? await apiAttachmentFields(m.attachments) : {}),
+ })),
+ );
const assistantMsg: ChatMessage = {
id: generateId(),
@@ -235,7 +339,7 @@ export function InputArea() {
setStreamState({
conversationId: convId,
isStreaming: true,
- phase: deepResearch ? 'Researching...' : 'Generating...',
+ phase: deepResearch ? 'Researching...' : searchWeb ? 'Searching the web...' : 'Generating...',
elapsedMs: 0,
activeToolCalls: [],
content: '',
@@ -376,12 +480,44 @@ export function InputArea() {
}
} else {
for await (const sseEvent of streamChat(
- { model: selectedModel, messages: apiMessages, stream: true, temperature, max_tokens: maxTokens },
+ {
+ model: selectedModel,
+ messages: apiMessages,
+ stream: true,
+ temperature,
+ max_tokens: maxTokens,
+ ...(searchWeb ? { web_search: true } : {}),
+ },
controller.signal,
)) {
const eventName = sseEvent.event;
- if (eventName === 'agent_turn_start') {
+ if (eventName === 'web_search') {
+ try {
+ const data = JSON.parse(sseEvent.data);
+ const sources: ResearchSource[] = (data.sources ?? []).map((src: any) => ({
+ ref: src.ref,
+ title: src.title,
+ url: src.url,
+ }));
+ setLastAssistantWebSearch(
+ convId,
+ { query: data.query, engine: data.engine || undefined, error: data.error || undefined },
+ sources,
+ );
+ setStreamState({
+ phase: data.error ? 'Web search failed, answering without it...' : 'Generating...',
+ });
+ useAppStore.getState().addLogEntry({
+ timestamp: Date.now(),
+ level: data.error ? 'warn' : 'info',
+ category: 'chat',
+ message: data.error
+ ? `Web search failed: ${data.error}`
+ : `Web search found ${sources.length} source(s)`,
+ });
+ } catch {}
+ } else if (eventName === 'agent_turn_start') {
setStreamState({ phase: 'Agent thinking...' });
} else if (eventName === 'inference_start') {
setStreamState({ phase: 'Generating...' });
@@ -552,6 +688,10 @@ export function InputArea() {
deepResearch,
temperature,
maxTokens,
+ readyAttachments,
+ attachmentsReading,
+ webSearch,
+ setLastAssistantWebSearch,
]);
const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -567,7 +707,27 @@ export function InputArea() {
setDeepResearch(!deepResearch)}
+ onClick={toggleWebSearch}
+ disabled={streamState.isStreaming}
+ aria-pressed={webSearch}
+ className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full text-xs transition-colors cursor-pointer disabled:cursor-default disabled:opacity-50"
+ style={{
+ background: webSearch ? 'var(--color-accent-subtle)' : 'transparent',
+ border: `1px solid ${webSearch ? 'var(--color-accent)' : 'var(--color-border)'}`,
+ color: webSearch ? 'var(--color-accent)' : 'var(--color-text-tertiary)',
+ }}
+ title={
+ webSearch
+ ? 'Web search: on. Your message is sent to a search engine before Locus answers.'
+ : 'Web search: off. Turn on to look things up online.'
+ }
+ >
+
+ Web search
+
+
{
+ if (!e.dataTransfer.types.includes('Files')) return;
+ e.preventDefault();
+ setDragging(true);
+ }}
+ onDragLeave={(e) => {
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setDragging(false);
+ }}
+ onDrop={(e) => {
+ if (!e.dataTransfer.files.length) return;
+ e.preventDefault();
+ setDragging(false);
+ void addFiles(Array.from(e.dataTransfer.files));
+ }}
>
+ {pending.length > 0 && (
+
+ {pending.map((p) => (
+
removePending(p.key)}
+ />
+ ))}
+
+ )}
+
)}
+
diff --git a/frontend/src/components/Chat/MessageBubble.tsx b/frontend/src/components/Chat/MessageBubble.tsx
index 320976c..641c2b9 100644
--- a/frontend/src/components/Chat/MessageBubble.tsx
+++ b/frontend/src/components/Chat/MessageBubble.tsx
@@ -9,6 +9,8 @@ import { Copy, Check } from 'lucide-react';
import { AudioPlayer } from './AudioPlayer';
import { ToolCallCard } from './ToolCallCard';
import { ResearchTimeline } from './ResearchTimeline';
+import { AttachmentChip } from './AttachmentChip';
+import { WebSources } from './WebSources';
import { rehypeCitations } from '../../lib/rehype-citations';
import { XRayFooter } from './XRayFooter';
import { SpeakMessageButton } from './SpeakMessageButton';
@@ -119,19 +121,28 @@ export function MessageBubble({ message, isLive = false }: Props) {
if (isUser) {
return (
-
-
- {message.content}
-
+
+ {message.attachments && message.attachments.length > 0 && (
+
+ {message.attachments.map((a) => (
+
+ ))}
+
+ )}
+ {message.content && (
+
+ {message.content}
+
+ )}
);
}
@@ -174,6 +185,11 @@ export function MessageBubble({ message, isLive = false }: Props) {
)}
+ {/* What the web search found */}
+ {message.webSearch && (
+
+ )}
+
{/* Footer: copy + read aloud + x-ray */}
diff --git a/frontend/src/components/Chat/SystemPanel.tsx b/frontend/src/components/Chat/SystemPanel.tsx
index 467ae64..f27bfc6 100644
--- a/frontend/src/components/Chat/SystemPanel.tsx
+++ b/frontend/src/components/Chat/SystemPanel.tsx
@@ -9,10 +9,10 @@ import {
HardDrive,
Hash,
X,
- Trophy,
- ExternalLink,
+ UserRound,
} from 'lucide-react';
import { useAppStore } from '../../lib/store';
+import { displayName } from '../../lib/profile';
import { getBase } from '../../lib/api';
interface EnergyData {
@@ -37,8 +37,8 @@ const CLOUD_PRICING = [
export function SystemPanel() {
const savings = useAppStore((s) => s.savings);
const toggleSystemPanel = useAppStore((s) => s.toggleSystemPanel);
- const optInEnabled = useAppStore((s) => s.optInEnabled);
- const setOptInModalOpen = useAppStore((s) => s.setOptInModalOpen);
+ const callUser = displayName(useAppStore((s) => s.profile));
+ const setProfileModalOpen = useAppStore((s) => s.setProfileModalOpen);
const liveEnergy = useAppStore((s) => s.liveEnergy);
const [energy, setEnergy] = useState
(null);
const [telemetry, setTelemetry] = useState(null);
@@ -210,64 +210,31 @@ export function SystemPanel() {
- {/* Leaderboard / Share */}
+ {/* The user's name */}
diff --git a/frontend/src/components/Chat/WebSources.tsx b/frontend/src/components/Chat/WebSources.tsx
new file mode 100644
index 0000000..56a8304
--- /dev/null
+++ b/frontend/src/components/Chat/WebSources.tsx
@@ -0,0 +1,54 @@
+import { Globe } from 'lucide-react';
+import type { ResearchSource, WebSearchInfo } from '../../types';
+
+interface Props {
+ webSearch: WebSearchInfo;
+ sources: ResearchSource[];
+}
+
+function hostOf(url?: string): string {
+ if (!url) return '';
+ try {
+ return new URL(url).hostname.replace(/^www\./, '');
+ } catch {
+ return url;
+ }
+}
+
+/** The pages a web search read for an answer, numbered like its citations. */
+export function WebSources({ webSearch, sources }: Props) {
+ return (
+
+
+
+ {webSearch.error ? (
+ Web search didn't work: {webSearch.error}
+ ) : (
+
+ Searched the web for {webSearch.query}
+
+ )}
+
+ {sources.length > 0 && (
+
+ {sources.map((s) => (
+
+ [{s.ref}]
+
+ {s.title || hostOf(s.url)}
+
+ {hostOf(s.url)}
+
+ ))}
+
+ )}
+
+ );
+}
diff --git a/frontend/src/components/Desktop/SavingsDashboard.tsx b/frontend/src/components/Desktop/SavingsDashboard.tsx
index 9f0a417..94fa4b4 100644
--- a/frontend/src/components/Desktop/SavingsDashboard.tsx
+++ b/frontend/src/components/Desktop/SavingsDashboard.tsx
@@ -423,7 +423,7 @@ export function SavingsDashboard({ apiUrl }: { apiUrl: string }) {
Share Your Savings
- Opt in to privately share your savings for the chance to win a Mac Mini!
+ Opt in to share your savings on the public leaderboard. Your display name and savings are public; your email isn't shown.
({
- joined: false,
- fetchIdentity: vi.fn(),
- savePreference: vi.fn(),
- setOptIn: vi.fn(),
-}));
-vi.mock('../lib/store', () => ({
- useAppStore: (selector: (state: Record
) => unknown) => selector({
- setOptIn: mocks.setOptIn,
- optInDisplayName: '',
- optInEmail: '',
- optInEnabled: mocks.joined,
- }),
-}));
-vi.mock('../lib/analytics', () => ({
- fetchAnalyticsIdentity: mocks.fetchIdentity,
- saveAnalyticsPreference: mocks.savePreference,
-}));
-
-import { OptInModal } from './OptInModal';
-
-beforeEach(() => {
- mocks.joined = false;
- vi.clearAllMocks();
-});
-
-describe('existing sharing modal', () => {
- it('offers explicit analytics actions without a checkbox or side effects on render', () => {
- const html = renderToStaticMarkup( );
- expect(html).not.toContain('type="checkbox"');
- expect(html).toContain('Enable analytics & enter giveaway');
- expect(html).toContain('Enter giveaway only');
- expect(html).toContain('Enable analytics only');
- expect(html).toContain('Continue without sharing');
- expect(html).toContain('Win a Mac mini');
- expect(html).toContain('Your name and savings are public');
- expect(mocks.savePreference).not.toHaveBeenCalled();
- expect(mocks.setOptIn).not.toHaveBeenCalled();
- });
-
- it('allows existing leaderboard members to change analytics independently', () => {
- mocks.joined = true;
- const html = renderToStaticMarkup( );
- expect(html).toContain('Enable analytics');
- expect(html).toContain('Stop leaderboard updates');
- expect(mocks.savePreference).not.toHaveBeenCalled();
- });
-});
diff --git a/frontend/src/components/OptInModal.tsx b/frontend/src/components/OptInModal.tsx
deleted file mode 100644
index 54f6063..0000000
--- a/frontend/src/components/OptInModal.tsx
+++ /dev/null
@@ -1,266 +0,0 @@
-import { useEffect, useRef, useState } from 'react';
-import { Trophy, X } from 'lucide-react';
-import { useAppStore } from '../lib/store';
-import { isProfane } from '../lib/profanity';
-import { fetchAnalyticsIdentity, saveAnalyticsPreference } from '../lib/analytics';
-
-interface OptInModalProps {
- onClose: () => void;
-}
-
-export function OptInModal({ onClose }: OptInModalProps) {
- const setOptIn = useAppStore((s) => s.setOptIn);
- const optInDisplayName = useAppStore((s) => s.optInDisplayName);
- const optInEmail = useAppStore((s) => s.optInEmail);
- const optInEnabled = useAppStore((s) => s.optInEnabled);
- const [name, setName] = useState(optInDisplayName);
- const [email, setEmail] = useState(optInEmail);
- const [joined, setJoined] = useState(optInEnabled);
- const [analyticsEnabled, setAnalyticsEnabled] = useState(false);
- const [analyticsLoading, setAnalyticsLoading] = useState(true);
- const [saving, setSaving] = useState(false);
- const [error, setError] = useState('');
- const [status, setStatus] = useState('');
- const dialogRef = useRef(null);
-
- useEffect(() => {
- let active = true;
- fetchAnalyticsIdentity()
- .then((identity) => { if (active) setAnalyticsEnabled(identity.enabled); })
- .catch(() => {
- if (active) setError('Could not load analytics. You can retry saving your choice.');
- })
- .finally(() => { if (active) setAnalyticsLoading(false); });
- return () => { active = false; };
- }, []);
-
- const handleJoin = async (enableAnalytics: boolean) => {
- if (saving || analyticsLoading) return;
- const trimmed = name.trim();
- const trimmedEmail = email.trim();
- if (trimmed.length < 2 || trimmed.length > 30) {
- setError('Please enter a display name with 2–30 characters.');
- return;
- }
- if (isProfane(trimmed)) {
- setError('Please choose a different name.');
- return;
- }
- if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmedEmail)) {
- setError('Please enter a valid email address.');
- return;
- }
- setError('');
- setSaving(true);
- try {
- await saveAnalyticsPreference(enableAnalytics);
- setAnalyticsEnabled(enableAnalytics);
- setOptIn(true, trimmed, trimmedEmail);
- setJoined(true);
- setStatus(enableAnalytics ? 'Usage analytics enabled.' : 'Usage analytics are off.');
- } catch (cause) {
- setError(cause instanceof Error ? cause.message : 'Could not save your sharing choice.');
- } finally {
- setSaving(false);
- }
- };
-
- const handleAnalytics = async (enabled: boolean, close: boolean) => {
- if (saving || analyticsLoading) return;
- setError('');
- setSaving(true);
- try {
- await saveAnalyticsPreference(enabled);
- setAnalyticsEnabled(enabled);
- setStatus(enabled ? 'Usage analytics enabled.' : 'Usage analytics are off.');
- if (close) onClose();
- } catch (cause) {
- setError(cause instanceof Error ? cause.message : 'Could not save your analytics choice.');
- } finally {
- setSaving(false);
- }
- };
-
- const busy = saving || analyticsLoading;
- const primaryStyle = {
- background: 'var(--color-accent)',
- color: 'var(--color-on-accent)',
- };
- const inputStyle = {
- background: 'var(--color-bg-secondary)',
- border: '1px solid var(--color-border)',
- color: 'var(--color-text)',
- };
- const buttonClass = 'min-h-10 rounded-xl px-3 py-2 text-sm font-medium cursor-pointer disabled:opacity-50';
-
- return (
- { if (event.target === event.currentTarget && !saving) onClose(); }}
- >
-
{
- if (event.key === 'Escape' && !saving) onClose();
- if (event.key !== 'Tab') return;
- const controls = dialogRef.current?.querySelectorAll
(
- 'button:not([disabled]), input:not([disabled]), a[href]',
- );
- if (!controls?.length) return;
- const first = controls[0];
- const last = controls[controls.length - 1];
- if (event.shiftKey && document.activeElement === first) {
- event.preventDefault();
- last.focus();
- } else if (!event.shiftKey && document.activeElement === last) {
- event.preventDefault();
- first.focus();
- }
- }}
- >
-
-
-
-
- Share your savings on the leaderboard for a chance to win a Mac mini.
-
-
- {error && {error}
}
- {status && {status}
}
-
- {!joined && (
-
- )}
-
-
-
- Optional analytics sends usage counts, timings, errors, environment metadata,
- and a random ID to PostHog.
-
-
- Leaderboard entries send your name, email, and savings to Supabase.
- Your name and savings are public; email is not displayed.
-
-
Privacy details
-
-
- {joined ? (
-
-
- Leaderboard sharing enabled · Analytics {analyticsEnabled ? 'on' : 'off'}
-
-
void handleAnalytics(!analyticsEnabled, false)}
- disabled={busy}
- className={buttonClass + ' w-full'}
- style={primaryStyle}
- >{saving ? 'Saving…' : analyticsEnabled ? 'Disable analytics' : 'Enable analytics'}
-
- Done
- { setOptIn(false, '', ''); setJoined(false); onClose(); }}
- disabled={saving}
- className={buttonClass}
- style={{ color: 'var(--color-text-secondary)' }}
- >Stop leaderboard updates
-
-
- ) : (
-
-
void handleJoin(true)}
- disabled={busy}
- className={buttonClass + ' w-full'}
- style={primaryStyle}
- >{saving ? 'Saving…' : 'Enable analytics & enter giveaway'}
-
-
- Enter giveaway only
-
- void handleAnalytics(true, true)} disabled={busy} className={buttonClass} style={{ color: 'var(--color-text)' }}>
- Enable analytics only
-
-
-
void handleAnalytics(false, true)}
- disabled={busy}
- className={buttonClass + ' w-full border'}
- style={{ color: 'var(--color-text)', borderColor: 'var(--color-border)' }}
- >Continue without sharing
-
- )}
-
-
- );
-}
diff --git a/frontend/src/components/ProfileModal.test.tsx b/frontend/src/components/ProfileModal.test.tsx
new file mode 100644
index 0000000..bb5ad59
--- /dev/null
+++ b/frontend/src/components/ProfileModal.test.tsx
@@ -0,0 +1,31 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../lib/store', () => ({
+ useAppStore: (selector: (state: Record) => unknown) =>
+ selector({ setProfile: vi.fn() }),
+}));
+vi.mock('../lib/profile', async (importOriginal) => ({
+ ...(await importOriginal()),
+ fetchProfile: vi.fn(() => new Promise(() => {})),
+}));
+
+import { ProfileModal } from './ProfileModal';
+
+describe('ProfileModal', () => {
+ const html = renderToStaticMarkup( {}} />);
+
+ it('asks for first name, last name and nickname', () => {
+ expect(html).toContain('What should Locus call you?');
+ expect(html).toContain('First name');
+ expect(html).toContain('Last name');
+ expect(html).toContain('Nickname');
+ expect(html).toMatch(/autocomplete="nickname"/i);
+ });
+
+ it('has no giveaway or sharing prompts', () => {
+ expect(html).not.toMatch(/mac mini|giveaway|leaderboard|analytics/i);
+ expect(html).toContain('Not now');
+ expect(html).toContain('Save');
+ });
+});
diff --git a/frontend/src/components/ProfileModal.tsx b/frontend/src/components/ProfileModal.tsx
new file mode 100644
index 0000000..dc065bf
--- /dev/null
+++ b/frontend/src/components/ProfileModal.tsx
@@ -0,0 +1,181 @@
+import { useEffect, useRef, useState } from 'react';
+import { X } from 'lucide-react';
+import { useAppStore } from '../lib/store';
+import {
+ EMPTY_PROFILE,
+ MAX_NAME_LENGTH,
+ fetchProfile,
+ saveProfile,
+ type UserProfile,
+} from '../lib/profile';
+
+interface ProfileModalProps {
+ onClose: () => void;
+}
+
+const FIELDS: Array<{ key: keyof UserProfile; label: string; placeholder: string; autoComplete: string }> = [
+ { key: 'first_name', label: 'First name', placeholder: '', autoComplete: 'given-name' },
+ { key: 'last_name', label: 'Last name', placeholder: '', autoComplete: 'family-name' },
+ { key: 'nickname', label: 'Nickname', placeholder: 'What Locus should call you', autoComplete: 'nickname' },
+];
+
+/** Asks for the user's name so the assistant can address them by nickname. */
+export function ProfileModal({ onClose }: ProfileModalProps) {
+ const setProfile = useAppStore((s) => s.setProfile);
+ const [form, setForm] = useState(EMPTY_PROFILE);
+ const [loading, setLoading] = useState(true);
+ const [saving, setSaving] = useState(false);
+ const [error, setError] = useState('');
+ const dialogRef = useRef(null);
+ const firstFieldRef = useRef(null);
+
+ useEffect(() => {
+ let active = true;
+ fetchProfile()
+ .then((profile) => { if (active) setForm(profile); })
+ .catch(() => { /* start empty; saving reports any real problem */ })
+ .finally(() => {
+ if (!active) return;
+ setLoading(false);
+ firstFieldRef.current?.focus();
+ });
+ return () => { active = false; };
+ }, []);
+
+ const callThem = form.nickname.trim() || form.first_name.trim();
+
+ const handleSave = async () => {
+ if (saving || loading) return;
+ setError('');
+ setSaving(true);
+ try {
+ const saved = await saveProfile({
+ first_name: form.first_name.trim(),
+ last_name: form.last_name.trim(),
+ nickname: form.nickname.trim(),
+ });
+ setProfile(saved);
+ onClose();
+ } catch (cause) {
+ setError(cause instanceof Error ? cause.message : 'Could not save your name.');
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const busy = saving || loading;
+ const inputStyle = {
+ background: 'var(--color-bg-secondary)',
+ border: '1px solid var(--color-border)',
+ color: 'var(--color-text)',
+ };
+
+ return (
+ { if (event.target === event.currentTarget && !saving) onClose(); }}
+ >
+
{
+ if (event.key === 'Escape' && !saving) onClose();
+ if (event.key !== 'Tab') return;
+ const controls = dialogRef.current?.querySelectorAll
(
+ 'button:not([disabled]), input:not([disabled])',
+ );
+ if (!controls?.length) return;
+ const first = controls[0];
+ const last = controls[controls.length - 1];
+ if (event.shiftKey && document.activeElement === first) {
+ event.preventDefault();
+ last.focus();
+ } else if (!event.shiftKey && document.activeElement === last) {
+ event.preventDefault();
+ first.focus();
+ }
+ }}
+ >
+
+
+
+ What should Locus call you?
+
+
+ Locus uses your nickname when it talks to you. Your name stays on this
+ computer.
+
+
+
+
+
+ );
+}
diff --git a/frontend/src/lib/analytics-invitation.test.ts b/frontend/src/lib/analytics-invitation.test.ts
deleted file mode 100644
index 573c31e..0000000
--- a/frontend/src/lib/analytics-invitation.test.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-const mocks = vi.hoisted(() => ({ fetchIdentity: vi.fn() }));
-vi.mock('./analytics', () => ({ fetchAnalyticsIdentity: mocks.fetchIdentity }));
-import { offerAnalyticsChoice } from './analytics-invitation';
-
-const seenKey = 'locus-analytics-choice-seen';
-let stored: Map;
-
-beforeEach(() => {
- vi.resetAllMocks();
- stored = new Map();
- vi.stubGlobal('localStorage', {
- getItem: (key: string) => stored.get(key) ?? null,
- setItem: (key: string, value: string) => stored.set(key, value),
- });
-});
-afterEach(() => vi.unstubAllGlobals());
-
-const invitation = (sharingModalSeen: boolean) => ({
- ready: false,
- sharingModalSeen,
- open: vi.fn(),
- markSharingModalSeen: vi.fn(),
-});
-
-describe('analytics invitation after setup', () => {
- it('does not consume a fresh user invitation while setup is incomplete', () => {
- const request = invitation(false);
- offerAnalyticsChoice(request);
- expect(request.open).not.toHaveBeenCalled();
- expect(request.markSharingModalSeen).not.toHaveBeenCalled();
- expect(stored.has(seenKey)).toBe(false);
- expect(mocks.fetchIdentity).not.toHaveBeenCalled();
-
- offerAnalyticsChoice({ ...request, ready: true });
- expect(request.open).toHaveBeenCalledOnce();
- expect(request.markSharingModalSeen).toHaveBeenCalledOnce();
- expect(stored.get(seenKey)).toBe('true');
- });
-
- it('waits for the desktop backend before checking an existing user choice', async () => {
- const request = invitation(true);
- offerAnalyticsChoice(request);
- expect(mocks.fetchIdentity).not.toHaveBeenCalled();
- expect(stored.has(seenKey)).toBe(false);
-
- mocks.fetchIdentity.mockResolvedValue({ choice_recorded: false });
- offerAnalyticsChoice({ ...request, ready: true });
- await vi.waitFor(() => expect(request.open).toHaveBeenCalledOnce());
- expect(stored.get(seenKey)).toBe('true');
- });
-
- it('does not reopen for an existing user who already recorded a choice', async () => {
- const request = invitation(true);
- mocks.fetchIdentity.mockResolvedValue({ choice_recorded: true });
- offerAnalyticsChoice({ ...request, ready: true });
- await vi.waitFor(() => expect(stored.get(seenKey)).toBe('true'));
- expect(request.open).not.toHaveBeenCalled();
- });
-
- it('does not consume the invitation when its effect is cancelled', async () => {
- const request = invitation(true);
- let finish: (identity: { choice_recorded: boolean }) => void = () => {};
- mocks.fetchIdentity.mockReturnValue(new Promise((resolve) => { finish = resolve; }));
- const cancel = offerAnalyticsChoice({ ...request, ready: true });
- cancel?.();
- finish({ choice_recorded: false });
- await Promise.resolve();
- expect(request.open).not.toHaveBeenCalled();
- expect(stored.has(seenKey)).toBe(false);
- });
-
- it('keeps a failed lookup eligible for the next ready launch', async () => {
- const request = invitation(true);
- mocks.fetchIdentity.mockRejectedValueOnce(new Error('Server unavailable'));
- offerAnalyticsChoice({ ...request, ready: true });
- await Promise.resolve();
- await Promise.resolve();
- expect(stored.has(seenKey)).toBe(false);
-
- mocks.fetchIdentity.mockResolvedValue({ choice_recorded: false });
- offerAnalyticsChoice({ ...request, ready: true });
- await vi.waitFor(() => expect(request.open).toHaveBeenCalledOnce());
- expect(stored.get(seenKey)).toBe('true');
- });
-});
diff --git a/frontend/src/lib/analytics-invitation.ts b/frontend/src/lib/analytics-invitation.ts
deleted file mode 100644
index f485959..0000000
--- a/frontend/src/lib/analytics-invitation.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { fetchAnalyticsIdentity } from './analytics';
-
-const ANALYTICS_SEEN_KEY = 'locus-analytics-choice-seen';
-
-interface AnalyticsInvitation {
- ready: boolean;
- sharingModalSeen: boolean;
- open: () => void;
- markSharingModalSeen: () => void;
-}
-
-/** Offer the sharing dialog only after the app can actually display it. */
-export function offerAnalyticsChoice({
- ready, sharingModalSeen, open, markSharingModalSeen,
-}: AnalyticsInvitation): (() => void) | undefined {
- if (!ready) return;
- if (!sharingModalSeen) {
- open();
- markSharingModalSeen();
- localStorage.setItem(ANALYTICS_SEEN_KEY, 'true');
- return;
- }
- if (localStorage.getItem(ANALYTICS_SEEN_KEY)) return;
-
- // Existing users may have seen the older leaderboard-only dialog.
- let active = true;
- fetchAnalyticsIdentity().then((identity) => {
- if (!active) return;
- if (!identity.choice_recorded) open();
- localStorage.setItem(ANALYTICS_SEEN_KEY, 'true');
- }).catch(() => { /* Retry next launch if the server was unavailable. */ });
- return () => { active = false; };
-}
diff --git a/frontend/src/lib/attachments.test.ts b/frontend/src/lib/attachments.test.ts
new file mode 100644
index 0000000..f89223b
--- /dev/null
+++ b/frontend/src/lib/attachments.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { apiAttachmentFields, formatBytes, savePayload } from './attachments';
+import type { AttachmentMeta } from '../types';
+
+const meta = (over: Partial): AttachmentMeta => ({
+ id: crypto.randomUUID(),
+ name: 'file',
+ kind: 'document',
+ format: 'text',
+ size: 10,
+ ...over,
+});
+
+describe('apiAttachmentFields', () => {
+ it('is empty without attachments', async () => {
+ expect(await apiAttachmentFields(undefined)).toEqual({});
+ expect(await apiAttachmentFields([])).toEqual({});
+ });
+
+ it('sends images and documents from saved content', async () => {
+ const image = meta({ name: 'photo.png', kind: 'image', format: 'PNG image' });
+ const doc = meta({ name: 'notes.md', format: 'MD file', truncated: true });
+ await savePayload(image.id, { image: 'aGVsbG8=' });
+ await savePayload(doc.id, { text: '# Notes' });
+
+ expect(await apiAttachmentFields([image, doc])).toEqual({
+ images: ['aGVsbG8='],
+ attachments: [{ name: 'notes.md', format: 'MD file', text: '# Notes', truncated: true, note: undefined }],
+ });
+ });
+
+ it('describes files it can no longer find or read', async () => {
+ const gone = meta({ name: 'old.pdf', format: 'PDF' });
+ const binary = meta({ name: 'a.bin', kind: 'unsupported', format: 'BIN file', note: 'Binary file.' });
+ const result = await apiAttachmentFields([gone, binary]);
+ expect(result.images).toBeUndefined();
+ expect(result.attachments).toEqual([
+ { name: 'old.pdf', format: 'PDF', text: '', note: 'This file is no longer available on this device.' },
+ { name: 'a.bin', format: 'BIN file', text: '', note: 'Binary file.' },
+ ]);
+ });
+});
+
+describe('formatBytes', () => {
+ it('uses B, KB and MB', () => {
+ expect(formatBytes(512)).toBe('512 B');
+ expect(formatBytes(2048)).toBe('2 KB');
+ expect(formatBytes(3.5 * 1024 * 1024)).toBe('3.5 MB');
+ });
+});
diff --git a/frontend/src/lib/attachments.ts b/frontend/src/lib/attachments.ts
new file mode 100644
index 0000000..aea194b
--- /dev/null
+++ b/frontend/src/lib/attachments.ts
@@ -0,0 +1,191 @@
+/**
+ * Files attached to chat messages.
+ *
+ * The server reads each file (`POST /v1/attachments`) and returns extracted
+ * text for documents or a resized JPEG for images. Conversations live in
+ * localStorage, which holds only a few MB, so the message keeps just the
+ * metadata and a small thumbnail; the full content goes to IndexedDB, keyed
+ * by attachment id, and is read back when the conversation is sent again.
+ */
+import { authHeaders, getBase } from './api';
+import type { AttachmentMeta } from '../types';
+
+/** What `/v1/attachments` returns for one file. */
+interface ServerAttachment {
+ name: string;
+ kind: 'document' | 'image' | 'unsupported';
+ format: string;
+ size: number;
+ text?: string | null;
+ truncated?: boolean;
+ image?: string | null;
+ width?: number | null;
+ height?: number | null;
+ note?: string | null;
+}
+
+/** The content sent to the model, kept out of localStorage. */
+export interface AttachmentPayload {
+ text?: string;
+ image?: string;
+}
+
+export const MAX_FILES_PER_MESSAGE = 10;
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+
+/** Upload files for reading. Throws with the server's message on failure. */
+export async function readAttachments(
+ files: File[],
+): Promise> {
+ const form = new FormData();
+ for (const file of files) form.append('files', file, file.name);
+ const resp = await fetch(`${getBase()}/v1/attachments`, {
+ method: 'POST',
+ headers: authHeaders(),
+ body: form,
+ });
+ if (!resp.ok) {
+ let detail = `Upload failed (${resp.status})`;
+ try {
+ const body = await resp.json();
+ if (typeof body?.detail === 'string') detail = body.detail;
+ } catch {
+ /* keep the status message */
+ }
+ throw new Error(detail);
+ }
+ const body: { attachments: ServerAttachment[] } = await resp.json();
+ return Promise.all(
+ body.attachments.map(async (a) => {
+ const meta: AttachmentMeta = {
+ id: crypto.randomUUID(),
+ name: a.name,
+ kind: a.kind,
+ format: a.format,
+ size: a.size,
+ chars: a.text?.length,
+ truncated: a.truncated || undefined,
+ note: a.note || undefined,
+ thumbnail: a.image ? await makeThumbnail(a.image) : undefined,
+ };
+ return { meta, payload: { text: a.text ?? undefined, image: a.image ?? undefined } };
+ }),
+ );
+}
+
+/** A small JPEG data URL for showing an image in the conversation. */
+async function makeThumbnail(base64Jpeg: string, maxSide = 160): Promise {
+ try {
+ const img = new Image();
+ img.src = `data:image/jpeg;base64,${base64Jpeg}`;
+ await img.decode();
+ const scale = Math.min(1, maxSide / Math.max(img.width, img.height));
+ const canvas = document.createElement('canvas');
+ canvas.width = Math.max(1, Math.round(img.width * scale));
+ canvas.height = Math.max(1, Math.round(img.height * scale));
+ canvas.getContext('2d')?.drawImage(img, 0, 0, canvas.width, canvas.height);
+ return canvas.toDataURL('image/jpeg', 0.7);
+ } catch {
+ return undefined;
+ }
+}
+
+// ── IndexedDB storage for attachment content ───────────────────────────
+
+const DB_NAME = 'locus-attachments';
+const STORE = 'payloads';
+/** Content of attachments added this session, so sends don't wait on IndexedDB. */
+const memory = new Map();
+let dbPromise: Promise | null = null;
+
+function openDb(): Promise {
+ if (!dbPromise) {
+ dbPromise = new Promise((resolve, reject) => {
+ const req = indexedDB.open(DB_NAME, 1);
+ req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+ req.onsuccess = () => resolve(req.result);
+ req.onerror = () => reject(req.error);
+ });
+ }
+ return dbPromise;
+}
+
+export async function savePayload(id: string, payload: AttachmentPayload): Promise {
+ memory.set(id, payload);
+ try {
+ const db = await openDb();
+ await new Promise((resolve, reject) => {
+ const tx = db.transaction(STORE, 'readwrite');
+ tx.objectStore(STORE).put(payload, id);
+ tx.oncomplete = () => resolve();
+ tx.onerror = () => reject(tx.error);
+ });
+ } catch {
+ // Without IndexedDB the attachment still works for this session.
+ }
+}
+
+export async function loadPayload(id: string): Promise {
+ const cached = memory.get(id);
+ if (cached) return cached;
+ try {
+ const db = await openDb();
+ const payload = await new Promise((resolve, reject) => {
+ const req = db.transaction(STORE, 'readonly').objectStore(STORE).get(id);
+ req.onsuccess = () => resolve(req.result as AttachmentPayload | undefined);
+ req.onerror = () => reject(req.error);
+ });
+ if (payload) memory.set(id, payload);
+ return payload;
+ } catch {
+ return undefined;
+ }
+}
+
+export async function deletePayloads(ids: string[]): Promise {
+ for (const id of ids) memory.delete(id);
+ if (ids.length === 0) return;
+ try {
+ const db = await openDb();
+ const tx = db.transaction(STORE, 'readwrite');
+ for (const id of ids) tx.objectStore(STORE).delete(id);
+ } catch {
+ /* nothing to clean up */
+ }
+}
+
+/** The chat API fields for one message's attachments. */
+export async function apiAttachmentFields(attachments: AttachmentMeta[] | undefined): Promise<{
+ images?: string[];
+ attachments?: Array<{ name: string; format: string; text: string; truncated?: boolean; note?: string }>;
+}> {
+ if (!attachments?.length) return {};
+ const images: string[] = [];
+ const documents: Array<{ name: string; format: string; text: string; truncated?: boolean; note?: string }> = [];
+ for (const meta of attachments) {
+ const payload = await loadPayload(meta.id);
+ if (meta.kind === 'image') {
+ if (payload?.image) images.push(payload.image);
+ else documents.push({ name: meta.name, format: meta.format, text: '', note: 'This image is no longer available on this device.' });
+ } else if (meta.kind === 'document' && payload?.text !== undefined) {
+ documents.push({ name: meta.name, format: meta.format, text: payload.text, truncated: meta.truncated, note: meta.note });
+ } else {
+ documents.push({
+ name: meta.name,
+ format: meta.format,
+ text: '',
+ note: meta.note || 'This file is no longer available on this device.',
+ });
+ }
+ }
+ return {
+ ...(images.length ? { images } : {}),
+ ...(documents.length ? { attachments: documents } : {}),
+ };
+}
+
+export function formatBytes(bytes: number): string {
+ if (bytes < 1024) return `${bytes} B`;
+ if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
diff --git a/frontend/src/lib/profile.test.ts b/frontend/src/lib/profile.test.ts
new file mode 100644
index 0000000..0c64fb6
--- /dev/null
+++ b/frontend/src/lib/profile.test.ts
@@ -0,0 +1,34 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { displayName, offerProfilePrompt } from './profile';
+
+let stored: Map;
+
+beforeEach(() => {
+ stored = new Map();
+ vi.stubGlobal('localStorage', {
+ getItem: (key: string) => stored.get(key) ?? null,
+ setItem: (key: string, value: string) => stored.set(key, value),
+ });
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe('displayName', () => {
+ it('prefers the nickname, then the first name', () => {
+ expect(displayName({ first_name: 'Aryan', last_name: 'Kumar', nickname: 'Ary' })).toBe('Ary');
+ expect(displayName({ first_name: 'Aryan', last_name: 'Kumar', nickname: '' })).toBe('Aryan');
+ expect(displayName({ first_name: '', last_name: 'Kumar', nickname: '' })).toBe('');
+ expect(displayName(null)).toBe('');
+ });
+});
+
+describe('offerProfilePrompt', () => {
+ it('waits for setup, then asks exactly once', () => {
+ const open = vi.fn();
+ offerProfilePrompt({ ready: false, open });
+ expect(open).not.toHaveBeenCalled();
+
+ offerProfilePrompt({ ready: true, open });
+ offerProfilePrompt({ ready: true, open });
+ expect(open).toHaveBeenCalledOnce();
+ });
+});
diff --git a/frontend/src/lib/profile.ts b/frontend/src/lib/profile.ts
new file mode 100644
index 0000000..106b031
--- /dev/null
+++ b/frontend/src/lib/profile.ts
@@ -0,0 +1,59 @@
+/**
+ * The user's name. The server keeps it in USER.md, which goes into every
+ * system prompt, so the assistant calls the user by their nickname.
+ */
+import { authHeaders, getBase } from './api';
+
+export interface UserProfile {
+ first_name: string;
+ last_name: string;
+ nickname: string;
+}
+
+export const EMPTY_PROFILE: UserProfile = { first_name: '', last_name: '', nickname: '' };
+export const MAX_NAME_LENGTH = 50;
+
+/** The name Locus uses for the user: their nickname, else their first name. */
+export function displayName(profile: UserProfile | null | undefined): string {
+ return profile?.nickname || profile?.first_name || '';
+}
+
+async function detail(resp: Response, fallback: string): Promise {
+ try {
+ const body = await resp.json();
+ if (typeof body?.detail === 'string') return body.detail;
+ } catch {
+ /* use the fallback */
+ }
+ return fallback;
+}
+
+export async function fetchProfile(): Promise {
+ const resp = await fetch(`${getBase()}/v1/profile`, { headers: authHeaders() });
+ if (!resp.ok) throw new Error(await detail(resp, `Could not load your name (${resp.status}).`));
+ return resp.json();
+}
+
+export async function saveProfile(profile: UserProfile): Promise {
+ const resp = await fetch(`${getBase()}/v1/profile`, {
+ method: 'PUT',
+ headers: authHeaders({ 'Content-Type': 'application/json' }),
+ body: JSON.stringify(profile),
+ });
+ if (!resp.ok) throw new Error(await detail(resp, `Could not save your name (${resp.status}).`));
+ return resp.json();
+}
+
+const PROMPT_SEEN_KEY = 'locus-profile-prompt-seen';
+
+interface ProfilePrompt {
+ ready: boolean;
+ open: () => void;
+}
+
+/** Ask for the user's name once, after desktop setup has finished. */
+export function offerProfilePrompt({ ready, open }: ProfilePrompt): void {
+ if (!ready || localStorage.getItem(PROMPT_SEEN_KEY)) return;
+ localStorage.setItem(PROMPT_SEEN_KEY, 'true');
+ open();
+}
diff --git a/frontend/src/lib/sse.ts b/frontend/src/lib/sse.ts
index f4368d5..e56a455 100644
--- a/frontend/src/lib/sse.ts
+++ b/frontend/src/lib/sse.ts
@@ -3,10 +3,19 @@ import { getBase, authHeaders } from './api';
export interface ChatRequest {
model: string;
- messages: Array<{ role: string; content: string }>;
+ messages: Array<{
+ role: string;
+ content: string;
+ /** Base64 JPEGs for vision models (from /v1/attachments). */
+ images?: string[];
+ /** Documents, folded into the prompt by the server. */
+ attachments?: Array<{ name: string; format: string; text: string; truncated?: boolean; note?: string }>;
+ }>;
stream: true;
temperature?: number;
max_tokens?: number;
+ /** Search the web for the latest user message before answering. */
+ web_search?: boolean;
}
export async function* streamChat(
diff --git a/frontend/src/lib/store.ts b/frontend/src/lib/store.ts
index 67c43d2..ce8e7ea 100644
--- a/frontend/src/lib/store.ts
+++ b/frontend/src/lib/store.ts
@@ -13,8 +13,11 @@ import type {
StreamState,
ToolCallInfo,
TokenUsage,
+ WebSearchInfo,
} from '../types';
import type { ManagedAgent } from './api';
+import { deletePayloads } from './attachments';
+import type { UserProfile } from './profile';
import { isEmbedOnlyModel } from './model-capabilities';
import { serializeToolCallArguments } from './tool-call';
@@ -40,7 +43,7 @@ const OPTIN_KEY = 'locus-optin';
const OPTIN_NAME_KEY = 'locus-display-name';
const OPTIN_EMAIL_KEY = 'locus-email';
const OPTIN_ANONID_KEY = 'locus-anon-id';
-const OPTIN_SEEN_KEY = 'locus-optin-seen';
+const WEB_SEARCH_KEY = 'locus-web-search';
interface ConversationStore {
version: 1;
@@ -179,8 +182,9 @@ interface AppState {
optInDisplayName: string;
optInEmail: string;
optInAnonId: string;
- optInModalSeen: boolean;
- optInModalOpen: boolean;
+ // The user's name (see lib/profile.ts) and the dialog that asks for it
+ profile: UserProfile | null;
+ profileModalOpen: boolean;
// Actions: conversations
loadConversations: () => void;
@@ -207,6 +211,15 @@ interface AppState {
deepResearch: boolean;
setDeepResearch: (on: boolean) => void;
+ // Web search toggle (remembered across launches) and what an answer searched
+ webSearch: boolean;
+ setWebSearch: (on: boolean) => void;
+ setLastAssistantWebSearch: (
+ conversationId: string,
+ webSearch: WebSearchInfo,
+ sources: ResearchSource[],
+ ) => void;
+
// Actions: models & server
setModels: (models: ModelInfo[]) => void;
setModelsLoading: (loading: boolean) => void;
@@ -252,8 +265,8 @@ interface AppState {
// Actions: opt-in sharing
setOptIn: (enabled: boolean, displayName: string, email: string) => void;
- setOptInModalOpen: (open: boolean) => void;
- markOptInModalSeen: () => void;
+ setProfile: (profile: UserProfile | null) => void;
+ setProfileModalOpen: (open: boolean) => void;
// Logs
logEntries: LogEntry[];
@@ -296,8 +309,8 @@ export const useAppStore = create((set, get) => {
optInDisplayName: localStorage.getItem(OPTIN_NAME_KEY) || '',
optInEmail: localStorage.getItem(OPTIN_EMAIL_KEY) || '',
optInAnonId: localStorage.getItem(OPTIN_ANONID_KEY) || crypto.randomUUID(),
- optInModalSeen: localStorage.getItem(OPTIN_SEEN_KEY) === 'true',
- optInModalOpen: false,
+ profile: null,
+ profileModalOpen: false,
// ── Conversations ───────────────────────────────────────────────
@@ -386,6 +399,10 @@ export const useAppStore = create((set, get) => {
if (streamState.isStreaming && streamState.conversationId === id) return;
const store = loadConversations();
+ const attachmentIds = (store.conversations[id]?.messages ?? []).flatMap(
+ (m) => m.attachments?.map((a) => a.id) ?? [],
+ );
+ void deletePayloads(attachmentIds);
delete store.conversations[id];
if (store.activeId === id) {
const remaining = Object.keys(store.conversations);
@@ -479,6 +496,25 @@ export const useAppStore = create((set, get) => {
deepResearch: false,
setDeepResearch: (on: boolean) => set({ deepResearch: on }),
+ // ── Web search ────────────────────────────────────────────────
+ webSearch: localStorage.getItem(WEB_SEARCH_KEY) === 'true',
+ setWebSearch: (on: boolean) => {
+ localStorage.setItem(WEB_SEARCH_KEY, String(on));
+ set({ webSearch: on });
+ },
+ setLastAssistantWebSearch: (conversationId, webSearch, sources) => {
+ const store = loadConversations();
+ const conv = store.conversations[conversationId];
+ const lastMsg = conv?.messages[conv.messages.length - 1];
+ if (!conv || !lastMsg || lastMsg.role !== 'assistant') return;
+ lastMsg.webSearch = webSearch;
+ lastMsg.researchSources = sources;
+ saveConversations(store);
+ if (get().activeId === conversationId) {
+ set({ messages: [...conv.messages] });
+ }
+ },
+
// ── Models & server ────────────────────────────────────────────
setModels: (models: ModelInfo[]) =>
@@ -593,11 +629,8 @@ export const useAppStore = create((set, get) => {
localStorage.setItem(OPTIN_ANONID_KEY, anonId);
set({ optInEnabled: enabled, optInDisplayName: displayName, optInEmail: email });
},
- setOptInModalOpen: (open: boolean) => set({ optInModalOpen: open }),
- markOptInModalSeen: () => {
- localStorage.setItem(OPTIN_SEEN_KEY, 'true');
- set({ optInModalSeen: true });
- },
+ setProfile: (profile: UserProfile | null) => set({ profile }),
+ setProfileModalOpen: (open: boolean) => set({ profileModalOpen: open }),
};
});
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index f68be09..1c08064 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -115,15 +115,40 @@ export interface LiveEnergyMetrics {
duration_s: number;
}
+/** A file attached to a user message. Its content lives in IndexedDB
+ * (see lib/attachments.ts); conversations keep only this metadata. */
+export interface AttachmentMeta {
+ id: string;
+ name: string;
+ kind: 'document' | 'image' | 'unsupported';
+ format: string;
+ size: number;
+ /** Characters of extracted text, for documents. */
+ chars?: number;
+ truncated?: boolean;
+ note?: string;
+ /** Small JPEG data URL, for images. */
+ thumbnail?: string;
+}
+
+/** What a web search found for an answer (sources go in researchSources). */
+export interface WebSearchInfo {
+ query: string;
+ engine?: string;
+ error?: string;
+}
+
export interface ChatMessage {
id: string;
role: 'user' | 'assistant';
content: string;
timestamp: number;
+ attachments?: AttachmentMeta[];
toolCalls?: ToolCallInfo[];
researchTraces?: ResearchSearchTrace[];
researchSources?: ResearchSource[];
isResearch?: boolean;
+ webSearch?: WebSearchInfo;
usage?: TokenUsage;
telemetry?: MessageTelemetry;
audio?: { url: string };
diff --git a/pyproject.toml b/pyproject.toml
index 2de73b9..43ae92c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -90,12 +90,18 @@ server = [
"uvicorn>=0.30",
"pydantic>=2.0",
"python-multipart>=0.0.9",
+ # Reading chat attachments: PDF text and images (server/attachments.py).
+ "pdfplumber>=0.10",
+ "pillow>=10",
]
desktop = [
"fastapi>=0.110",
"uvicorn>=0.30",
"pydantic>=2.0",
"python-multipart>=0.0.9",
+ # Reading chat attachments: PDF text and images (server/attachments.py).
+ "pdfplumber>=0.10",
+ "pillow>=10",
"faster-whisper>=1.0",
# faster-whisper 1.2.1 passes metadata_errors to av.open(), which PyAV 19 removed (#1077).
"av>=11,<19",
diff --git a/src/locus/server/app.py b/src/locus/server/app.py
index 7b3ac63..6e445f4 100644
--- a/src/locus/server/app.py
+++ b/src/locus/server/app.py
@@ -20,10 +20,12 @@
router as analytics_router,
)
from locus.server.api_routes import include_all_routes
+from locus.server.attachments import router as attachments_router
from locus.server.comparison import comparison_router
from locus.server.connectors_router import create_connectors_router
from locus.server.dashboard import dashboard_router
from locus.server.digest_routes import create_digest_router
+from locus.server.profile_routes import router as profile_router
from locus.server.research_router import router as research_router
from locus.server.routes import router
from locus.server.upload_router import router as upload_router
@@ -480,6 +482,8 @@ async def _shutdown_memory_service() -> None:
app.include_router(create_connectors_router())
app.include_router(create_digest_router())
app.include_router(upload_router)
+ app.include_router(attachments_router)
+ app.include_router(profile_router)
app.include_router(research_router)
app.include_router(analytics_router)
include_all_routes(app)
diff --git a/src/locus/server/attachments.py b/src/locus/server/attachments.py
new file mode 100644
index 0000000..2bf21f6
--- /dev/null
+++ b/src/locus/server/attachments.py
@@ -0,0 +1,522 @@
+"""Files attached to chat messages.
+
+``POST /v1/attachments`` reads uploaded files and returns their content for
+the client to send with a chat message: extracted text for documents, a
+resized JPEG for images. Nothing is stored on the server. The chat route then
+folds that content into the prompt with :func:`render_attachments`, within a
+size budget so large documents can't push the question out of a local model's
+context window.
+
+Text extraction uses only the standard library plus ``pdfplumber`` (PDF) and
+Pillow (images), so every format below works in the desktop runtime:
+
+* PDF; Office Open XML (``.docx``, ``.pptx``, ``.xlsx``); OpenDocument
+ (``.odt``, ``.ods``, ``.odp``); EPUB; HTML; RTF; Jupyter notebooks
+* Anything that decodes as text: plain text, Markdown, CSV, JSON, XML, YAML,
+ logs, source code, and so on
+* Images Pillow can open (PNG, JPEG, GIF, WebP, BMP, TIFF, ICO, ...)
+
+Other binary files are accepted and described by name, type and size so the
+model can at least tell the user what it received.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import logging
+import re
+import zipfile
+from html.parser import HTMLParser
+from typing import Any, Iterable, List, Optional, Sequence
+from xml.etree import ElementTree
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from pydantic import BaseModel
+
+from locus.server.models import MessageAttachment
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/v1/attachments", tags=["attachments"])
+
+#: Largest file accepted, per file.
+MAX_FILE_BYTES = 25 * 1024 * 1024
+#: Most files accepted in one upload.
+MAX_FILES = 10
+#: Extracted text kept per file. The prompt budget below trims further.
+MAX_TEXT_CHARS = 200_000
+#: Attachment text sent to the model per request, across all messages. About
+#: 10k tokens, which leaves room for the conversation and the answer in the
+#: default 16k-token Ollama context.
+PROMPT_BUDGET_CHARS = 40_000
+#: Images are scaled down so their longest side is at most this many pixels.
+IMAGE_MAX_SIDE = 1568
+
+_ZIP_MAGIC = b"PK\x03\x04"
+
+
+class Attachment(BaseModel):
+ """What the client gets back for one uploaded file."""
+
+ name: str
+ kind: str # "document" | "image" | "unsupported"
+ format: str
+ size: int
+ text: Optional[str] = None
+ truncated: bool = False
+ image: Optional[str] = None # base64 JPEG
+ width: Optional[int] = None
+ height: Optional[int] = None
+ note: Optional[str] = None
+
+
+class AttachmentsResponse(BaseModel):
+ attachments: List[Attachment]
+
+
+# ---------------------------------------------------------------------------
+# Text extraction
+# ---------------------------------------------------------------------------
+
+
+class _HTMLText(HTMLParser):
+ """Collect visible text, one block element per line."""
+
+ _BLOCKS = {
+ "p",
+ "div",
+ "br",
+ "li",
+ "tr",
+ "h1",
+ "h2",
+ "h3",
+ "h4",
+ "h5",
+ "h6",
+ "section",
+ "article",
+ "header",
+ "footer",
+ "pre",
+ "blockquote",
+ "td",
+ "th",
+ }
+ _SKIP = {"script", "style", "noscript", "template", "head"}
+
+ def __init__(self) -> None:
+ super().__init__(convert_charrefs=True)
+ self._parts: List[str] = []
+ self._skip_depth = 0
+
+ def handle_starttag(self, tag: str, attrs: Any) -> None:
+ if tag in self._SKIP:
+ self._skip_depth += 1
+ elif tag in self._BLOCKS:
+ self._parts.append("\n")
+
+ def handle_endtag(self, tag: str) -> None:
+ if tag in self._SKIP and self._skip_depth:
+ self._skip_depth -= 1
+ elif tag in self._BLOCKS:
+ self._parts.append("\n")
+
+ def handle_data(self, data: str) -> None:
+ if not self._skip_depth:
+ self._parts.append(data)
+
+ def text(self) -> str:
+ return _tidy("".join(self._parts))
+
+
+def _tidy(text: str) -> str:
+ """Collapse runs of spaces and blank lines."""
+ text = re.sub(r"[ \t\r\f\v]+", " ", text)
+ text = re.sub(r" *\n *", "\n", text)
+ return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def html_to_text(html: str) -> str:
+ parser = _HTMLText()
+ parser.feed(html)
+ parser.close()
+ return parser.text()
+
+
+def _xml_text(xml: bytes, paragraph_tags: Iterable[str]) -> str:
+ """One line per paragraph element, with all the text inside it."""
+ paragraph_tags = set(paragraph_tags)
+ root = ElementTree.fromstring(xml)
+ lines = [
+ "".join(elem.itertext())
+ for elem in root.iter()
+ if elem.tag.rsplit("}", 1)[-1] in paragraph_tags
+ ]
+ return _tidy("\n".join(lines))
+
+
+def _natural_key(name: str) -> List[Any]:
+ return [int(part) if part.isdigit() else part for part in re.split(r"(\d+)", name)]
+
+
+def _docx_text(zf: zipfile.ZipFile) -> str:
+ parts = [
+ n
+ for n in zf.namelist()
+ if re.fullmatch(r"word/(document|footnotes|endnotes)\.xml", n)
+ ]
+ return "\n\n".join(_xml_text(zf.read(n), {"p"}) for n in sorted(parts))
+
+
+def _pptx_text(zf: zipfile.ZipFile) -> str:
+ slides = sorted(
+ (n for n in zf.namelist() if re.fullmatch(r"ppt/slides/slide\d+\.xml", n)),
+ key=_natural_key,
+ )
+ return "\n\n".join(
+ f"Slide {i}:\n{_xml_text(zf.read(n), {'p'})}" for i, n in enumerate(slides, 1)
+ )
+
+
+def _xlsx_text(zf: zipfile.ZipFile) -> str:
+ """Render each sheet as tab-separated rows."""
+ shared: List[str] = []
+ if "xl/sharedStrings.xml" in zf.namelist():
+ root = ElementTree.fromstring(zf.read("xl/sharedStrings.xml"))
+ for si in root.iter():
+ if si.tag.rsplit("}", 1)[-1] == "si":
+ shared.append(
+ "".join(t.text or "" for t in si.iter() if t.tag.endswith("}t"))
+ )
+ sheets = sorted(
+ (n for n in zf.namelist() if re.fullmatch(r"xl/worksheets/sheet\d+\.xml", n)),
+ key=_natural_key,
+ )
+ out: List[str] = []
+ for i, name in enumerate(sheets, 1):
+ rows: List[str] = []
+ root = ElementTree.fromstring(zf.read(name))
+ for row in root.iter():
+ if row.tag.rsplit("}", 1)[-1] != "row":
+ continue
+ cells: List[str] = []
+ for cell in row:
+ if cell.tag.rsplit("}", 1)[-1] != "c":
+ continue
+ value = next((v.text for v in cell if v.tag.endswith("}v")), None)
+ inline = "".join(
+ t.text or "" for t in cell.iter() if t.tag.endswith("}t")
+ )
+ if cell.get("t") == "s" and value is not None and value.isdigit():
+ idx = int(value)
+ cells.append(shared[idx] if idx < len(shared) else "")
+ else:
+ cells.append(inline or value or "")
+ if any(cells):
+ rows.append("\t".join(cells))
+ out.append(f"Sheet {i}:\n" + "\n".join(rows))
+ return "\n\n".join(out)
+
+
+def _odf_text(zf: zipfile.ZipFile) -> str:
+ return _xml_text(zf.read("content.xml"), {"p", "h"})
+
+
+def _epub_text(zf: zipfile.ZipFile) -> str:
+ pages = sorted(
+ (n for n in zf.namelist() if n.lower().endswith((".xhtml", ".html", ".htm"))),
+ key=_natural_key,
+ )
+ return "\n\n".join(
+ html_to_text(zf.read(n).decode("utf-8", "replace")) for n in pages
+ )
+
+
+def _notebook_text(data: bytes) -> str:
+ nb = json.loads(data.decode("utf-8"))
+ out: List[str] = []
+ for cell in nb.get("cells", []):
+ source = cell.get("source", "")
+ source = "".join(source) if isinstance(source, list) else source
+ out.append(f"[{cell.get('cell_type', 'cell')}]\n{source}")
+ return "\n\n".join(out)
+
+
+def _rtf_text(rtf: str) -> str:
+ """Strip RTF control words; good enough for prose documents."""
+ text = re.sub(
+ r"\\'([0-9a-fA-F]{2})",
+ lambda m: bytes.fromhex(m.group(1)).decode("cp1252"),
+ rtf,
+ )
+ text = re.sub(r"\\par[d]?\b|\\line\b", "\n", text)
+ text = re.sub(r"\{\\\*[^{}]*\}", "", text)
+ text = re.sub(r"\\[a-zA-Z]+-?\d* ?", "", text)
+ return _tidy(text.replace("{", "").replace("}", ""))
+
+
+def _pdf_text(data: bytes) -> str:
+ import pdfplumber
+
+ with pdfplumber.open(io.BytesIO(data)) as pdf:
+ return _tidy("\n\n".join(page.extract_text() or "" for page in pdf.pages))
+
+
+def _decode_text(data: bytes) -> Optional[str]:
+ """Decode ``data`` if it looks like text; ``None`` for binary data."""
+ if not data:
+ return ""
+ for bom, encoding in (
+ (b"\xef\xbb\xbf", "utf-8-sig"),
+ (b"\xff\xfe", "utf-16"),
+ (b"\xfe\xff", "utf-16"),
+ ):
+ if data.startswith(bom):
+ return data.decode(encoding, "replace")
+ sample = data[:8192]
+ if b"\x00" in sample:
+ return None
+ try:
+ return data.decode("utf-8")
+ except UnicodeDecodeError:
+ pass
+ text = data.decode("latin-1")
+ printable = sum(ch.isprintable() or ch in "\n\r\t" for ch in text[:8192])
+ return text if printable / max(len(text[:8192]), 1) > 0.95 else None
+
+
+_ZIP_FORMATS = {
+ ".docx": ("Word document", _docx_text),
+ ".docm": ("Word document", _docx_text),
+ ".pptx": ("PowerPoint presentation", _pptx_text),
+ ".pptm": ("PowerPoint presentation", _pptx_text),
+ ".xlsx": ("Excel spreadsheet", _xlsx_text),
+ ".xlsm": ("Excel spreadsheet", _xlsx_text),
+ ".odt": ("OpenDocument text", _odf_text),
+ ".ods": ("OpenDocument spreadsheet", _odf_text),
+ ".odp": ("OpenDocument presentation", _odf_text),
+ ".epub": ("EPUB book", _epub_text),
+}
+
+_LEGACY_OFFICE = {
+ ".doc": "Word 97-2003",
+ ".xls": "Excel 97-2003",
+ ".ppt": "PowerPoint 97-2003",
+}
+
+
+def _extension(name: str) -> str:
+ return "." + name.rsplit(".", 1)[-1].lower() if "." in name else ""
+
+
+def extract_text(name: str, data: bytes) -> tuple[Optional[str], str, Optional[str]]:
+ """Return ``(text, format_label, note)`` for a non-image file.
+
+ ``text`` is ``None`` when the file's content can't be read; ``note`` then
+ says why, in words the model can relay to the user.
+ """
+ ext = _extension(name)
+ if data.startswith(b"%PDF") or ext == ".pdf":
+ text = _pdf_text(data)
+ note = (
+ None
+ if text
+ else "The PDF has no selectable text (it may be a scanned image)."
+ )
+ return text, "PDF", note
+ if data.startswith(_ZIP_MAGIC) and ext in _ZIP_FORMATS:
+ label, reader = _ZIP_FORMATS[ext]
+ with zipfile.ZipFile(io.BytesIO(data)) as zf:
+ return reader(zf), label, None
+ if ext in _LEGACY_OFFICE:
+ return (
+ None,
+ _LEGACY_OFFICE[ext],
+ f"Locus can't read the old {_LEGACY_OFFICE[ext]} format. "
+ "Save it as a newer file "
+ f"(for example .{ext[1:]}x) and attach it again.",
+ )
+ if ext == ".ipynb":
+ return _notebook_text(data), "Jupyter notebook", None
+
+ text = _decode_text(data)
+ if text is None:
+ label = f"{ext[1:].upper()} file" if ext else "binary file"
+ return (
+ None,
+ label,
+ "This is a binary file, so its content can't be read as text.",
+ )
+ if ext in {".html", ".htm", ".xhtml"} or text.lstrip()[:15].lower().startswith(
+ (" Optional[tuple[str, int, int, str]]:
+ """Return ``(base64_jpeg, width, height, format)``, or ``None`` if not an image."""
+ try:
+ from PIL import Image, ImageOps
+ except ImportError:
+ return None
+ try:
+ with Image.open(io.BytesIO(data)) as img:
+ fmt = img.format or "image"
+ img.seek(0) # first frame of animations
+ img = ImageOps.exif_transpose(img)
+ if img.mode in ("RGBA", "LA", "P"):
+ img = img.convert("RGBA")
+ background = Image.new("RGB", img.size, (255, 255, 255))
+ background.paste(img, mask=img.getchannel("A"))
+ img = background
+ else:
+ img = img.convert("RGB")
+ img.thumbnail((IMAGE_MAX_SIDE, IMAGE_MAX_SIDE))
+ out = io.BytesIO()
+ img.save(out, format="JPEG", quality=85)
+ return (
+ base64.b64encode(out.getvalue()).decode("ascii"),
+ img.width,
+ img.height,
+ fmt,
+ )
+ except Exception:
+ return None
+
+
+def read_attachment(name: str, data: bytes) -> Attachment:
+ """Turn one uploaded file into an :class:`Attachment`."""
+ image = prepare_image(data)
+ if image is not None:
+ b64, width, height, fmt = image
+ return Attachment(
+ name=name,
+ kind="image",
+ format=f"{fmt} image",
+ size=len(data),
+ image=b64,
+ width=width,
+ height=height,
+ )
+ try:
+ text, label, note = extract_text(name, data)
+ except Exception as exc: # a damaged file shouldn't fail the whole upload
+ logger.info("Could not read attachment %s: %s", name, exc)
+ return Attachment(
+ name=name,
+ kind="unsupported",
+ format=_extension(name)[1:].upper() or "file",
+ size=len(data),
+ note=(
+ f"The file couldn't be read ({type(exc).__name__}). It may be damaged."
+ ),
+ )
+ if text is None:
+ return Attachment(
+ name=name, kind="unsupported", format=label, size=len(data), note=note
+ )
+ truncated = len(text) > MAX_TEXT_CHARS
+ return Attachment(
+ name=name,
+ kind="document",
+ format=label,
+ size=len(data),
+ text=text[:MAX_TEXT_CHARS],
+ truncated=truncated,
+ note=note,
+ )
+
+
+@router.post("", response_model=AttachmentsResponse)
+async def read_attachments(files: List[UploadFile] = File(...)) -> AttachmentsResponse:
+ """Read uploaded files for a chat message. Nothing is stored."""
+ if len(files) > MAX_FILES:
+ raise HTTPException(
+ status_code=400, detail=f"Attach at most {MAX_FILES} files at a time."
+ )
+ out: List[Attachment] = []
+ for upload in files:
+ name = upload.filename or "file"
+ data = await upload.read(MAX_FILE_BYTES + 1)
+ if len(data) > MAX_FILE_BYTES:
+ raise HTTPException(
+ status_code=413,
+ detail=f"{name} is larger than {MAX_FILE_BYTES // (1024 * 1024)} MB.",
+ )
+ out.append(read_attachment(name, data))
+ return AttachmentsResponse(attachments=out)
+
+
+# ---------------------------------------------------------------------------
+# Prompt rendering
+# ---------------------------------------------------------------------------
+
+
+def render_attachments(
+ attachments: Sequence[MessageAttachment], budget: int
+) -> tuple[str, int]:
+ """Render documents as a prompt block. Returns ``(block, chars_used)``."""
+ if not attachments:
+ return "", 0
+ parts: List[str] = []
+ used = 0
+ for att in attachments:
+ header = f''
+ if att.note and not att.text:
+ parts.append(f"{header}\n[{att.note}]\n ")
+ continue
+ room = max(budget - used, 0)
+ text = att.text[:room]
+ used += len(text)
+ shortened = att.truncated or len(text) < len(att.text)
+ body = text
+ if shortened:
+ body += (
+ "\n[... the rest of this file was cut to fit the model's context ...]"
+ )
+ if att.note:
+ body = f"[{att.note}]\n{body}"
+ parts.append(f"{header}\n{body}\n")
+ return "The user attached these files:\n\n" + "\n\n".join(parts), used
+
+
+def contents_with_attachments(
+ messages: Sequence[Any], budget: int = PROMPT_BUDGET_CHARS
+) -> List[str]:
+ """Each message's content with its documents folded in ahead of it.
+
+ Newer messages get first claim on ``budget``, so the latest files are sent
+ in full when the conversation already carries older ones. The messages
+ themselves aren't changed.
+ """
+ contents = [getattr(m, "content", "") or "" for m in messages]
+ remaining = budget
+ for i in range(len(messages) - 1, -1, -1):
+ attachments = getattr(messages[i], "attachments", None)
+ if not attachments:
+ continue
+ block, used = render_attachments(attachments, remaining)
+ remaining -= used
+ contents[i] = f"{block}\n\n{contents[i]}" if contents[i] else block
+ return contents
+
+
+__all__ = [
+ "Attachment",
+ "AttachmentsResponse",
+ "MessageAttachment",
+ "contents_with_attachments",
+ "extract_text",
+ "html_to_text",
+ "prepare_image",
+ "read_attachment",
+ "render_attachments",
+ "router",
+]
diff --git a/src/locus/server/cloud_router.py b/src/locus/server/cloud_router.py
index d0a23dd..7a028fd 100644
--- a/src/locus/server/cloud_router.py
+++ b/src/locus/server/cloud_router.py
@@ -112,10 +112,34 @@ def _openrouter_model_id(model: str) -> str:
def _to_openai_msgs(messages: Sequence[Message]) -> list[dict[str, Any]]:
+ """OpenAI chat messages; images become ``image_url`` content parts."""
out = []
for m in messages:
role = m.role.value if hasattr(m.role, "value") else str(m.role)
- out.append({"role": role, "content": m.content or ""})
+ if getattr(m, "images", None):
+ parts: list[dict[str, Any]] = [{"type": "text", "text": m.content or ""}]
+ parts.extend(
+ {
+ "type": "image_url",
+ "image_url": {"url": f"data:image/jpeg;base64,{img}"},
+ }
+ for img in m.images
+ )
+ out.append({"role": role, "content": parts})
+ else:
+ out.append({"role": role, "content": m.content or ""})
+ return out
+
+
+def _to_ollama_msgs(messages: Sequence[Message]) -> list[dict[str, Any]]:
+ """Ollama /api/chat messages; images go in each message's ``images`` list."""
+ out = []
+ for m in messages:
+ role = m.role.value if hasattr(m.role, "value") else str(m.role)
+ msg: dict[str, Any] = {"role": role, "content": m.content or ""}
+ if getattr(m, "images", None):
+ msg["images"] = list(m.images)
+ out.append(msg)
return out
@@ -318,7 +342,7 @@ async def stream_local(
"""Stream tokens directly from Ollama, bypassing the engine system."""
payload = {
"model": model,
- "messages": _to_openai_msgs(messages),
+ "messages": _to_ollama_msgs(messages),
"stream": True,
# Disable extended thinking (Qwen3.5 etc.) — when enabled all tokens
# go into the 'thinking' field and 'content' stays empty.
diff --git a/src/locus/server/models.py b/src/locus/server/models.py
index fb59ef8..b080b2c 100644
--- a/src/locus/server/models.py
+++ b/src/locus/server/models.py
@@ -13,12 +13,26 @@
# ---------------------------------------------------------------------------
+class MessageAttachment(BaseModel):
+ """A document attached to a chat message (see ``server/attachments.py``)."""
+
+ name: str
+ format: str = ""
+ text: str = ""
+ truncated: bool = False
+ note: Optional[str] = None
+
+
class ChatMessage(BaseModel):
role: str
content: str = ""
name: Optional[str] = None
tool_calls: Optional[List[Dict[str, Any]]] = None
tool_call_id: Optional[str] = None
+ # Locus extensions, read from /v1/attachments. Images are base64 JPEGs for
+ # vision models; attachments are documents, folded into the prompt.
+ images: Optional[List[str]] = None
+ attachments: Optional[List[MessageAttachment]] = None
class ChatCompletionRequest(BaseModel):
@@ -28,6 +42,8 @@ class ChatCompletionRequest(BaseModel):
max_tokens: int = 1024
stream: bool = False
tools: Optional[List[Dict[str, Any]]] = None
+ # Locus extension: search the web for the latest user message first.
+ web_search: bool = False
# ---------------------------------------------------------------------------
diff --git a/src/locus/server/profile_routes.py b/src/locus/server/profile_routes.py
new file mode 100644
index 0000000..a906a4e
--- /dev/null
+++ b/src/locus/server/profile_routes.py
@@ -0,0 +1,117 @@
+"""The user's name, so the assistant knows what to call them.
+
+``GET/PUT /v1/profile`` read and write a small block in the persona's
+``USER.md``, which :class:`~locus.prompt.builder.SystemPromptBuilder` adds to
+every system prompt under "User Profile". Anything else the user keeps in that
+file is left alone. The block is plain text, so the CLI and agents see the same
+name, and editing it by hand works too.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/v1/profile", tags=["profile"])
+
+START = ""
+END = ""
+_BLOCK_RE = re.compile(re.escape(START) + r".*?" + re.escape(END) + r"\n?", re.S)
+_FIELDS = (
+ ("first_name", "First name"),
+ ("last_name", "Last name"),
+ ("nickname", "Nickname"),
+)
+MAX_LEN = 50
+
+
+class Profile(BaseModel):
+ first_name: str = Field("", max_length=MAX_LEN)
+ last_name: str = Field("", max_length=MAX_LEN)
+ nickname: str = Field("", max_length=MAX_LEN)
+
+
+def _clean(value: str) -> str:
+ """One line of plain text: no line breaks or comment markers."""
+ value = value.replace("", "")
+ return re.sub(r"\s+", " ", value).strip()
+
+
+def render_block(profile: Profile) -> str:
+ """The USER.md block for ``profile``, or "" when it's empty."""
+ values = {key: _clean(getattr(profile, key)) for key, _ in _FIELDS}
+ if not any(values.values()):
+ return ""
+ lines = [START]
+ lines += [f"{label}: {values[key]}" for key, label in _FIELDS if values[key]]
+ call_them = values["nickname"] or values["first_name"]
+ if call_them:
+ lines.append(
+ f'Address the user as "{call_them}" when you greet them or speak to them '
+ "directly, unless they ask you to use a different name."
+ )
+ lines.append(END)
+ return "\n".join(lines) + "\n"
+
+
+def parse_block(text: str) -> Profile:
+ """The profile stored in USER.md ``text`` (empty if there is none)."""
+ match = _BLOCK_RE.search(text)
+ if not match:
+ return Profile()
+ found = {}
+ for key, label in _FIELDS:
+ line = re.search(rf"^{label}: (.*)$", match.group(0), re.M)
+ if line:
+ found[key] = line.group(1).strip()
+ return Profile(**found)
+
+
+def write_profile(path: Path, profile: Profile) -> None:
+ """Replace (or add, or remove) the profile block in ``path``."""
+ existing = path.read_text(encoding="utf-8") if path.exists() else ""
+ rest = _BLOCK_RE.sub("", existing).lstrip("\n")
+ block = render_block(profile)
+ if not block and not rest:
+ if path.exists():
+ path.unlink()
+ return
+ content = block + ("\n" + rest if block and rest else rest)
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(content, encoding="utf-8")
+
+
+def profile_path(request: Request) -> Path:
+ """The USER.md the system prompt reads, honouring a named persona."""
+ from locus.core.config import load_config
+ from locus.prompt.builder import SystemPromptBuilder
+
+ config = getattr(request.app.state, "config", None) or load_config()
+ resolved = SystemPromptBuilder._resolve_persona(config.memory_files)
+ if not resolved.user_path:
+ # persona_name = "none" turns persona files off entirely.
+ raise HTTPException(
+ status_code=409,
+ detail='Persona files are turned off (persona_name = "none"), '
+ "so Locus can't use your name.",
+ )
+ return Path(resolved.user_path).expanduser()
+
+
+@router.get("", response_model=Profile)
+def get_profile(request: Request) -> Profile:
+ path = profile_path(request)
+ return parse_block(path.read_text(encoding="utf-8")) if path.exists() else Profile()
+
+
+@router.put("", response_model=Profile)
+def put_profile(profile: Profile, request: Request) -> Profile:
+ cleaned = Profile(**{key: _clean(getattr(profile, key)) for key, _ in _FIELDS})
+ write_profile(profile_path(request), cleaned)
+ return cleaned
+
+
+__all__ = ["Profile", "parse_block", "render_block", "router", "write_profile"]
diff --git a/src/locus/server/routes.py b/src/locus/server/routes.py
index e2b4463..a64efc6 100644
--- a/src/locus/server/routes.py
+++ b/src/locus/server/routes.py
@@ -32,17 +32,31 @@
router = APIRouter()
+#: ``name`` of the system message that carries web search results. Like
+#: memory context, it doesn't count as a caller-supplied system prompt, so the
+#: server still adds its identity prompt.
+WEB_CONTEXT_NAME = "locus_web_context"
+
def _to_messages(chat_messages) -> list[Message]:
- """Convert Pydantic ChatMessage objects to core Message objects."""
+ """Convert Pydantic ChatMessage objects to core Message objects.
+
+ Attached documents are folded into each message's content and images are
+ carried over for vision models.
+ """
+ from locus.server.attachments import contents_with_attachments
+
+ chat_messages = list(chat_messages)
+ contents = contents_with_attachments(chat_messages)
messages = []
- for m in chat_messages:
+ for m, content in zip(chat_messages, contents):
role = Role(m.role) if m.role in {r.value for r in Role} else Role.USER
+ is_web_context = role == Role.SYSTEM and m.name == WEB_CONTEXT_NAME
messages.append(
Message(
role=role,
- content=m.content or "",
- name=m.name,
+ content=content,
+ name=None if is_web_context else m.name,
tool_calls=[
ToolCall(
id=tool_call.get("id", ""),
@@ -53,6 +67,8 @@ def _to_messages(chat_messages) -> list[Message]:
]
or None,
tool_call_id=m.tool_call_id,
+ metadata={"web_context": True} if is_web_context else {},
+ images=list(m.images) if getattr(m, "images", None) else None,
)
)
return messages
@@ -86,7 +102,11 @@ def _ensure_identity_prompt(messages: list[Message], app_config) -> list[Message
"""
def _is_caller_system_prompt(m: Message) -> bool:
- return m.role == Role.SYSTEM and not m.metadata.get("memory_context")
+ return (
+ m.role == Role.SYSTEM
+ and not m.metadata.get("memory_context")
+ and not m.metadata.get("web_context")
+ )
system_messages = [message for message in messages if message.role == Role.SYSTEM]
caller_supplied_system = any(
@@ -154,18 +174,132 @@ def _is_caller_system_prompt(m: Message) -> bool:
return [combined_system, *non_system_messages]
+def _with_web_search_event(response, web_result):
+ """Send the web search sources ahead of a streamed answer.
+
+ The ``web_search`` SSE event lets the client show what was searched and
+ link the answer's ``[n]`` citations before any tokens arrive.
+ """
+ if web_result is None or not isinstance(response, StreamingResponse):
+ return response
+ import json as _json
+
+ body = response.body_iterator
+ event = f"event: web_search\ndata: {_json.dumps(web_result.event())}\n\n"
+
+ async def with_event():
+ yield event
+ async for chunk in body:
+ yield chunk
+
+ response.body_iterator = with_event()
+ return response
+
+
+#: Ollama models known to accept images, keyed by model name.
+_vision_cache: dict[str, bool] = {}
+
+
+async def _model_accepts_images(engine, model: str) -> bool:
+ """Ask Ollama whether ``model`` has the ``vision`` capability.
+
+ Non-Ollama engines are assumed to handle images (or ignore them).
+ """
+ if _uses_direct_cloud_router(engine, model):
+ return True
+ if (_engine_key_for_model(engine, model) or "ollama") != "ollama":
+ return True
+ if model in _vision_cache:
+ return _vision_cache[model]
+ import httpx
+
+ from locus.server.cloud_router import _ollama_host
+
+ try:
+ async with httpx.AsyncClient(timeout=5) as client:
+ resp = await client.post(
+ f"{_ollama_host()}/api/show", json={"model": model}
+ )
+ resp.raise_for_status()
+ capabilities = resp.json().get("capabilities") or []
+ except Exception:
+ # Unknown: send the images and let the model or engine decide.
+ return True
+ _vision_cache[model] = "vision" in capabilities
+ return _vision_cache[model]
+
+
+async def _drop_images_without_vision(request_body, engine, model: str) -> None:
+ """Replace images with a note when the model can't see them.
+
+ Sending images to a text-only Ollama model fails the request outright, so
+ the model is told instead and can suggest switching to a vision model.
+ """
+ with_images = [m for m in request_body.messages if m.images]
+ if not with_images or await _model_accepts_images(engine, model):
+ return
+ from locus.server.models import MessageAttachment
+
+ for m in with_images:
+ note = MessageAttachment(
+ name=f"{len(m.images)} image(s)",
+ format="image",
+ note=(
+ f"The user attached {len(m.images)} image(s), but the current model "
+ f"({model}) can't view images. Tell the user to pick a vision model, "
+ "such as qwen3.5 or gemma3, to ask about images."
+ ),
+ )
+ m.attachments = [*(m.attachments or []), note]
+ m.images = None
+
+
@router.post("/v1/chat/completions")
async def chat_completions(request_body: ChatCompletionRequest, request: Request):
"""Handle chat completion requests (streaming and non-streaming)."""
engine = request.app.state.engine
agent = getattr(request.app.state, "agent", None)
model = request_body.model
+ # Agents take only the latest message's text, which would drop web results,
+ # attached documents and images, so those requests go straight to the engine.
+ has_extras = request_body.web_search or any(
+ m.images or m.attachments for m in request_body.messages
+ )
use_server_agent = (
agent is not None
and not request_body.tools
+ and not has_extras
and (not request_body.stream or bool(getattr(agent, "_tools", None)))
)
+ await _drop_images_without_vision(request_body, engine, model)
+
+ # Search the web for the latest user message (before memory context, which
+ # rewrites messages with attachments folded in).
+ web_result = None
+ if request_body.web_search:
+ from locus.server.models import ChatMessage
+ from locus.server.web_context import render_context, search_web
+
+ web_query = next(
+ (
+ m.content
+ for m in reversed(request_body.messages)
+ if m.role == "user" and m.content
+ ),
+ "",
+ )
+ if web_query:
+ web_result = await search_web(web_query.strip()[:400])
+ request_body.messages.insert(
+ 0,
+ ChatMessage(
+ role="system",
+ name=WEB_CONTEXT_NAME,
+ content=render_context(web_result),
+ ),
+ )
+
# Inject memory context into messages before dispatching
config = getattr(request.app.state, "config", None)
memory_backend = getattr(request.app.state, "memory_backend", None)
@@ -231,6 +365,8 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request
]
or None,
tool_call_id=getattr(msg, "tool_call_id", None),
+ # Attachments are already folded into the content.
+ images=msg.images,
)
)
request_body.messages = new_msgs
@@ -287,7 +423,7 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request
# to the desktop UI and other stream:true clients (#735). Fall back to
# direct token streaming when no tool-bearing agent is configured.
if request_body.tools:
- return await _handle_stream_tools(
+ response = await _handle_stream_tools(
engine,
model,
request_body,
@@ -296,8 +432,8 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request
bus=getattr(request.app.state, "bus", None),
memory_service=getattr(request.app.state, "memory_service", None),
)
- if use_server_agent:
- return await _handle_agent_stream(
+ elif use_server_agent:
+ response = await _handle_agent_stream(
agent,
model,
request_body,
@@ -306,16 +442,18 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request
bus=getattr(request.app.state, "bus", None),
memory_service=getattr(request.app.state, "memory_service", None),
)
- return await _handle_stream(
- engine,
- model,
- request_body,
- complexity_info,
- trace_store=getattr(request.app.state, "trace_store", None),
- app_config=config,
- bus=getattr(request.app.state, "bus", None),
- memory_service=getattr(request.app.state, "memory_service", None),
- )
+ else:
+ response = await _handle_stream(
+ engine,
+ model,
+ request_body,
+ complexity_info,
+ trace_store=getattr(request.app.state, "trace_store", None),
+ app_config=config,
+ bus=getattr(request.app.state, "bus", None),
+ memory_service=getattr(request.app.state, "memory_service", None),
+ )
+ return _with_web_search_event(response, web_result)
# Non-streaming: use agent if available, otherwise direct engine call.
#
diff --git a/src/locus/server/web_context.py b/src/locus/server/web_context.py
new file mode 100644
index 0000000..0e22846
--- /dev/null
+++ b/src/locus/server/web_context.py
@@ -0,0 +1,174 @@
+"""Web search for chat messages.
+
+When a chat request sets ``web_search``, the chat route searches the web for
+the user's latest message before the model answers, reads the top pages, and
+adds the results as context the model cites as ``[1]``, ``[2]``, ... The
+sources are also sent to the client in a ``web_search`` SSE event so the UI
+can link the citations.
+
+Searching sends the query to the configured engine (DuckDuckGo, or Tavily,
+You.com, Serply or Firecrawl with a key; see
+:class:`locus.tools.web_search.WebSearchTool`), so the client only asks for it
+when the user turns web search on. A message that contains a URL fetches that
+page instead of searching.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime as _dt
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+#: Search results requested.
+MAX_RESULTS = 5
+#: Top results whose pages are fetched for more than the search snippet.
+FETCH_TOP = 3
+#: Characters kept from each fetched page.
+PAGE_CHARS = 3000
+SEARCH_TIMEOUT_S = 20.0
+FETCH_TIMEOUT_S = 10.0
+
+_RESULT_RE = re.compile(
+ r"^###\s*(?P.*?)\s*\nSource:\s*(?P\S+)\s*\nSummary:\s*(?P.*)",
+ re.S,
+)
+
+
+@dataclass
+class WebSource:
+ ref: int
+ title: str
+ url: str
+ snippet: str = ""
+ text: str = ""
+
+ def public(self) -> Dict[str, Any]:
+ """The fields sent to the client."""
+ return {"ref": self.ref, "title": self.title, "url": self.url}
+
+
+@dataclass
+class WebSearchResult:
+ query: str
+ engine: str = ""
+ sources: List[WebSource] = field(default_factory=list)
+ error: Optional[str] = None
+
+ def event(self) -> Dict[str, Any]:
+ """Payload of the ``web_search`` SSE event."""
+ payload: Dict[str, Any] = {
+ "query": self.query,
+ "engine": self.engine,
+ "sources": [s.public() for s in self.sources],
+ }
+ if self.error:
+ payload["error"] = self.error
+ return payload
+
+
+def parse_results(content: str) -> List[WebSource]:
+ """Parse :class:`WebSearchTool`'s ``### title / Source / Summary`` blocks."""
+ sources: List[WebSource] = []
+ for block in content.split("\n\n---\n\n"):
+ match = _RESULT_RE.match(block.strip())
+ if not match:
+ continue
+ sources.append(
+ WebSource(
+ ref=len(sources) + 1,
+ title=match["title"] or match["url"],
+ url=match["url"],
+ snippet=match["summary"].strip(),
+ )
+ )
+ return sources
+
+
+async def search_web(query: str) -> WebSearchResult:
+ """Search for ``query`` and read the top pages. Never raises."""
+ from locus.tools.web_search import WebSearchTool
+
+ result = WebSearchResult(query=query)
+ tool = WebSearchTool(max_results=MAX_RESULTS)
+ try:
+ found = await asyncio.wait_for(
+ asyncio.to_thread(tool.execute, query=query), SEARCH_TIMEOUT_S
+ )
+ except asyncio.TimeoutError:
+ result.error = "The web search timed out."
+ return result
+ except Exception as exc: # the tool reports most errors itself
+ result.error = f"The web search failed ({type(exc).__name__})."
+ return result
+
+ metadata = found.metadata or {}
+ result.engine = str(metadata.get("engine") or metadata.get("extractor") or "")
+ if not found.success:
+ result.error = found.content or "The web search failed."
+ return result
+
+ if metadata.get("mode") == "fetch":
+ url = str(metadata.get("url", ""))
+ result.sources = [
+ WebSource(ref=1, title=url, url=url, text=found.content[: PAGE_CHARS * 2])
+ ]
+ return result
+
+ result.sources = parse_results(found.content)
+ if not result.sources:
+ result.error = "The web search found no results."
+ return result
+
+ async def fetch(source: WebSource) -> None:
+ try:
+ text = await asyncio.wait_for(
+ asyncio.to_thread(WebSearchTool._fetch_url, source.url, PAGE_CHARS),
+ FETCH_TIMEOUT_S,
+ )
+ source.text = (text or "").strip()
+ except Exception:
+ logger.debug("Could not fetch %s", source.url, exc_info=True)
+
+ await asyncio.gather(*(fetch(s) for s in result.sources[:FETCH_TOP]))
+ return result
+
+
+def render_context(result: WebSearchResult, today: Optional[_dt.date] = None) -> str:
+ """The system prompt section that gives the model the search results."""
+ today = today or _dt.date.today()
+ if result.error or not result.sources:
+ reason = result.error or "The web search found no results."
+ return (
+ "The user asked you to search the web, but the search didn't work: "
+ f"{reason} Answer from your own knowledge, and say that you couldn't "
+ "check the web, so recent details may be out of date."
+ )
+ lines = [
+ "Web search results for the user's latest message, "
+ f"retrieved {today.isoformat()}.",
+ "Use them to answer. Cite the sources you rely on inline as [1], [2], "
+ "and so on, using the numbers below. If the results don't answer the "
+ "question, say so rather than guessing. Don't invent sources or URLs.",
+ "",
+ ]
+ for source in result.sources:
+ body = source.text or source.snippet
+ lines.append(
+ f"[{source.ref}] {source.title}\nURL: {source.url}\n{body}".rstrip()
+ )
+ lines.append("")
+ return "\n".join(lines).rstrip()
+
+
+__all__ = [
+ "WebSearchResult",
+ "WebSource",
+ "parse_results",
+ "render_context",
+ "search_web",
+]
diff --git a/tests/memory/test_ingest.py b/tests/memory/test_ingest.py
index c3e771f..7256b57 100644
--- a/tests/memory/test_ingest.py
+++ b/tests/memory/test_ingest.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import sys
from pathlib import Path
import pytest
@@ -54,15 +55,13 @@ def test_read_document_utf8_fallback(tmp_path: Path):
assert "caf" in text
-def test_read_document_pdf_missing_dep(tmp_path: Path):
+def test_read_document_pdf_missing_dep(tmp_path: Path, monkeypatch):
p = tmp_path / "doc.pdf"
p.write_bytes(b"%PDF-1.4 fake pdf content")
- # Should raise ImportError when pdfplumber not installed
- # or succeed if it IS installed — either way just check it's handled
- try:
+ # Simulate pdfplumber not being installed; the server extra installs it.
+ monkeypatch.setitem(sys.modules, "pdfplumber", None)
+ with pytest.raises(ImportError, match="pdfplumber"):
read_document(p)
- except ImportError as exc:
- assert "pdfplumber" in str(exc)
def test_read_document_not_found(tmp_path: Path):
diff --git a/tests/server/test_attachments.py b/tests/server/test_attachments.py
new file mode 100644
index 0000000..3566bea
--- /dev/null
+++ b/tests/server/test_attachments.py
@@ -0,0 +1,306 @@
+"""Reading chat attachments and folding them into the prompt."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import zipfile
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+PIL = pytest.importorskip("PIL")
+
+from fastapi.testclient import TestClient # noqa: E402
+from PIL import Image # noqa: E402
+
+from locus.server import attachments # noqa: E402
+from locus.server.attachments import ( # noqa: E402
+ contents_with_attachments,
+ extract_text,
+ read_attachment,
+ render_attachments,
+)
+from locus.server.models import ChatMessage, MessageAttachment # noqa: E402
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+A = "http://schemas.openxmlformats.org/drawingml/2006/main"
+S = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+
+
+def _zip(files: dict[str, str]) -> bytes:
+ out = io.BytesIO()
+ with zipfile.ZipFile(out, "w") as zf:
+ for name, body in files.items():
+ zf.writestr(name, body)
+ return out.getvalue()
+
+
+def _png(width=40, height=30, mode="RGBA") -> bytes:
+ out = io.BytesIO()
+ Image.new(
+ mode, (width, height), (200, 30, 30, 128) if mode == "RGBA" else (200, 30, 30)
+ ).save(out, format="PNG")
+ return out.getvalue()
+
+
+class TestExtractText:
+ def test_docx_paragraphs(self):
+ data = _zip(
+ {
+ "word/document.xml": (
+ f''
+ "Lease renewal "
+ "12 months, "
+ "same rent "
+ " "
+ )
+ }
+ )
+ text, label, note = extract_text("lease.docx", data)
+ assert text == "Lease renewal\n12 months, same rent"
+ assert label == "Word document"
+ assert note is None
+
+ def test_pptx_slides_in_order(self):
+ slide = (
+ ''
+ "{t} "
+ )
+ data = _zip(
+ {
+ "ppt/slides/slide10.xml": slide.format(a=A, t="Last"),
+ "ppt/slides/slide2.xml": slide.format(a=A, t="Second"),
+ "ppt/slides/slide1.xml": slide.format(a=A, t="First"),
+ }
+ )
+ text, label, _ = extract_text("deck.pptx", data)
+ assert label == "PowerPoint presentation"
+ assert text.index("First") < text.index("Second") < text.index("Last")
+ assert "Slide 3:\nLast" in text
+
+ def test_xlsx_shared_and_inline_strings(self):
+ data = _zip(
+ {
+ "xl/sharedStrings.xml": (
+ f'Name Ada '
+ ),
+ "xl/worksheets/sheet1.xml": (
+ f''
+ '0 '
+ 'Score
'
+ '1 97
'
+ " "
+ ),
+ }
+ )
+ text, label, _ = extract_text("scores.xlsx", data)
+ assert label == "Excel spreadsheet"
+ assert text == "Sheet 1:\nName\tScore\nAda\t97"
+
+ def test_odt_keeps_text_after_spans(self):
+ data = _zip(
+ {
+ "content.xml": (
+ ''
+ "Paint the kitchen green "
+ " "
+ )
+ }
+ )
+ text, label, _ = extract_text("notes.odt", data)
+ assert label == "OpenDocument text"
+ assert text == "Paint the kitchen green"
+
+ def test_epub_pages(self):
+ data = _zip(
+ {
+ "OEBPS/ch1.xhtml": (
+ "Chapter 1 It begins.
"
+ ),
+ "OEBPS/ch2.xhtml": "It ends.
",
+ }
+ )
+ text, label, _ = extract_text("book.epub", data)
+ assert label == "EPUB book"
+ assert text.index("It begins.") < text.index("It ends.")
+
+ def test_html_drops_scripts_and_styles(self):
+ html = (
+ b""
+ b"Hello
World
"
+ )
+ text, label, _ = extract_text("page.html", html)
+ assert label == "web page"
+ assert text == "Hello\n\nWorld"
+
+ def test_rtf(self):
+ text, label, _ = extract_text(
+ "memo.rtf", rb"{\rtf1\ansi{\fonttbl\f0 Arial;}\f0 Hello\par Caf\'e9}"
+ )
+ assert label == "RTF document"
+ assert "Hello" in text and "Café" in text
+
+ def test_notebook_cells(self):
+ nb = {
+ "cells": [
+ {"cell_type": "markdown", "source": ["# Title"]},
+ {"cell_type": "code", "source": "print(1)"},
+ ]
+ }
+ text, label, _ = extract_text("a.ipynb", json.dumps(nb).encode())
+ assert label == "Jupyter notebook"
+ assert "[markdown]\n# Title" in text and "[code]\nprint(1)" in text
+
+ @pytest.mark.parametrize(
+ ("name", "data", "expected"),
+ [
+ ("data.csv", b"a,b\n1,2\n", "a,b\n1,2\n"),
+ ("config.yaml", "name: café\n".encode("utf-8"), "name: café\n"),
+ ("legacy.txt", "naïve".encode("latin-1"), "naïve"),
+ ("utf16.txt", "hello".encode("utf-16"), "hello"),
+ ("script", b"#!/bin/sh\necho hi\n", "#!/bin/sh\necho hi\n"),
+ ],
+ )
+ def test_anything_that_decodes_as_text(self, name, data, expected):
+ text, _, note = extract_text(name, data)
+ assert text == expected
+ assert note is None
+
+ def test_binary_is_described_not_read(self):
+ text, label, note = extract_text("archive.bin", b"\x00\x01\x02binary\x00")
+ assert text is None
+ assert label == "BIN file"
+ assert "binary file" in note
+
+ def test_legacy_office_explains_how_to_fix(self):
+ text, label, note = extract_text("old.doc", b"\xd0\xcf\x11\xe0binary")
+ assert text is None
+ assert label == "Word 97-2003"
+ assert ".docx" in note
+
+ def test_pdf_without_text_says_so(self):
+ out = io.BytesIO()
+ Image.new("RGB", (50, 50), "white").save(out, format="PDF")
+ text, label, note = extract_text("scan.pdf", out.getvalue())
+ assert label == "PDF"
+ assert text == ""
+ assert "scanned" in note
+
+
+class TestReadAttachment:
+ def test_image_becomes_flattened_jpeg(self):
+ att = read_attachment("photo.png", _png())
+ assert att.kind == "image"
+ assert att.format == "PNG image"
+ assert (att.width, att.height) == (40, 30)
+ decoded = Image.open(io.BytesIO(base64.b64decode(att.image)))
+ assert decoded.format == "JPEG" and decoded.mode == "RGB"
+
+ def test_large_image_is_scaled_down(self):
+ att = read_attachment("big.png", _png(4000, 1000, mode="RGB"))
+ assert max(att.width, att.height) == attachments.IMAGE_MAX_SIDE
+ assert att.width == attachments.IMAGE_MAX_SIDE
+
+ def test_document(self):
+ att = read_attachment("notes.md", b"# Notes\nBuy milk")
+ assert att.kind == "document"
+ assert att.text == "# Notes\nBuy milk"
+ assert att.truncated is False
+
+ def test_long_text_is_truncated(self, monkeypatch):
+ monkeypatch.setattr(attachments, "MAX_TEXT_CHARS", 10)
+ att = read_attachment("long.txt", b"x" * 25)
+ assert att.text == "x" * 10 and att.truncated is True
+
+ def test_damaged_file_does_not_raise(self):
+ att = read_attachment("broken.docx", b"PK\x03\x04not really a zip")
+ assert att.kind == "unsupported"
+ assert "damaged" in att.note
+
+
+class TestEndpoint:
+ @pytest.fixture
+ def client(self):
+ app = fastapi.FastAPI()
+ app.include_router(attachments.router)
+ return TestClient(app)
+
+ def test_reads_several_files(self, client):
+ resp = client.post(
+ "/v1/attachments",
+ files=[
+ ("files", ("a.txt", b"hello", "text/plain")),
+ ("files", ("b.png", _png(), "image/png")),
+ ("files", ("c.bin", b"\x00\x00\x00", "application/octet-stream")),
+ ],
+ )
+ assert resp.status_code == 200
+ kinds = [a["kind"] for a in resp.json()["attachments"]]
+ assert kinds == ["document", "image", "unsupported"]
+
+ def test_rejects_too_many_files(self, client, monkeypatch):
+ monkeypatch.setattr(attachments, "MAX_FILES", 1)
+ resp = client.post(
+ "/v1/attachments",
+ files=[
+ ("files", ("a.txt", b"a", "text/plain")),
+ ("files", ("b.txt", b"b", "text/plain")),
+ ],
+ )
+ assert resp.status_code == 400
+
+ def test_rejects_oversized_file(self, client, monkeypatch):
+ monkeypatch.setattr(attachments, "MAX_FILE_BYTES", 4)
+ resp = client.post(
+ "/v1/attachments", files=[("files", ("a.txt", b"hello", "text/plain"))]
+ )
+ assert resp.status_code == 413
+ assert "a.txt" in resp.json()["detail"]
+
+
+class TestPromptFolding:
+ def test_render_marks_cut_text(self):
+ block, used = render_attachments(
+ [MessageAttachment(name="a.txt", format="text", text="abcdef")], 4
+ )
+ assert used == 4
+ assert (
+ '\nabcd\n[... the rest' in block
+ )
+
+ def test_note_only_attachment(self):
+ block, used = render_attachments(
+ [MessageAttachment(name="x.bin", format="BIN file", note="Binary.")], 100
+ )
+ assert used == 0
+ assert "[Binary.]" in block
+
+ def test_newest_message_gets_the_budget_first(self):
+ old = ChatMessage(
+ role="user",
+ content="first",
+ attachments=[MessageAttachment(name="old.txt", text="o" * 30)],
+ )
+ new = ChatMessage(
+ role="user",
+ content="second",
+ attachments=[MessageAttachment(name="new.txt", text="n" * 30)],
+ )
+ contents = contents_with_attachments(
+ [old, ChatMessage(role="assistant", content="ok"), new], budget=40
+ )
+ assert "n" * 30 in contents[2]
+ assert "o" * 10 in contents[0] and "o" * 11 not in contents[0]
+ assert contents[1] == "ok"
+ assert contents[2].endswith("\n\nsecond")
+
+ def test_attachment_only_message(self):
+ msg = ChatMessage(
+ role="user",
+ content="",
+ attachments=[MessageAttachment(name="a.txt", text="hi")],
+ )
+ (content,) = contents_with_attachments([msg])
+ assert content.startswith("The user attached these files:")
diff --git a/tests/server/test_chat_extras.py b/tests/server/test_chat_extras.py
new file mode 100644
index 0000000..a5f2ff7
--- /dev/null
+++ b/tests/server/test_chat_extras.py
@@ -0,0 +1,251 @@
+"""Attachments, images and web search on /v1/chat/completions."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient # noqa: E402
+
+from locus.core.types import Role # noqa: E402
+from locus.server import routes # noqa: E402
+from locus.server.app import create_app # noqa: E402
+from locus.server.web_context import ( # noqa: E402
+ WebSearchResult,
+ WebSource,
+ parse_results,
+ render_context,
+)
+
+
+def _recording_engine(seen: list):
+ engine = MagicMock()
+ engine.engine_id = "mock"
+ engine.health.return_value = True
+ engine.list_models.return_value = ["test-model"]
+
+ async def stream(messages, *, model, temperature=0.7, max_tokens=1024, **kwargs):
+ seen.append(list(messages))
+ for token in ["Hi", "!"]:
+ yield token
+
+ engine.stream = stream
+ return engine
+
+
+def _config():
+ from locus.core.config import JarvisConfig
+
+ cfg = JarvisConfig()
+ cfg.analytics.enabled = False
+ cfg.traces.enabled = False
+ cfg.security.enabled = False
+ cfg.agent.context_from_memory = False
+ return cfg
+
+
+@pytest.fixture
+def seen():
+ return []
+
+
+@pytest.fixture
+def client(seen, monkeypatch):
+ routes._vision_cache.clear()
+ agent = MagicMock()
+ agent._tools = [object()]
+ app = create_app(
+ _recording_engine(seen), "test-model", agent=agent, config=_config()
+ )
+ return TestClient(app)
+
+
+def _post(client, messages, **extra):
+ return client.post(
+ "/v1/chat/completions",
+ json={"model": "test-model", "messages": messages, "stream": True, **extra},
+ )
+
+
+def _events(resp):
+ """``(event_name, data)`` pairs from an SSE body."""
+ out, name = [], None
+ for line in resp.text.split("\n"):
+ if line.startswith("event: "):
+ name = line[7:].strip()
+ elif line.startswith("data: "):
+ out.append((name, line[6:]))
+ name = None
+ return out
+
+
+class TestAttachments:
+ def test_documents_are_folded_into_the_message(self, client, seen):
+ resp = _post(
+ client,
+ [
+ {
+ "role": "user",
+ "content": "Summarize this",
+ "attachments": [
+ {"name": "notes.txt", "format": "text", "text": "Buy milk"}
+ ],
+ }
+ ],
+ )
+ assert resp.status_code == 200
+ user = [m for m in seen[0] if m.role == Role.USER][-1]
+ assert (
+ '\nBuy milk' in user.content
+ )
+ assert user.content.endswith("Summarize this")
+
+ def test_extras_bypass_the_server_agent(self, client, seen):
+ # The agent only sees the latest message's text, so the request must
+ # reach the engine directly for the attachment to be used.
+ _post(
+ client,
+ [
+ {
+ "role": "user",
+ "content": "x",
+ "attachments": [{"name": "a", "text": "b"}],
+ }
+ ],
+ )
+ assert len(seen) == 1
+
+ def test_images_reach_a_vision_model(self, client, seen, monkeypatch):
+ async def yes(engine, model):
+ return True
+
+ monkeypatch.setattr(routes, "_model_accepts_images", yes)
+ _post(
+ client,
+ [{"role": "user", "content": "What is this?", "images": ["aGVsbG8="]}],
+ )
+ user = [m for m in seen[0] if m.role == Role.USER][-1]
+ assert user.images == ["aGVsbG8="]
+
+ def test_images_become_a_note_for_text_only_models(self, client, seen, monkeypatch):
+ async def no(engine, model):
+ return False
+
+ monkeypatch.setattr(routes, "_model_accepts_images", no)
+ _post(
+ client, [{"role": "user", "content": "What is this?", "images": ["a", "b"]}]
+ )
+ user = [m for m in seen[0] if m.role == Role.USER][-1]
+ assert user.images is None
+ assert "attached 2 image(s)" in user.content
+ assert "vision model" in user.content
+
+
+class TestWebSearch:
+ @pytest.fixture
+ def search(self, monkeypatch):
+ calls = []
+
+ async def fake_search(query):
+ calls.append(query)
+ return WebSearchResult(
+ query=query,
+ engine="duckduckgo",
+ sources=[
+ WebSource(
+ ref=1,
+ title="Ollama",
+ url="https://ollama.com",
+ text="Run models locally.",
+ )
+ ],
+ )
+
+ monkeypatch.setattr("locus.server.web_context.search_web", fake_search)
+ return calls
+
+ def test_sources_arrive_before_the_answer(self, client, search):
+ resp = _post(
+ client, [{"role": "user", "content": "What is Ollama?"}], web_search=True
+ )
+ events = _events(resp)
+ assert events[0][0] == "web_search"
+ payload = json.loads(events[0][1])
+ assert payload["query"] == "What is Ollama?"
+ assert payload["sources"] == [
+ {"ref": 1, "title": "Ollama", "url": "https://ollama.com"}
+ ]
+ assert events[-1][1] == "[DONE]"
+
+ def test_results_are_in_the_system_prompt_with_identity(self, client, seen, search):
+ _post(client, [{"role": "user", "content": "What is Ollama?"}], web_search=True)
+ system = [m for m in seen[0] if m.role == Role.SYSTEM]
+ assert len(system) == 1
+ assert (
+ "[1] Ollama\nURL: https://ollama.com\nRun models locally."
+ in system[0].content
+ )
+ # The search results don't count as a caller system prompt, so the
+ # server's identity prompt is still there ahead of them.
+ assert system[0].content.index("[1] Ollama") > 0
+ assert system[0].name is None
+
+ def test_searches_the_latest_user_message(self, client, search):
+ _post(
+ client,
+ [
+ {"role": "user", "content": "first"},
+ {"role": "assistant", "content": "ok"},
+ {"role": "user", "content": "weather in Pune today"},
+ ],
+ web_search=True,
+ )
+ assert search == ["weather in Pune today"]
+
+ def test_off_by_default(self, client, search):
+ resp = _post(client, [{"role": "user", "content": "hello"}])
+ assert search == []
+ assert all(name != "web_search" for name, _ in _events(resp))
+
+
+class TestWebContext:
+ def test_parse_results(self):
+ content = (
+ "### First\nSource: https://a.example\nSummary: Alpha\n\n---\n\n"
+ "### Second\nSource: https://b.example\nSummary: Beta\nmore"
+ )
+ sources = parse_results(content)
+ assert [(s.ref, s.title, s.url, s.snippet) for s in sources] == [
+ (1, "First", "https://a.example", "Alpha"),
+ (2, "Second", "https://b.example", "Beta\nmore"),
+ ]
+
+ def test_render_prefers_page_text_and_dates_results(self):
+ result = WebSearchResult(
+ query="q",
+ sources=[
+ WebSource(
+ ref=1,
+ title="T",
+ url="https://t.example",
+ snippet="short",
+ text="full page",
+ )
+ ],
+ )
+ context = render_context(result, today=dt.date(2026, 11, 1))
+ assert "retrieved 2026-11-01" in context
+ assert "full page" in context and "short" not in context
+ assert "[1], [2]" in context
+
+ def test_render_failure_tells_the_model(self):
+ context = render_context(
+ WebSearchResult(query="q", error="The web search timed out.")
+ )
+ assert "timed out" in context
+ assert "couldn't check the web" in context
diff --git a/tests/server/test_profile_routes.py b/tests/server/test_profile_routes.py
new file mode 100644
index 0000000..9eb7c14
--- /dev/null
+++ b/tests/server/test_profile_routes.py
@@ -0,0 +1,152 @@
+"""The user's name in USER.md, and the assistant using their nickname."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient # noqa: E402
+
+from locus.core.types import Role # noqa: E402
+from locus.server.app import create_app # noqa: E402
+from locus.server.profile_routes import ( # noqa: E402
+ END,
+ START,
+ Profile,
+ parse_block,
+ render_block,
+)
+
+
+def _config(user_path):
+ from locus.core.config import JarvisConfig
+
+ cfg = JarvisConfig()
+ cfg.analytics.enabled = False
+ cfg.traces.enabled = False
+ cfg.security.enabled = False
+ cfg.agent.context_from_memory = False
+ cfg.memory_files.user_path = str(user_path)
+ cfg.memory_files.soul_path = ""
+ cfg.memory_files.memory_path = ""
+ return cfg
+
+
+@pytest.fixture
+def user_md(tmp_path):
+ return tmp_path / "USER.md"
+
+
+@pytest.fixture
+def seen():
+ return []
+
+
+@pytest.fixture
+def client(user_md, seen):
+ engine = MagicMock()
+ engine.engine_id = "mock"
+ engine.health.return_value = True
+ engine.list_models.return_value = ["test-model"]
+
+ async def stream(messages, *, model, temperature=0.7, max_tokens=1024, **kwargs):
+ seen.append(list(messages))
+ yield "Hi"
+
+ engine.stream = stream
+ return TestClient(create_app(engine, "test-model", config=_config(user_md)))
+
+
+def test_empty_profile(client):
+ assert client.get("/v1/profile").json() == {
+ "first_name": "",
+ "last_name": "",
+ "nickname": "",
+ }
+
+
+def test_save_and_read_back(client, user_md):
+ body = {"first_name": "Aryan", "last_name": "Kumar", "nickname": "Ary"}
+ assert client.put("/v1/profile", json=body).json() == body
+ assert client.get("/v1/profile").json() == body
+ text = user_md.read_text(encoding="utf-8")
+ assert text.startswith(START)
+ assert 'Address the user as "Ary"' in text
+
+
+def test_keeps_the_rest_of_user_md(client, user_md):
+ user_md.write_text("I like short answers.\n", encoding="utf-8")
+ client.put(
+ "/v1/profile", json={"first_name": "Aryan", "last_name": "", "nickname": ""}
+ )
+ client.put(
+ "/v1/profile", json={"first_name": "Aryan", "last_name": "", "nickname": "Ary"}
+ )
+ text = user_md.read_text(encoding="utf-8")
+ assert text.count(START) == 1
+ assert text.endswith("I like short answers.\n")
+
+ client.put("/v1/profile", json={"first_name": "", "last_name": "", "nickname": ""})
+ assert user_md.read_text(encoding="utf-8") == "I like short answers.\n"
+
+
+def test_clearing_an_otherwise_empty_file_removes_it(client, user_md):
+ client.put("/v1/profile", json={"first_name": "A", "last_name": "", "nickname": ""})
+ client.put("/v1/profile", json={"first_name": "", "last_name": "", "nickname": ""})
+ assert not user_md.exists()
+
+
+def test_values_are_one_plain_line(client):
+ resp = client.put(
+ "/v1/profile",
+ json={
+ "first_name": "Ar\nyan",
+ "last_name": "",
+ "nickname": " Ary ",
+ },
+ )
+ assert resp.json() == {"first_name": "Ar yan", "last_name": "x", "nickname": "Ary"}
+
+
+def test_rejects_long_names(client):
+ assert client.put("/v1/profile", json={"nickname": "x" * 51}).status_code == 422
+
+
+def test_first_name_is_used_without_a_nickname():
+ block = render_block(Profile(first_name="Aryan", last_name="Kumar"))
+ assert 'Address the user as "Aryan"' in block
+ assert parse_block(f"before\n{block}after") == Profile(
+ first_name="Aryan", last_name="Kumar"
+ )
+ assert render_block(Profile()) == ""
+ assert END in block
+
+
+def test_the_assistant_is_told_the_nickname(client, seen):
+ client.put(
+ "/v1/profile",
+ json={"first_name": "Aryan", "last_name": "Kumar", "nickname": "Ary"},
+ )
+ client.post(
+ "/v1/chat/completions",
+ json={
+ "model": "test-model",
+ "messages": [{"role": "user", "content": "hello"}],
+ "stream": True,
+ },
+ )
+ system = [m for m in seen[0] if m.role == Role.SYSTEM]
+ assert len(system) == 1
+ assert "## User Profile" in system[0].content
+ assert 'Address the user as "Ary"' in system[0].content
+
+
+def test_persona_none_cannot_store_a_name(user_md):
+ cfg = _config(user_md)
+ cfg.memory_files.persona_name = "none"
+ engine = MagicMock()
+ client = TestClient(create_app(engine, "test-model", config=cfg))
+ assert client.put("/v1/profile", json={"nickname": "Ary"}).status_code == 409
diff --git a/uv.lock b/uv.lock
index deb930f..88537e0 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3653,6 +3653,8 @@ desktop = [
{ name = "faster-whisper" },
{ name = "numpy" },
{ name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or (platform_machine == 'x86_64' and sys_platform == 'darwin')" },
+ { name = "pdfplumber" },
+ { name = "pillow" },
{ name = "pydantic" },
{ name = "python-multipart" },
{ name = "sounddevice" },
@@ -3771,6 +3773,8 @@ security-signing = [
]
server = [
{ name = "fastapi" },
+ { name = "pdfplumber" },
+ { name = "pillow" },
{ name = "pydantic" },
{ name = "python-multipart" },
{ name = "uvicorn" },
@@ -3865,8 +3869,12 @@ requires-dist = [
{ name = "openai", marker = "extra == 'inference-cloud'", specifier = ">=1.30" },
{ name = "openai", marker = "extra == 'media'", specifier = ">=1.30" },
{ name = "openhands-sdk", marker = "python_full_version >= '3.12' and extra == 'openhands'", specifier = ">=1.0" },
+ { name = "pdfplumber", marker = "extra == 'desktop'", specifier = ">=0.10" },
{ name = "pdfplumber", marker = "extra == 'memory-pdf'", specifier = ">=0.10" },
{ name = "pdfplumber", marker = "extra == 'pdf'", specifier = ">=0.10" },
+ { name = "pdfplumber", marker = "extra == 'server'", specifier = ">=0.10" },
+ { name = "pillow", marker = "extra == 'desktop'", specifier = ">=10" },
+ { name = "pillow", marker = "extra == 'server'", specifier = ">=10" },
{ name = "playwright", marker = "extra == 'browser'", specifier = ">=1.40" },
{ name = "polars", marker = "extra == 'framework-comparison'", specifier = ">=1.0" },
{ name = "posthog", specifier = ">=3.0" },