If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mazzzystar/Queryable shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 6w ago
• 7 active contributors
• MIT licensed
• ⚠ Single-maintainer risk — top contributor 87% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mazzzystar/Queryable repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mazzzystar/Queryable.

What it runs against: a local clone of mazzzystar/Queryable — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mazzzystar/Queryable | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 72 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mazzzystar/Queryable. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mazzzystar/Queryable.git
#   cd Queryable
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mazzzystar/Queryable and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mazzzystar/Queryable(\\.git)?\\b" \\
  && ok "origin remote is mazzzystar/Queryable" \\
  || miss "origin remote is not mazzzystar/Queryable (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Queryable/Queryable/QueryableApp.swift" \\
  && ok "Queryable/Queryable/QueryableApp.swift" \\
  || miss "missing critical file: Queryable/Queryable/QueryableApp.swift"
test -f "Queryable/Queryable/ViewModel/PhotoSearcher.swift" \\
  && ok "Queryable/Queryable/ViewModel/PhotoSearcher.swift" \\
  || miss "missing critical file: Queryable/Queryable/ViewModel/PhotoSearcher.swift"
test -f "Queryable/Queryable/Model/PhotoSearchModel.swift" \\
  && ok "Queryable/Queryable/Model/PhotoSearchModel.swift" \\
  || miss "missing critical file: Queryable/Queryable/Model/PhotoSearchModel.swift"
test -f "Queryable/Queryable/CLIP/ImgEncoder.swift" \\
  && ok "Queryable/Queryable/CLIP/ImgEncoder.swift" \\
  || miss "missing critical file: Queryable/Queryable/CLIP/ImgEncoder.swift"
test -f "Queryable/Queryable/CLIP/TextEncoder.swift" \\
  && ok "Queryable/Queryable/CLIP/TextEncoder.swift" \\
  || miss "missing critical file: Queryable/Queryable/CLIP/TextEncoder.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 72 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~42d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mazzzystar/Queryable"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Queryable is an iOS app that performs on-device semantic photo search using Apple's MobileCLIP model (previously OpenAI's CLIP). Users type natural language queries like 'a brown dog sitting on a bench' to search their photo library without uploading images to any server. The app encodes all photos into vector embeddings once, then compares text query embeddings against those vectors to rank and return matching photos. Single-app Xcode project at Queryable/Queryable.xcodeproj with two core ML modules in Queryable/Queryable/CLIP/: ImgEncoder.swift (processes photos into vectors) and TextEncoder.swift (encodes text queries). Asset management via Assets.xcassets contains app icons and UI images. Model files (.mlmodelc format) are downloaded separately from Google Drive rather than versioned in git.

iOS users who want privacy-preserving photo search with natural language capabilities, and iOS developers building on-device ML apps who need reference implementations for running vision-language models (CLIP/MobileCLIP) in CoreML format on iPhones.

Production-ready with active maintenance. The app is published on the App Store (id 1661598353) and the codebase was updated in 2024 to support MobileCLIP. However, the GitHub repo shows sparse recent commits—most active work happened 2022–2024. No visible automated testing or CI pipeline in the file structure suggests development velocity has normalized post-launch.

Low risk for production use, but moderate risk for active development: the project is single-maintainer (mazzzystar) with infrequent commits, no visible test suite or GitHub Actions CI, and heavy reliance on two external ML models (OpenAI CLIP and Apple MobileCLIP) whose versions must be manually managed. The Jupyter notebooks for model conversion (PyTorch2CoreML.ipynb) are critical but lack documentation on dependencies or reproducibility steps.

The major recent change (2024-09-01) was adopting Apple's MobileCLIP model (s2 variant) as the default, replacing OpenAI's CLIP for better on-device performance. Pre-converted model files are hosted on Google Drive. No visible open PRs or issues in the file listing; development appears to be maintenance mode post-launch.

Clone the repo: git clone https://github.com/mazzzystar/Queryable.git && cd Queryable/Queryable. Open the Xcode project: open Queryable.xcodeproj. Download pre-converted TextEncoder_mobileCLIP_s2.mlmodelc and ImageEncoder_mobileCLIP_s2.mlmodelc from the Google Drive folder (link in README) and add them to the Xcode project. Build and run on an iOS device or simulator with Xcode.

Daily commands: Open Xcode project file at Queryable/Queryable.xcodeproj, ensure models are in the correct bundle directory, select a physical iOS device or simulator target, press Cmd+R to build and run. No npm/pip environment setup needed once models are placed.

