Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
API v1: GET /search, keyword over every recording and semantic through Inquire (mailr spec G3); notes are per user in API v1 (open question 2)
Murtaza Nasirc18ddc436ee2
diff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.mdindex 81080c3a..11759f1c 100644--- a/docs/user-guide/api-reference.md+++ b/docs/user-guide/api-reference.md@@ -654,6 +654,8 @@ GET /api/v1/recordings/{id}/notes**Scope:** `read`+Notes are per user. The owner gets the recording's notes. A user the recording is shared with gets only their own personal notes, never the owner's; the same holds for `notes` in the recording details and in search.+**Response:**```json@@ -727,6 +729,8 @@ PUT /api/v1/recordings/{id}/notes**Scope:** `write`+The owner replaces the recording's notes. A user the recording is shared with, even with view access only, replaces their own personal notes; the owner's notes do not change. `notes` in `PATCH /api/v1/recordings/{id}` follows the same rule.+**Request Body:**```json@@ -789,6 +793,65 @@ DELETE /api/v1/recordings/{id}---+## Search++### Search Recordings++```http+GET /api/v1/search+```++**Scope:** `read`++Finds words in the titles, participants, notes, summaries and transcripts of your recordings, with the time and speaker of each transcript hit. Keyword search works on every installation; semantic search needs Inquire mode.++| Parameter | Type | Default | Description |+|-----------|------|---------|-------------|+| `q` | string | required | 2 to 500 characters. Words are matched separately; `"a quoted phrase"` stays together. Every word must appear in the recording. `%` and `_` are literal. |+| `mode` | string | `keyword` | `keyword`, `semantic`, or `auto` (semantic when available, else keyword) |+| `fields` | string | all | Comma list of `title`, `participants`, `notes`, `summary`, `transcript` (keyword mode) |+| `scope` | string | `own` | `own` |+| `recording_ids` | string | - | Comma list of recording ids |+| `tag_id`, `folder_id` | - | - | As on [List Recordings](#list-recordings) |+| `speaker` | string | - | Transcript hits of this speaker only (exact name, any case) |+| `date_from`, `date_to` | string | - | ISO dates or date-times; a date alone includes that whole day |+| `date_field` | string | `meeting_date` | `meeting_date` (the creation time where a recording has none) or `created_at` |+| `limit` | integer | 20 | 1 to 50 hits |+| `page` | integer | 1 | Keyword mode |++**Response:**++```json+{+ "query": "budget freeze",+ "mode_used": "keyword",+ "results": [+ {+ "recording_id": 412,+ "title": "Weekly sync",+ "meeting_date": "2026-09-29T15:00:00Z",+ "field": "transcript",+ "segment_index": 87,+ "start_time": 754.2,+ "end_time": 761.0,+ "speaker": "Dana",+ "text": "So the budget freeze applies to travel only.",+ "match_spans": [[7, 13], [14, 20]],+ "score": 0.7+ }+ ],+ "page": 1,+ "has_more": false+}+```++- Keyword hits: the title and participants as a whole, notes and summaries per line, transcripts per segment. `text` is at most 400 characters around the first match; `match_spans` are character offsets into `text`. A transcript without speaker segments gives hits with `start_time` and `segment_index` set to `null`.+- `score` is the share of the query words in the hit times a weight per field (title 1.0, summary 0.9, notes and participants 0.8, transcript 0.7). Ties go to the newer recording.+- Keyword mode reads at most the 200 newest matching recordings per request.+- Semantic hits come from the Inquire index: `field` is `transcript`, `segment_index` is `null`, `score` is the similarity. The query text is sent to the embedding model of the instance; `GET /api/v1/capabilities` reports `features.search.semantic` and `models_local`.+- `mode=semantic` on an instance without Inquire mode: `409` with `"code": "semantic_unavailable"`.+- Limit: 30 requests per minute per token (`API_SEARCH_RATE_LIMIT`).+## Tags### List Tagsdiff --git a/docs/user-guide/inquire-mode.md b/docs/user-guide/inquire-mode.mdindex 4d574cb5..a4e5a07d 100644--- a/docs/user-guide/inquire-mode.md+++ b/docs/user-guide/inquire-mode.md@@ -82,6 +82,10 @@ A note on changing embedding models: vectors from different models are not compaPerformance scales well with proper setup. The initial indexing of recordings happens automatically after transcription, and subsequent searches leverage this pre-computed index. Response times typically range from a few seconds for focused searches to slightly longer for complex queries across large libraries.+## Searching from Other Tools++Semantic search is also available through the API: `GET /api/v1/search?mode=semantic` (see the [API Reference](api-reference.md#search)). The same request without `mode=semantic` runs a keyword search over every recording, which works without Inquire mode.+## Agentic Inquire (Beta)Administrators can enable an agentic mode with `ENABLE_INQUIRE_AGENT=true` (requires Inquire Mode to be enabled). Instead of a single retrieval pass, an AI agent works iteratively: it searches your transcripts, lists recordings, and reads transcripts, summaries, or notes as needed, thinking between steps until it can answer. The interface shows each step live (what was searched, what was read, how many matches), a Stop button to interrupt, and a collapsed activity line on every answer so you can always see how a conclusion was reached. Answers cite their sources as compact numbered markers such as "2 @ 14:05": clicking one opens that recording and starts playback at the cited moment, and a Sources list at the end of each answer maps every number to its recording. The numbering stays stable through the conversation, so a follow-up like "tell me more about 3" refers to exactly what you saw.diff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex e48ed744..ca0fa9a2 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -25,7 +25,7 @@ from typing import Optionalfrom flask import Blueprint, jsonify, request, current_app, send_file, redirectfrom flask_login import login_required, current_user-from src.utils.token_auth import require_scope+from src.utils.token_auth import require_scope, token_rate_keyfrom sqlalchemy import func, extract, or_, and_from werkzeug.exceptions import RequestEntityTooLargefrom werkzeug.utils import secure_filename@@ -253,6 +253,30 @@ OPENAPI_SPEC = {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Capabilities"}}}}}}},+ "/search": {+ "get": {+ "tags": ["Recordings"],+ "summary": "Search titles, participants, notes, summaries and transcripts",+ "description": "Keyword search over every recording you own, or semantic search through the Inquire index (mode=semantic). Transcript hits carry segment_index, start_time, end_time and speaker.",+ "parameters": [+ {"name": "q", "in": "query", "required": True, "schema": {"type": "string"}},+ {"name": "mode", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "fields", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "scope", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "recording_ids", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "tag_id", "in": "query", "required": False, "schema": {"type": "integer"}},+ {"name": "folder_id", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "speaker", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "date_from", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "date_to", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "date_field", "in": "query", "required": False, "schema": {"type": "string"}},+ {"name": "limit", "in": "query", "required": False, "schema": {"type": "integer"}},+ {"name": "page", "in": "query", "required": False, "schema": {"type": "integer"}}+ ],+ "responses": {"200": {"description": "Hits"}, "400": {"description": "invalid_parameter"},+ "409": {"description": "semantic_unavailable"}}+ }+ },"/recordings/changes": {"get": {"tags": ["Recordings"],@@ -892,6 +916,7 @@ CAPABILITY_FEATURES = {'etags': True,'webhook_signature_v2': True,}+# search: {'keyword': True, 'semantic': <Inquire on>} is filled in get_capabilities.@api_v1_bp.route('/capabilities', methods=['GET'])@@ -904,6 +929,8 @@ def get_capabilities():features['internal_sharing'] = os.environ.get('ENABLE_INTERNAL_SHARING', 'false').lower() == 'true'features['public_sharing'] = os.environ.get('ENABLE_PUBLIC_SHARING', 'true').lower() == 'true'features['can_share_publicly'] = bool(features['public_sharing'] and getattr(current_user, 'can_share_publicly', True))+ from src.services.search_v1 import semantic_available+ features['search'] = {'keyword': True, 'semantic': semantic_available()}features['inquire'] = {'enabled': os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() == 'true','agent': os.environ.get('ENABLE_INQUIRE_AGENT', 'false').lower() == 'true',@@ -1227,6 +1254,77 @@ def _conditional(prefix):return decorator+@api_v1_bp.route('/search', methods=['GET'])+@require_scope('read')+@rate_limit(os.environ.get('API_SEARCH_RATE_LIMIT', '30 per minute'), key_func=token_rate_key)+@login_required+def search_recordings_v1():+ """Search titles, participants, notes, summaries and transcripts (mailr spec G3).++ Query params: q (2 to 500 characters), mode (keyword | semantic | auto),+ fields, scope (own), recording_ids, tag_id, folder_id, speaker,+ date_from, date_to, date_field (meeting_date | created_at), limit (1-50),+ page (keyword mode).+ """+ from src.services import search_v1+ args = request.args+ q = (args.get('q') or '').strip()+ if not 2 <= len(q) <= 500:+ return jsonify({'error': 'q must be 2 to 500 characters', 'code': 'invalid_parameter'}), 400+ mode = args.get('mode', 'keyword')+ if mode not in ('keyword', 'semantic', 'auto'):+ return jsonify({'error': 'mode must be keyword, semantic or auto', 'code': 'invalid_parameter'}), 400+ if args.get('scope', 'own') != 'own':+ return jsonify({'error': "scope must be 'own'", 'code': 'invalid_parameter'}), 400+ fields = tuple(f.strip() for f in args.get('fields', ','.join(search_v1.FIELDS)).split(',') if f.strip())+ unknown = [f for f in fields if f not in search_v1.FIELDS]+ if unknown or not fields:+ return jsonify({'error': f'Unknown field(s): {", ".join(unknown) or "none given"}',+ 'code': 'invalid_parameter'}), 400+ date_field = args.get('date_field', 'meeting_date')+ if date_field not in ('meeting_date', 'created_at'):+ return jsonify({'error': 'date_field must be meeting_date or created_at', 'code': 'invalid_parameter'}), 400+ limit = args.get('limit', 20, type=int)+ page = args.get('page', 1, type=int)+ if limit is None or not 1 <= limit <= 50 or page is None or page < 1:+ return jsonify({'error': 'limit must be 1 to 50 and page at least 1', 'code': 'invalid_parameter'}), 400+ try:+ recording_ids = [int(x) for x in args.get('recording_ids', '').split(',') if x.strip()] or None+ except ValueError:+ return jsonify({'error': 'recording_ids must be a comma list of ids', 'code': 'invalid_parameter'}), 400+ folder = args.get('folder_id', '').strip()+ folder_id = None+ if folder:+ if folder.lower() == 'none':+ folder_id = 'none'+ elif folder.isdigit():+ folder_id = int(folder)+ else:+ return jsonify({'error': 'folder_id must be an id or none', 'code': 'invalid_parameter'}), 400+ filters = dict(recording_ids=recording_ids, tag_id=args.get('tag_id', type=int), folder_id=folder_id,+ date_from=args.get('date_from') or None, date_to=args.get('date_to') or None,+ date_field=date_field)+ speaker = (args.get('speaker') or '').strip() or None++ use_semantic = mode == 'semantic' or (mode == 'auto' and search_v1.semantic_available())+ if mode == 'semantic' and not search_v1.semantic_available():+ return jsonify({'error': 'Semantic search is not available on this instance',+ 'code': 'semantic_unavailable'}), 409+ try:+ if use_semantic:+ # The dates are checked the same way in both modes.+ search_v1.candidate_query(current_user, ['x'], ('title',), **filters)+ results = search_v1.semantic_search(current_user, q, limit=limit, speaker=speaker, **filters)+ has_more = False+ else:+ results, has_more = search_v1.keyword_search(current_user, q, fields=fields, speaker=speaker,+ limit=limit, page=page, **filters)+ except search_v1.SearchError as e:+ return jsonify({'error': str(e), 'code': e.code}), e.status+ return jsonify({'query': q, 'mode_used': 'semantic' if use_semantic else 'keyword',+ 'results': results, 'page': page if not use_semantic else 1, 'has_more': has_more})++@api_v1_bp.route('/recordings/changes', methods=['GET'])@require_scope('read')@login_required@@ -1332,7 +1430,7 @@ def get_recording(recording_id):if 'summary' in include_fields:response['summary'] = recording.summaryif 'notes' in include_fields:- response['notes'] = recording.notes+ response['notes'] = recording.get_user_notes(current_user)return jsonify(response)@@ -1464,9 +1562,11 @@ def get_notes(recording_id):if not has_recording_access(recording, current_user):return jsonify({'error': 'Permission denied'}), 403+ # The owner's notes for the owner; a recipient's own personal notes otherwise.+ notes = recording.get_user_notes(current_user)return jsonify({- 'notes': recording.notes,- 'has_notes': bool(recording.notes)+ 'notes': notes,+ 'has_notes': bool(notes)})@@ -1522,7 +1622,8 @@ def update_recording(recording_id):if 'participants' in data:recording.participants = data['participants']if 'notes' in data:- recording.notes = data['notes']+ from src.services.recording_state import set_user_notes+ set_user_notes(recording, current_user, data['notes'])if 'summary' in data:recording.summary = data['summary']if 'meeting_date' in data:@@ -1578,7 +1679,7 @@ def update_recording(recording_id):'id': recording.id,'title': recording.title,'participants': recording.participants,- 'notes': recording.notes,+ 'notes': recording.get_user_notes(current_user),'summary': recording.summary,'meeting_date': recording.meeting_date.isoformat() if recording.meeting_date else None,'is_inbox': recording.is_inbox,@@ -1599,17 +1700,20 @@ def replace_notes(recording_id):if not recording:return jsonify({'error': 'Recording not found'}), 404- if not has_recording_access(recording, current_user, require_edit=True):+ # Notes are per user, as in the web app: a recipient with view access+ # writes their personal notes, never the owner's.+ if not has_recording_access(recording, current_user):return jsonify({'error': 'Permission denied'}), 403data = request.get_json()if not data or 'notes' not in data:return jsonify({'error': 'notes field required'}), 400- recording.notes = data['notes']+ from src.services.recording_state import set_user_notes+ set_user_notes(recording, current_user, data['notes'])db.session.commit()- return jsonify({'success': True, 'notes': recording.notes})+ return jsonify({'success': True, 'notes': recording.get_user_notes(current_user)})@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['PUT'])diff --git a/src/services/recording_state.py b/src/services/recording_state.pyindex 688719a8..66e95214 100644--- a/src/services/recording_state.py+++ b/src/services/recording_state.py@@ -68,3 +68,18 @@ def archived_condition(recording_model, user_id):db.func.coalesce(recording_model.is_archived, False) == True), # noqa: E712recording_model.id.in_(shared_archived),)+++def set_user_notes(recording, user, notes):+ """The owner writes the recording's notes; anyone else writes their own+ personal notes and never sees or changes the owner's (mailr spec Q2)."""+ if recording.user_id == user.id:+ recording.notes = notes+ return+ state = _state(recording, user)+ if not state:+ state = SharedRecordingState(recording_id=recording.id, user_id=user.id,+ is_inbox=True, is_highlighted=False)+ db.session.add(state)+ state.personal_notes = notes+diff --git a/src/services/search_v1.py b/src/services/search_v1.pynew file mode 100644index 00000000..b535e181--- /dev/null+++ b/src/services/search_v1.py@@ -0,0 +1,241 @@+"""Keyword and semantic search over recordings for API v1 (mailr spec G3).++Keyword mode: the query splits into terms (a quoted phrase stays one term).+A recording is a candidate when every term appears in one of the selected+fields (ILIKE, on SQLite and PostgreSQL); at most MAX_CANDIDATES candidates,+newest first, are read. Each field then gives hits: the title and the+participants as a whole, notes and summary per line, the transcript per+segment. The access filter runs first, so a recording the caller cannot read+is never a candidate.+"""++import re+from datetime import datetime++from sqlalchemy import func, or_++from src.database import db++FIELDS = ('title', 'participants', 'notes', 'summary', 'transcript')+WEIGHTS = {'title': 1.0, 'summary': 0.9, 'notes': 0.8, 'participants': 0.8, 'transcript': 0.7}+MAX_CANDIDATES = 200+TEXT_LIMIT = 400++_TERM = re.compile(r'"([^"]+)"|(\S+)')+++class SearchError(ValueError):+ def __init__(self, message, code='invalid_parameter', status=400):+ super().__init__(message)+ self.code = code+ self.status = status+++def parse_terms(query):+ terms = []+ for phrase, word in _TERM.findall(query or ''):+ term = (phrase or word).strip()+ if term and term.lower() not in (t.lower() for t in terms):+ terms.append(term)+ return terms+++def _like(term):+ escaped = term.replace('\\', '\\\\').replace('%', '\\%').replace('_', '\\_')+ return f'%{escaped}%'+++def _spans(text, terms):+ lower = text.lower()+ spans = []+ for term in terms:+ needle = term.lower()+ start = lower.find(needle)+ while start != -1:+ spans.append([start, start + len(needle)])+ start = lower.find(needle, start + 1)+ return sorted(spans)+++def _cut(text, spans):+ """At most TEXT_LIMIT characters around the first match; spans follow."""+ if len(text) <= TEXT_LIMIT:+ return text, spans+ first = spans[0][0] if spans else 0+ start = max(0, min(first - TEXT_LIMIT // 4, len(text) - TEXT_LIMIT))+ end = start + TEXT_LIMIT+ piece = text[start:end]+ prefix = '…' if start > 0 else ''+ suffix = '…' if end < len(text) else ''+ shifted = [[a - start + len(prefix), b - start + len(prefix)] for a, b in spans if a >= start and b <= end]+ return prefix + piece + suffix, shifted+++def _lines(text):+ for line in (text or '').splitlines():+ if line.strip():+ yield line.strip()+++def _hit(recording, field, text, terms, when, notes_for, segment=None):+ spans = _spans(text, terms)+ if not spans:+ return None+ matched = {t.lower() for t in terms if t.lower() in text.lower()}+ cut, cut_spans = _cut(text, spans)+ return {+ 'recording_id': recording.id,+ 'title': recording.title,+ 'meeting_date': _z(recording.meeting_date),+ 'field': field,+ 'segment_index': segment['index'] if segment else None,+ 'start_time': segment['start_time'] if segment else None,+ 'end_time': segment['end_time'] if segment else None,+ 'speaker': segment['speaker'] if segment else None,+ 'text': cut,+ 'match_spans': cut_spans,+ 'score': round(len(matched) / len(terms) * WEIGHTS[field], 4),+ '_when': when,+ '_terms': matched,+ }+++def _z(value):+ return value.strftime('%Y-%m-%dT%H:%M:%SZ') if value else None+++def _parse_date(value, end_of_day=False):+ from datetime import timedelta+ from src.utils.dates import to_utc_naive+ try:+ parsed = to_utc_naive(datetime.fromisoformat(value.replace('Z', '+00:00')))+ except (AttributeError, ValueError):+ raise SearchError(f'Invalid date: {value!r}')+ if end_of_day and len(value.strip()) == 10:+ return parsed + timedelta(days=1), True+ return parsed, False+++def candidate_query(user, terms, fields, recording_ids=None, tag_id=None, folder_id=None,+ date_from=None, date_to=None, date_field='meeting_date'):+ from src.models import Recording, RecordingTag+ query = Recording.query.filter(Recording.user_id == user.id) # scope=own (G4 adds shared)+ if recording_ids:+ query = query.filter(Recording.id.in_(recording_ids))+ if tag_id:+ query = query.filter(Recording.id.in_(+ db.session.query(RecordingTag.recording_id).filter(RecordingTag.tag_id == tag_id)))+ if folder_id is not None:+ query = query.filter(Recording.folder_id.is_(None) if folder_id == 'none'+ else Recording.folder_id == folder_id)+ when = (func.coalesce(Recording.meeting_date, Recording.created_at) if date_field == 'meeting_date'+ else Recording.created_at)+ if date_from:+ start, _ = _parse_date(date_from)+ query = query.filter(when >= start)+ if date_to:+ end, exclusive = _parse_date(date_to, end_of_day=True)+ query = query.filter(when < end if exclusive else when <= end)+ columns = {'title': Recording.title, 'participants': Recording.participants, 'notes': Recording.notes,+ 'summary': Recording.summary, 'transcript': Recording.transcription}+ for term in terms:+ pattern = _like(term)+ query = query.filter(or_(*[columns[f].ilike(pattern, escape='\\') for f in fields]))+ return query.order_by(when.desc(), Recording.id.desc()), when+++def keyword_search(user, query_text, fields=FIELDS, speaker=None, limit=20, page=1, **filters):+ from src.services.transcript_segments import segments_of+ terms = parse_terms(query_text)+ if not terms:+ raise SearchError('q must contain a word')+ if speaker:+ fields = ('transcript',)+ candidates, _ = candidate_query(user, terms, fields, **filters)+ hits = []+ for recording in candidates.limit(MAX_CANDIDATES).all():+ when = recording.meeting_date or recording.created_at or datetime.min+ found = []+ if 'title' in fields and recording.title:+ found.append(_hit(recording, 'title', recording.title, terms, when, None))+ if 'participants' in fields and recording.participants:+ found.append(_hit(recording, 'participants', recording.participants, terms, when, None))+ if 'notes' in fields:+ for line in _lines(recording.get_user_notes(user)):+ found.append(_hit(recording, 'notes', line, terms, when, None))+ if 'summary' in fields:+ for line in _lines(recording.summary):+ found.append(_hit(recording, 'summary', line, terms, when, None))+ if 'transcript' in fields and recording.transcription:+ segments = segments_of(recording.transcription)+ if segments is None:+ if not speaker:+ for line in _lines(recording.transcription):+ found.append(_hit(recording, 'transcript', line, terms, when, None))+ else:+ for seg in segments:+ if speaker and (seg['speaker'] or '').strip().lower() != speaker.strip().lower():+ continue+ hit = _hit(recording, 'transcript', seg['text'], terms, when, None, segment=seg)+ found.append(hit)+ found = [h for h in found if h]+ # Every term must appear somewhere in this recording's real text (the+ # candidate filter also matched JSON keys of the stored transcript).+ covered = set().union(*(h['_terms'] for h in found)) if found else set()+ if covered >= {t.lower() for t in terms}:+ hits.extend(found)+ hits.sort(key=lambda h: (-h['score'], -h['_when'].timestamp() if h['_when'] != datetime.min else 0,+ -h['recording_id'], h['segment_index'] if h['segment_index'] is not None else -1))+ start = (page - 1) * limit+ page_hits = hits[start:start + limit]+ for h in page_hits:+ h.pop('_when', None)+ h.pop('_terms', None)+ return page_hits, len(hits) > start + limit+++def semantic_available():+ from src.services import embeddings as emb+ import os+ inquire = os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() == 'true'+ return inquire and bool(emb.EMBEDDINGS_AVAILABLE)+++def semantic_search(user, query_text, limit=20, recording_ids=None, tag_id=None, date_from=None,+ date_to=None, speaker=None, **_ignored):+ from src.models import Recording+ from src.services.embeddings import semantic_search_chunks+ own = [rid for (rid,) in db.session.query(Recording.id).filter(Recording.user_id == user.id)]+ if recording_ids:+ own = [rid for rid in own if rid in set(recording_ids)]+ if not own:+ return []+ chunk_filters = {'recording_ids': own}+ if tag_id:+ chunk_filters['tag_ids'] = [tag_id]+ if date_from:+ chunk_filters['date_from'] = date_from[:10]+ if date_to:+ chunk_filters['date_to'] = date_to[:10]+ results = semantic_search_chunks(user.id, query_text, chunk_filters, top_k=limit * 3 if speaker else limit)+ hits = []+ for chunk, similarity in results:+ if speaker and (chunk.speaker_name or '').strip().lower() != speaker.strip().lower():+ continue+ rec = chunk.recording+ hits.append({+ 'recording_id': chunk.recording_id,+ 'title': rec.title if rec else None,+ 'meeting_date': _z(rec.meeting_date) if rec else None,+ 'field': 'transcript',+ 'segment_index': None,+ 'start_time': chunk.start_time,+ 'end_time': chunk.end_time,+ 'speaker': chunk.speaker_name,+ 'text': chunk.content[:TEXT_LIMIT],+ 'match_spans': [],+ 'score': round(float(similarity), 4),+ })+ if len(hits) >= limit:+ break+ return hitsdiff --git a/src/services/transcript_segments.py b/src/services/transcript_segments.pynew file mode 100644index 00000000..a50f111c--- /dev/null+++ b/src/services/transcript_segments.py@@ -0,0 +1,44 @@+"""Read a stored transcript as segments, whatever key set it was saved with.++Transcripts are stored as JSON lists of segments. Older connectors and edits+saved 'start'/'end'/'text' where newer ones save 'start_time'/'end_time'/+'sentence'. Every reader that needs segments goes through segments_of(), so+the key sets are handled in one place.+"""++import json+++def _number(value):+ try:+ return None if value is None else float(value)+ except (TypeError, ValueError):+ return None+++def segments_of(transcription):+ """[{index, speaker, text, start_time, end_time}] for a JSON transcript,+ None for a plain-text transcript or no transcript."""+ if not transcription:+ return None+ try:+ data = json.loads(transcription)+ except (TypeError, ValueError):+ return None+ if not isinstance(data, list):+ return None+ segments = []+ for index, seg in enumerate(data):+ if not isinstance(seg, dict):+ continue+ text = seg.get('sentence')+ if text is None:+ text = seg.get('text', '')+ segments.append({+ 'index': index,+ 'speaker': seg.get('speaker') or None,+ 'text': str(text or ''),+ 'start_time': _number(seg.get('start_time', seg.get('start'))),+ 'end_time': _number(seg.get('end_time', seg.get('end'))),+ })+ return segmentsdiff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.pyindex 9679665c..95c23467 100644--- a/tests/test_api_v1_scope_coverage.py+++ b/tests/test_api_v1_scope_coverage.py@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))from src.app import appEXPECTED = {- "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "get_recording",+ "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "search_recordings_v1", "get_recording","get_transcript", "get_summary", "get_notes", "get_recording_status", "list_tags", "list_folders","get_folder", "get_transcription_info", "list_speakers", "get_recording_speakers","get_recording_events", "download_events_ics", "download_audio"},diff --git a/tests/test_api_v1_search.py b/tests/test_api_v1_search.pynew file mode 100644index 00000000..1815cc38--- /dev/null+++ b/tests/test_api_v1_search.py@@ -0,0 +1,185 @@+"""GET /api/v1/search (mailr spec G3).++Keyword search reads every recording the caller owns, without semantic+search: a word spoken once a year ago is found with its timestamp and+speaker. Semantic mode needs Inquire mode and embeddings.++SHARED-DB: users, tokens, tags and recordings are removed afterwards.+"""++import json+import os+import secrets+import sys+from datetime import datetime+from unittest.mock import patch++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import APIToken, Recording, RecordingTag, SharedRecordingState, Tag, User+from src.utils.token_auth import hash_token++NEW_KEYS = [{"speaker": "Dana", "sentence": "Welcome back everyone.", "start_time": 0.0, "end_time": 3.0},+ {"speaker": "Dana", "sentence": "So the budget freeze applies to travel only.", "start_time": 754.2, "end_time": 761.0},+ {"speaker": "Omar", "sentence": "Understood, 100% clear_now.", "start_time": 762.0, "end_time": 765.0}]+OLD_KEYS = [{"speaker": "Lee", "text": "The zeppelin order shipped late.", "start": 12.5, "end": 15.0}]+++def world():+ with app.app_context():+ s = secrets.token_hex(4)+ me = User(username=f"srch_{s}", email=f"srch_{s}@local.test", password="x")+ other = User(username=f"srcho_{s}", email=f"srcho_{s}@local.test", password="x")+ db.session.add_all([me, other])+ db.session.commit()+ tag = Tag(name=f"t-{s}", user_id=me.id)+ sync = Recording(user_id=me.id, title="Weekly sync", status="COMPLETED", original_filename="a.wav",+ meeting_date=datetime(2026, 9, 29, 15), participants="Dana, Omar",+ transcription=json.dumps(NEW_KEYS), summary="## Budget\n- The budget freeze ends in January.",+ notes="Ask about the budget freeze exceptions.")+ old = Recording(user_id=me.id, title="Ops call", status="COMPLETED", original_filename="b.wav",+ meeting_date=datetime(2025, 9, 1, 10), transcription=json.dumps(OLD_KEYS))+ plain = Recording(user_id=me.id, title="Phone note", status="COMPLETED", original_filename="c.wav",+ created_at=datetime(2026, 1, 5, 9), transcription="A plain text transcript about the zeppelin.")+ theirs = Recording(user_id=other.id, title="Budget freeze secrets", status="COMPLETED",+ original_filename="d.wav", transcription=json.dumps(NEW_KEYS))+ db.session.add_all([tag, sync, old, plain, theirs])+ db.session.commit()+ db.session.add(RecordingTag(recording_id=old.id, tag_id=tag.id, order=0))+ tokens = {}+ for who in (me, other):+ p = f"tok-{secrets.token_urlsafe(16)}"+ db.session.add(APIToken(user_id=who.id, token_hash=hash_token(p), name="s", scopes=json.dumps(["read"])))+ tokens[who.id] = p+ db.session.commit()+ ids = dict(me=me.id, other=other.id, tag=tag.id, sync=sync.id, old=old.id, plain=plain.id,+ theirs=theirs.id, tokens=tokens)+ yield ids+ with app.app_context():+ db.session.rollback()+ users = [ids["me"], ids["other"]]+ rec_ids = [ids[k] for k in ("sync", "old", "plain", "theirs")]+ RecordingTag.query.filter(RecordingTag.recording_id.in_(rec_ids)).delete(synchronize_session=False)+ SharedRecordingState.query.filter(SharedRecordingState.recording_id.in_(rec_ids)).delete(synchronize_session=False)+ Recording.query.filter(Recording.id.in_(rec_ids)).delete(synchronize_session=False)+ Tag.query.filter(Tag.user_id.in_(users)).delete(synchronize_session=False)+ APIToken.query.filter(APIToken.user_id.in_(users)).delete(synchronize_session=False)+ User.query.filter(User.id.in_(users)).delete(synchronize_session=False)+ db.session.commit()+++def _search(world, who="me", **params):+ from urllib.parse import urlencode+ with app.test_client() as c:+ return c.get(f"/api/v1/search?{urlencode(params)}",+ headers={"Authorization": f"Bearer {world['tokens'][world[who]]}"})+++def _ok(world, **params):+ resp = _search(world, **params)+ assert resp.status_code == 200, resp.get_json()+ return resp.get_json()+++def test_a_word_spoken_once_is_found_with_time_and_speaker(world):+ body = _ok(world, q="zeppelin")+ assert body["mode_used"] == "keyword"+ hit = next(h for h in body["results"] if h["recording_id"] == world["old"])+ assert (hit["field"], hit["segment_index"], hit["start_time"], hit["end_time"], hit["speaker"]) == \+ ("transcript", 0, 12.5, 15.0, "Lee") # old key set: text/start/end+ plain = next(h for h in body["results"] if h["recording_id"] == world["plain"])+ assert plain["start_time"] is None and plain["segment_index"] is None+++def test_each_field_gives_its_own_hit(world):+ by_field = {}+ for h in _ok(world, q="budget freeze")["results"]: # best hit first+ if h["recording_id"] == world["sync"]:+ by_field.setdefault(h["field"], h)+ assert set(by_field) == {"transcript", "summary", "notes"}+ t = by_field["transcript"]+ assert (t["segment_index"], t["start_time"], t["speaker"]) == (1, 754.2, "Dana")+ assert t["text"][t["match_spans"][0][0]:t["match_spans"][0][1]].lower() in ("budget", "freeze")+ assert by_field["summary"]["text"] == "- The budget freeze ends in January."+ assert _ok(world, q="Weekly")["results"][0]["field"] == "title"+ assert {h["field"] for h in _ok(world, q="Omar")["results"] if h["recording_id"] == world["sync"]} >= {"participants"}+++def test_terms_are_anded_and_phrases_kept(world):+ assert _ok(world, q="budget zeppelin")["results"] == []+ assert _ok(world, q='"freeze applies"')["results"][0]["field"] == "transcript"+ assert _ok(world, q='"applies freeze"')["results"] == []+++def test_percent_and_underscore_are_literal(world):+ hits = _ok(world, q="100%")["results"]+ assert [h["speaker"] for h in hits] == ["Omar"]+ assert [h["speaker"] for h in _ok(world, q="clear_now")["results"]] == ["Omar"]+ assert _ok(world, q="clear%now")["results"] == []+++def test_json_keys_are_not_matches(world):+ assert _ok(world, q="sentence")["results"] == []+ assert _ok(world, q="start_time")["results"] == []+++def test_filters(world):+ assert {h["speaker"] for h in _ok(world, q="budget", speaker="dana")["results"]} == {"Dana"}+ assert _ok(world, q="budget", speaker="omar")["results"] == []+ assert {h["recording_id"] for h in _ok(world, q="zeppelin", recording_ids=str(world["plain"]))["results"]} == {world["plain"]}+ assert {h["recording_id"] for h in _ok(world, q="zeppelin", tag_id=world["tag"])["results"]} == {world["old"]}+ by_meeting = _ok(world, q="zeppelin", date_from="2025-09-01", date_to="2025-09-01")["results"]+ assert {h["recording_id"] for h in by_meeting} == {world["old"]}+ by_created = _ok(world, q="zeppelin", date_field="created_at", date_from="2026-01-05", date_to="2026-01-05")["results"]+ assert {h["recording_id"] for h in by_created} == {world["plain"]}+ assert {h["field"] for h in _ok(world, q="budget", fields="summary")["results"]} == {"summary"}+++def test_another_users_recording_never_appears(world):+ assert world["theirs"] not in {h["recording_id"] for h in _ok(world, q="budget")["results"]}+ theirs = _ok(world, who="other", q="budget")["results"]+ assert {h["recording_id"] for h in theirs} == {world["theirs"]}+++def test_limit_and_page(world):+ first = _ok(world, q="budget", limit=2)+ second = _ok(world, q="budget", limit=2, page=2)+ assert len(first["results"]) == 2 and first["has_more"] is True+ keys = lambda r: [(h["recording_id"], h["field"], h["text"]) for h in r["results"]]+ assert not set(keys(first)) & set(keys(second))++[email protected]("params", [{"q": "a"}, {"q": "x" * 501}, {"q": "budget", "mode": "fuzzy"},+ {"q": "budget", "fields": "title,body"}, {"q": "budget", "date_from": "soon"},+ {"q": "budget", "limit": 51}])+def test_bad_parameters(world, params):+ resp = _search(world, **params)+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"+++def test_semantic_mode(world):+ from src.services import search_v1+ with patch.object(search_v1, "semantic_available", return_value=False):+ resp = _search(world, q="budget", mode="semantic")+ assert resp.status_code == 409 and resp.get_json()["code"] == "semantic_unavailable"+ assert _ok(world, q="budget", mode="auto")["mode_used"] == "keyword"++ class Chunk:+ recording_id = world["sync"]+ start_time, end_time, speaker_name = 754.2, 761.0, "Dana"+ content = "So the budget freeze applies to travel only."++ @property+ def recording(self):+ return db.session.get(Recording, world["sync"])++ with patch.object(search_v1, "semantic_available", return_value=True), \+ patch("src.services.embeddings.semantic_search_chunks", return_value=[(Chunk(), 0.82)]) as sem:+ body = _ok(world, q="spending pause", mode="auto")+ assert body["mode_used"] == "semantic"+ assert body["results"][0]["score"] == 0.82 and body["results"][0]["speaker"] == "Dana"+ assert sem.call_args.args[2]["recording_ids"] and world["theirs"] not in sem.call_args.args[2]["recording_ids"]diff --git a/tests/test_notes_visibility.py b/tests/test_notes_visibility.pynew file mode 100644index 00000000..d4ec1826--- /dev/null+++ b/tests/test_notes_visibility.py@@ -0,0 +1,98 @@+"""Notes are per user in API v1 (mailr spec, open question 2).++The owner reads and writes the recording's notes. A user the recording is+shared with reads and writes only their own personal notes: never the+owner's, in the notes route, the detail, PATCH or search.++SHARED-DB: users, tokens, shares and the recording are removed afterwards.+"""++import json+import os+import secrets+import sys+from unittest.mock import patch++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import APIToken, InternalShare, Recording, SharedRecordingState, User+from src.utils.token_auth import hash_token+++def world():+ with app.app_context():+ s = secrets.token_hex(4)+ owner = User(username=f"nown_{s}", email=f"nown_{s}@local.test", password="x")+ guest = User(username=f"ngst_{s}", email=f"ngst_{s}@local.test", password="x")+ db.session.add_all([owner, guest])+ db.session.commit()+ rec = Recording(user_id=owner.id, title="Sync", status="COMPLETED", original_filename="s.wav",+ notes="OWNER PRIVATE: salary numbers", transcription="hello")+ db.session.add(rec)+ db.session.commit()+ db.session.add(InternalShare(recording_id=rec.id, owner_id=owner.id, shared_with_user_id=guest.id,+ can_edit=True))+ tokens = {}+ for who in (owner, guest):+ p = f"tok-{secrets.token_urlsafe(16)}"+ db.session.add(APIToken(user_id=who.id, token_hash=hash_token(p), name="n"))+ tokens[who.id] = p+ db.session.commit()+ ids = dict(owner=owner.id, guest=guest.id, rec=rec.id, tokens=tokens)+ with patch("src.app.ENABLE_INTERNAL_SHARING", True):+ yield ids+ with app.app_context():+ db.session.rollback()+ SharedRecordingState.query.filter_by(recording_id=ids["rec"]).delete()+ InternalShare.query.filter_by(recording_id=ids["rec"]).delete()+ Recording.query.filter_by(id=ids["rec"]).delete()+ APIToken.query.filter(APIToken.user_id.in_([ids["owner"], ids["guest"]])).delete(synchronize_session=False)+ User.query.filter(User.id.in_([ids["owner"], ids["guest"]])).delete(synchronize_session=False)+ db.session.commit()+++def _h(world, who):+ return {"Authorization": f"Bearer {world['tokens'][world[who]]}"}+++def _owner_notes(world):+ with app.app_context():+ return db.session.get(Recording, world["rec"]).notes+++def test_a_recipient_never_sees_the_owners_notes(world):+ with app.test_client() as c:+ assert c.get(f"/api/v1/recordings/{world['rec']}/notes", headers=_h(world, "guest")).get_json()["notes"] is None+ assert c.get(f"/api/v1/recordings/{world['rec']}", headers=_h(world, "guest")).get_json()["notes"] is None+ assert c.get(f"/api/v1/recordings/{world['rec']}/notes",+ headers=_h(world, "owner")).get_json()["notes"] == "OWNER PRIVATE: salary numbers"+++def test_a_recipient_writes_personal_notes(world):+ with app.test_client() as c:+ put = c.put(f"/api/v1/recordings/{world['rec']}/notes", json={"notes": "my own take"}, headers=_h(world, "guest"))+ assert put.status_code == 200 and put.get_json()["notes"] == "my own take"+ patched = c.patch(f"/api/v1/recordings/{world['rec']}", json={"notes": "edited take"}, headers=_h(world, "guest"))+ assert patched.get_json()["recording"]["notes"] == "edited take"+ assert c.get(f"/api/v1/recordings/{world['rec']}/notes", headers=_h(world, "guest")).get_json()["notes"] == "edited take"+ assert _owner_notes(world) == "OWNER PRIVATE: salary numbers"+++def test_the_owner_still_writes_the_recording_notes(world):+ with app.test_client() as c:+ assert c.put(f"/api/v1/recordings/{world['rec']}/notes", json={"notes": "new"},+ headers=_h(world, "owner")).status_code == 200+ assert _owner_notes(world) == "new"+++def test_search_matches_only_the_notes_the_caller_can_see(world):+ from src.models import User as U+ from src.services.search_v1 import keyword_search+ with app.app_context():+ owner = db.session.get(U, world["owner"])+ hits, _ = keyword_search(owner, "salary", fields=("notes",))+ assert [h["field"] for h in hits] == ["notes"]