• Queryable/Queryable/QueryableApp.swift — App entry point and root view initialization; essential for understanding the application lifecycle and navigation structure.
• Queryable/Queryable/ViewModel/PhotoSearcher.swift — Core search orchestration logic that coordinates CLIP embedding generation, similarity search, and result filtering.
• Queryable/Queryable/Model/PhotoSearchModel.swift — Central model management for loading CoreML CLIP/MobileCLIP models and handling inference execution.
• Queryable/Queryable/CLIP/ImgEncoder.swift — Image encoding pipeline using CoreML; transforms photos into embeddings for similarity comparison.
• Queryable/Queryable/CLIP/TextEncoder.swift — Text encoding pipeline converting natural language queries to embeddings using BPE tokenizer; enables semantic search.
• Queryable/Queryable/Model/EmbeddingStore.swift — Persistence layer for pre-computed embeddings; critical for avoiding re-computation and enabling fast search.
• Queryable/Queryable/PhotoHelper/PhotoLibrary.swift — Photos framework wrapper handling photo access, batch processing, and asset collection management.

Add a new search filter or result sorting option

1. Add filter state property to PhotoSearcher ViewModel (Queryable/Queryable/ViewModel/PhotoSearcher.swift)
2. Implement filter logic in GPUSimilaritySearch before returning results (Queryable/Queryable/Model/GPUSimilaritySearch.swift)
3. Add filter UI control to SearchBarView or SearchResultsView (Queryable/Queryable/View/SearchBarView.swift)

Support a new CLIP variant or model (e.g., ViT-L instead of ViT-B)

1. Generate new CoreML model using PyTorch2CoreML notebook (PyTorch2CoreML.ipynb)
2. Place new model in CoreMLModels and update PhotoSearchModel to reference it (Queryable/Queryable/Model/PhotoSearchModel.swift)
3. Update tokenizer files if needed (vocab.json, merges.txt) (Queryable/Queryable/CoreMLModels/vocab.json)
4. Test inference in ImgEncoder and TextEncoder with new model dimensions (Queryable/Queryable/CLIP/ImgEncoder.swift)

Add a new UI view or tab (e.g., advanced search options)

1. Create new SwiftUI view file in View/ directory (e.g., AdvancedSearchView.swift) (Queryable/Queryable/View/SearchResultsView.swift)
2. Add navigation case to ContentView for the new tab/sheet (Queryable/Queryable/View/ContentView.swift)
3. Pass required ViewModel state (e.g., PhotoSearcher) to the new view (Queryable/Queryable/ViewModel/PhotoSearcher.swift)
4. Add localized strings for new UI labels to language files (Queryable/en.lproj/Localizable.strings)

• CoreML + Metal (GPU) — Enables fast on-device inference of CLIP/MobileCLIP models without network dependency; GPU acceleration via Metal for similarity search speeds up results across thousands of photos.
• SwiftUI — Native iOS framework for responsive UI with state binding; simplifies view management across iPhone and Mac (Catalyst) targets.
• Photos Framework (PHPhotoLibrary) — Standard iOS API for accessing user's photo library with privacy controls; only way to read Photos album without duplicating data.
• BPE Tokenizer (vocab.json + merges.txt) — OpenAI CLIP's tokenization method; must match training to preserve semantic space alignment for text encoding.
• Core Data / SwiftData — Persistent storage of photo metadata and pre-computed embeddings across app sessions; avoids re-indexing on every launch.

• Pre-compute and cache all photo embeddings on first app run

  • Why: Enables instant sub-second search response times; avoids latency from on-the-fly encoding.
  • Consequence: Initial indexing can take minutes for large photo libraries (10k+ photos); requires local storage (~50MB-200MB for embeddings depending on model size).

• Offline-only processing (no cloud backend)

  • Why: User privacy guaranteed; no photos or embeddings leave the device.
  • Consequence: Cannot share search results; no cross-device sync; updates to CLIP model require app update and re-indexing.

• Support MobileCLIP (smaller) over standard CLIP

  • Why: Fits on-device within memory and storage constraints; faster inference for real-time search.
  • Consequence: Slightly lower semantic accuracy than larger ViT-L/14 models; may miss nuanced multi-object queries.

• Use GPU similarity search via Metal Performance Shaders

  • Why: Parallelizes cosine similarity computation across thousands of embeddings.
  • Consequence: Complex SIMD code; potential precision issues with float32 normalization; not portable to Android without Vulkan rewrite.

• Does not support real-time indexing of newly captured photos (requires manual re-index)
• Does not provide cloud backup or cross-device sync of embeddings or search

1. Model files (.mlmodelc) are not in git—you must manually download them from Google Drive and add them to the Xcode project bundle, or the app will crash at inference. 2. The Jupyter notebooks require PyTorch, CoreMLTools, and Hugging Face transformers libraries, but their pinned versions are not documented; running them without correct environment setup will fail. 3. iOS photo library access requires Privacy-Photos NSLocalizedDescription in Info.plist, likely set in project.pbxproj but not visible in the file listing. 4. MobileCLIP s2 variant is currently the default, but code may have hardcoded references to model input/output shapes (e.g., image 224×224 pixels, embedding dimension 256)—switching models requires careful signature matching.

• Contrastive Vision-Language Pre-training (CLIP) — CLIP/MobileCLIP learns aligned embeddings for images and text by contrasting positive pairs; Queryable relies on this to map a text query and a photo into the same vector space for similarity matching
• Cosine Similarity for Vector Ranking — Queryable ranks photos by computing dot product (or cosine distance) between the query embedding and each photo embedding; this is the core search metric
• CoreML Model Quantization & Conversion — The Jupyter notebooks convert PyTorch/ONNX models to Apple's CoreML .mlmodelc format, often with quantization (float16, int8) to fit on-device and run efficiently on iOS neural engine
• On-Device Inference (Edge ML) — Queryable runs all ML entirely on-device with no cloud backend, protecting user privacy; this constrains model size and compute budget compared to server-side search
• Embedding Indexing & Retrieval — Queryable pre-encodes all photos into fixed-size vectors (embeddings) and stores them; at query time, it compares one new text embedding against thousands of cached photo embeddings to find top-K matches
• Natural Language Understanding via Embeddings — The text encoder converts free-form user queries like 'a brown dog sitting on a bench' into a 256-dimensional vector; CLIP's pretraining makes semantically similar queries map to nearby points in embedding space
• iOS Photo Library Access & Privacy — The app must request PHPhotoLibrary permissions and batch-process user photos without uploading them; this requires careful async image loading and memory management on-device

• openai/CLIP — Original contrastive vision-language model that Queryable implements; understanding CLIP's architecture (image/text encoders, cosine similarity ranking) is essential to the app's search algorithm
• apple/ml-mobileclip — Official Apple MobileCLIP implementation; the model Queryable now defaults to. Contains model weights, training details, and benchmark comparisons against CLIP that explain the efficiency vs. accuracy trade-off
• greyovo/PicQuery — Android port of Queryable by community contributor greyovo; shows how the same semantic search concept translates to Android using TensorFlow Lite instead of CoreML
• facebook/faiss — Vector similarity search library; if Queryable were to scale to millions of embeddings, FAISS approximate nearest neighbor algorithms would replace naive cosine similarity
• huggingface/transformers — Hugging Face library used in PyTorch2CoreML-HuggingFace.ipynb to load pretrained CLIP and MobileCLIP weights before exporting to CoreML format

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for BPETokenizer.swift and tokenization pipeline

The CLIP/Tokenizer directory contains critical BPETokenizer.swift and BPETokenizer+Reading.swift files with no visible test coverage. Since tokenization is fundamental to text embedding quality in the CLIP pipeline, adding XCTest cases would catch regressions in vocab.json/merges.txt loading and token encoding logic. This directly impacts search accuracy.

• [ ] Create QueryableTests target if missing, or add to existing test target
• [ ] Add XCTest cases in Tests/ for BPETokenizer initialization with vocab.json and merges.txt
• [ ] Add test cases for edge cases: empty strings, special characters, unknown tokens
• [ ] Add integration test verifying tokenizer output matches expected embedding dimensions for TextEncoder.swift
• [ ] Run tests in CI on PR merge (separate PR after this one)

Refactor GPUSimilaritySearch.swift and add performance benchmarks

GPUSimilaritySearch.swift likely contains the Metal-accelerated vector similarity computation, which is performance-critical for real-time search. The file appears monolithic with no visible companion benchmark or performance test. Adding benchmarks would help contributors optimize embedding search without regression.

• [ ] Create QueryableBenchmarks target (XCTest with measure blocks)
• [ ] Extract Metal setup/dispatch logic from GPUSimilaritySearch into separate MetalComputeManager.swift for testability
• [ ] Add benchmark test: similarity search on 1K/10K/100K embeddings, measuring latency
• [ ] Document expected performance targets in comments (e.g., '< 100ms for 10K embeddings on A15')
• [ ] Add benchmark results to a PERFORMANCE.md file for visibility

Create PhotoHelper integration tests and add PhotoLibrary error handling documentation

The PhotoHelper directory contains multiple models (PhotoLibrary.swift, PhotoCollection.swift, PhotoAsset.swift, PhotoAssetCollection.swift, CachedImageManager.swift) that interact with the Photos framework, but error cases (permission denial, inaccessible albums, concurrent modifications) are not documented. New contributors lack guidance on expected behavior when permissions fail or models become inconsistent.

• [ ] Add integration test file: Tests/PhotoHelperIntegrationTests.swift
• [ ] Create test cases for PhotoLibrary permission scenarios (authorized, denied, restricted)
• [ ] Add test for CachedImageManager cache invalidation on library changes
• [ ] Document error handling in PhotoLibrary.swift with code comments explaining each NSError case
• [ ] Create PHOTO_HELPER.md documenting the data model relationships and error states for contributors

• Add unit tests for ImgEncoder.swift and TextEncoder.swift to verify CoreML inference outputs match expected vector dimensions (e.g., embedding size 256 for MobileCLIP s2) and handle edge cases like empty images or very long text queries.
• Create automated notebook setup guide: document the exact Python environment (pyenv, conda, or venv), pinned library versions, and step-by-step instructions to regenerate .mlmodelc files from the Jupyter notebooks, so maintainers can reproducibly export future model variants.
• Add Xcode CI/CD pipeline (GitHub Actions or similar) to automatically build the iOS target on each commit, catch compilation errors early, and optionally run UI tests on simulators to prevent regressions when updating Swift dependencies or CoreML frameworks.

The Queryable iOS application demonstrates a reasonable security posture with offline-first design protecting user privacy. However, several areas require attention: (1) Local data storage encryption for embeddings and photo metadata should be explicitly verified, (2) Email functionality should use secure protocols with proper consent handling, (3) External integrations (Discord, GitHub, Twitter) need URL validation and certificate pinning, (4) Dependency management practices should be documented and regularly audited. The absence of provided dependency files prevents comprehensive vulnerability scanning. The application's architecture is generally secure for offline photo search, but implementation details around encryption, key management, and third-party integrations need verification.

• Medium · Potential Hardcoded Model Paths and Dependencies — Queryable/Queryable/CoreMLModels/. The codebase contains references to CoreML models (merges.txt, vocab.json) that are bundled directly in the application. While this is necessary for offline functionality, ensure that model files are not containing any sensitive configuration or API endpoints. Fix: Verify that CoreML model files and tokenizer resources do not contain hardcoded credentials, API keys, or sensitive endpoints. Implement code signing and integrity checks for critical model files.
• Medium · Local Data Storage Security — Queryable/Queryable/Model/EmbeddingStore.swift, Queryable/Queryable/PhotoHelper/DataModel.swift. The EmbeddingStore.swift and DataModel.swift files likely handle persistent storage of photo embeddings and metadata. If not properly encrypted, this could expose sensitive user data (photo embeddings and library structure) if the device is compromised. Fix: Implement encrypted data storage using iOS Keychain for sensitive metadata and Core Data encryption for embedding storage. Ensure proper file protection classes are applied to stored data.
• Medium · Email Helper Implementation Review Needed — Queryable/Queryable/View/ConfigPageViews/EmailHelper.swift. The EmailHelper.swift file in ConfigPageViews suggests email functionality for feedback. Email transmission could expose user data or feedback content if not properly secured. Fix: Verify that email functionality uses secure protocols (TLS/SSL). Ensure user data in feedback is anonymized or explicitly consented to. Review for any sensitive information being transmitted.
• Low · Dependency Management Transparency — Project root configuration files. No package dependency file (Podfile, Package.swift, or CocoaPods) was provided for analysis. The project may have external dependencies that could contain vulnerabilities. Fix: Maintain an updated dependency manifest. Regularly run security audits on dependencies using tools like CocoaPods vulnerabilities checker or Swift Package Manager security scanning.
• Low · Third-Party Service Integration Points — Queryable/Queryable/Assets.xcassets/ (DiscordIcon, GitHub, TwitterAvatar). The presence of Discord, GitHub, and Twitter links in Assets suggests potential external integrations or social sharing. External links could be vectors for phishing or man-in-the-middle attacks if not properly validated. Fix: Implement URL validation and SSL certificate pinning for any external service integrations. Use universal links with Apple's site association file for web-based links.
• Low · GPU Similarity Search Implementation — Queryable/Queryable/Model/GPUSimilaritySearch.swift. The GPUSimilaritySearch.swift component performs computational operations on embeddings. Potential side-channel attacks or information leakage through timing analysis could expose embedding patterns. Fix: Review GPU memory management to prevent data leakage. Implement secure erasure of intermediate computation results. Consider constant-time operations for sensitive comparisons.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.