findakin 2.0.0a1__tar.gz

findakin-2.0.0a1/.gitignore

@@ -0,0 +1,231 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+#lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Production secrets
+.env.production
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# DO App Platform
+.do/
+
+stuff/*
+# OS noise / local data archives
+.DS_Store
+*.zip
+
+# Library tooling / local stores
+.venv/
+*.egg-info/
+/dist/
+/build/
+website/dist/
+website/node_modules/
+*.lance/

findakin-2.0.0a1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to Findakin. The format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [2.0.0a1] — 2026-10-22
+
+Findakin becomes a **local Python library** on LanceDB. The hosted web application (v1) is
+archived under the git tag `v1-webapp` and the Digital Ocean deployment is retired.
+
+### Added
+- `findakin.Store`: a LanceDB directory holding `spectra` (metadata, content-hash ids),
+  `flux_native` (wavelength / flux arrays), one `emb__<encoder>` table per encoder and the
+  `encoders` registry.
+- `Store.ingest_folder()` with content deduplication, header metadata extraction tolerant to
+  BeSS / ISIS / specINTI / Demetra dialects, and `series_from` = object | night | folder.
+- `Store.embed()` over every spectro-kernel strategy (`naive`, `dct`, `multiscale_dct`,
+  `log_lambda`, `band_power`, `continuum_subtracted`, `lick`, `wavelets`, `pretrained`,
+  `remote`); several encoders coexist and are idempotent.
+- `Store.vectors()` (numpy matrix for population analyses), `Store.neighbours()` (k-NN by id,
+  by file or by vector, with SQL pre-filters), `Store.embed_file()`.
+- `findakin` CLI: `info`, `ingest`, `embed`, `encoders`, `search`.
+- `findakin.analysis` (clustering, anomalies, projection), `findakin.benchmark`,
+  `findakin.align` (common λ grids) and `findakin.connectors` (SSAP, STAROS) carried over
+  from v1 as pure library modules.
+- Landing page in `website/` (findakin.lelain.net), deployable with Netlify.
+- Release workflow publishing to PyPI through a Trusted Publisher.
+
+### Removed
+- FastAPI backend, MongoDB models, Clerk authentication, Cloudflare R2 storage, Qdrant /
+  ChromaDB services, job queue, React application, Docker / Digital Ocean deployment files.

findakin-2.0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthieu Le Lain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

findakin-2.0.0a1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: findakin
+Version: 2.0.0a1
+Summary: Population-level questions on collections of astronomical spectra: similarity search, clustering, anomalies, trajectories and encoder benchmarks on a local LanceDB store, with embeddings from spectro-kernel.
+Project-URL: Homepage, https://findakin.lelain.net
+Project-URL: Repository, https://github.com/matthieulel/findakin
+Project-URL: Documentation, https://github.com/matthieulel/findakin/tree/main/docs
+Project-URL: Changelog, https://github.com/matthieulel/findakin/blob/main/CHANGELOG.md
+Author: matthieulel
+License: MIT
+License-File: LICENSE
+Keywords: anomaly-detection,astronomy,clustering,embeddings,lancedb,mcp,similarity-search,spectra,spectroscopy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: astropy>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: lancedb>=0.15
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: pydantic>=2.6
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.12
+Requires-Dist: spectro-kernel>=0.8
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: hdbscan>=0.8.38; extra == 'all'
+Requires-Dist: plotly>=5.20; extra == 'all'
+Requires-Dist: pyvo>=1.5; extra == 'all'
+Requires-Dist: umap-learn>=0.5.6; extra == 'all'
+Provides-Extra: analysis
+Requires-Dist: hdbscan>=0.8.38; extra == 'analysis'
+Requires-Dist: umap-learn>=0.5.6; extra == 'analysis'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: encoders
+Requires-Dist: torch>=2.2; extra == 'encoders'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == 'mcp'
+Provides-Extra: viz
+Requires-Dist: plotly>=5.20; extra == 'viz'
+Provides-Extra: vo
+Requires-Dist: pyvo>=1.5; extra == 'vo'
+Description-Content-Type: text/markdown
+
+# Findakin
+
+**Find a kin for every spectrum.**
+
+Findakin answers *population* questions about collections of astronomical spectra:
+which look alike, what structure they form, which stand out, which changed in time, and
+which representation (encoder) is the most physical. It is a local Python library built on
+[spectro-kernel](https://github.com/matthieulel/spectro-kernel) (one spectrum → one vector)
+and [LanceDB](https://lancedb.com) (an embedded, versioned, columnar store with a vector
+index). No server, no account: your spectra stay on your disk.
+
+> **Status: v2 alpha.** The hosted web application (v1, FastAPI + MongoDB + Qdrant + React)
+> is archived under the git tag `v1-webapp`. The rewrite into a library is documented in
+> [docs/roadmap/findakin-v2-local-first.md](docs/roadmap/findakin-v2-local-first.md).
+> Landing page: [findakin.lelain.net](https://findakin.lelain.net).
+
+```
+spectro-kernel  = algorithms on ONE spectrum   (embeddings, I/O, lines, RV, reduction…)
+Findakin        = questions on MANY spectra    (index, neighbours, clusters, anomalies,
+                                                trajectories, encoder benchmarks)
+```
+
+## Install
+
+```bash
+pip install findakin                 # core: store, ingestion, kernel recipes, k-NN
+pip install "findakin[analysis]"     # + UMAP projection, HDBSCAN clustering
+pip install "findakin[vo]"           # + SSAP / Virtual Observatory connectors
+pip install "findakin[encoders]"     # + local PyTorch encoders (spectro-kernel embed_pretrained)
+```
+
+Python ≥ 3.11.
+
+## Quick start
+
+```python
+from findakin import Store
+
+st = Store.open("~/findakin/store")                 # a directory; created if missing
+
+# 1. ingest — FITS (BeSS / ISIS / specINTI / Demetra dialects), CSV, JSON, TXT.
+#    Spectra are deduplicated by content; metadata (object, time, instrument,
+#    observer, site, resolution, coverage) is extracted from the headers.
+report = st.ingest_folder("~/spectra/alphadra", source="staros", tags=["campaign:alphadra"])
+print(report)                                       # 1012 files → 987 added, 25 duplicates, 0 errors
+
+# 2. embed — any spectro-kernel strategy; several encoders coexist for the same spectra
+enc = st.embed(strategy="dct", dim=256, norm_method="z_score")   # → 'dct:v1:256:nogrid:z_score'
+enc_ll = st.embed(strategy="log_lambda", dim=256)                 # Doppler-robust recipe
+# tip: with min_max the continuum term dominates the vector and every pair scores ≈ 0.99;
+# z_score (zero mean) or continuum_subtracted let the lines drive the similarity.
+
+# 3. ask
+st.neighbours("~/spectra/new_alfdra.fits", k=10, encoder=enc)          # k-NN by file…
+st.neighbours(some_id, k=10, encoder=enc, where="observer = 'mlelain'")  # …or by id, filtered
+ids, X = st.vectors(enc, where="series_id = 'alf dra'")                 # numpy matrix for analysis
+
+from findakin.analysis import cluster_embeddings, detect_anomalies, project_embeddings
+labels = cluster_embeddings(X, method="hdbscan")
+outliers = detect_anomalies(X, method="lof", contamination=0.02)
+xy = project_embeddings(X, method="umap")
+```
+
+Same verbs on the command line:
+
+```bash
+findakin ingest ~/spectra/alphadra --source staros --tag campaign:alphadra
+findakin embed --strategy dct --dim 256
+findakin search ~/spectra/new_alfdra.fits -k 10
+findakin info
+```
+
+## What is in the store
+
+A LanceDB directory, versioned, rebuildable from your files:
+
+| Table | Content |
+|---|---|
+| `spectra` | one row per spectrum: `id` (content hash), `source`, `object`, `series_id`, `t_mjd`, `instrument`, `observer`, `site`, `resolution`, `wl_min/wl_max`, `file_uri`, `tags`, raw header (JSON) |
+| `flux_native` | the native wavelength / flux arrays (re-embed with a new encoder without re-reading files) |
+| `emb__<encoder>` | one table per encoder: `(id, vector, provenance)` — `encoder_id = strategy:model_version:dim:grid:norm` |
+| `encoders` | the encoder registry (config, dimension) |
+
+`series_id` groups spectra that form a trajectory in time: an object followed over epochs
+(default), a night of sky spectra (`series_from="night"`, e.g. aurorae), or a folder.
+
+## Roadmap (short)
+
+Phase 0 — store, ingestion, kernel encoders, k-NN, CLI ✅ · Phase 1 — common λ grids
+(inter-instrument alignment), `flux__<grid>` tables, vector indexes · Phase 2 — named
+populations, clusters / anomalies / projections stored as results, **trajectory anomalies**,
+Plotly notebook helpers · Phase 3 — learned encoders registry, encoder benchmark with an
+*instrument-leakage* score · Phase 4 — `findakin-mcp` over the store · Phase 5 — thin HTTP
+façade for STAROS / SpecRelay. Details: [docs/roadmap/](docs/roadmap/).
+
+## Development
+
+```bash
+uv venv .venv --python 3.12 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest -q
+ruff check src tests
+```
+
+The landing page lives in [website/](website/) (Vite + React, deployed separately). Project
+notes and decisions: [docs/](docs/) and [stuff/](stuff/).
+
+## License
+
+MIT — © 2026 Matthieu Le Lain.

findakin-2.0.0a1/README.md

@@ -0,0 +1,110 @@
+# Findakin
+
+**Find a kin for every spectrum.**
+
+Findakin answers *population* questions about collections of astronomical spectra:
+which look alike, what structure they form, which stand out, which changed in time, and
+which representation (encoder) is the most physical. It is a local Python library built on
+[spectro-kernel](https://github.com/matthieulel/spectro-kernel) (one spectrum → one vector)
+and [LanceDB](https://lancedb.com) (an embedded, versioned, columnar store with a vector
+index). No server, no account: your spectra stay on your disk.
+
+> **Status: v2 alpha.** The hosted web application (v1, FastAPI + MongoDB + Qdrant + React)
+> is archived under the git tag `v1-webapp`. The rewrite into a library is documented in
+> [docs/roadmap/findakin-v2-local-first.md](docs/roadmap/findakin-v2-local-first.md).
+> Landing page: [findakin.lelain.net](https://findakin.lelain.net).
+
+```
+spectro-kernel  = algorithms on ONE spectrum   (embeddings, I/O, lines, RV, reduction…)
+Findakin        = questions on MANY spectra    (index, neighbours, clusters, anomalies,
+                                                trajectories, encoder benchmarks)
+```
+
+## Install
+
+```bash
+pip install findakin                 # core: store, ingestion, kernel recipes, k-NN
+pip install "findakin[analysis]"     # + UMAP projection, HDBSCAN clustering
+pip install "findakin[vo]"           # + SSAP / Virtual Observatory connectors
+pip install "findakin[encoders]"     # + local PyTorch encoders (spectro-kernel embed_pretrained)
+```
+
+Python ≥ 3.11.
+
+## Quick start
+
+```python
+from findakin import Store
+
+st = Store.open("~/findakin/store")                 # a directory; created if missing
+
+# 1. ingest — FITS (BeSS / ISIS / specINTI / Demetra dialects), CSV, JSON, TXT.
+#    Spectra are deduplicated by content; metadata (object, time, instrument,
+#    observer, site, resolution, coverage) is extracted from the headers.
+report = st.ingest_folder("~/spectra/alphadra", source="staros", tags=["campaign:alphadra"])
+print(report)                                       # 1012 files → 987 added, 25 duplicates, 0 errors
+
+# 2. embed — any spectro-kernel strategy; several encoders coexist for the same spectra
+enc = st.embed(strategy="dct", dim=256, norm_method="z_score")   # → 'dct:v1:256:nogrid:z_score'
+enc_ll = st.embed(strategy="log_lambda", dim=256)                 # Doppler-robust recipe
+# tip: with min_max the continuum term dominates the vector and every pair scores ≈ 0.99;
+# z_score (zero mean) or continuum_subtracted let the lines drive the similarity.
+
+# 3. ask
+st.neighbours("~/spectra/new_alfdra.fits", k=10, encoder=enc)          # k-NN by file…
+st.neighbours(some_id, k=10, encoder=enc, where="observer = 'mlelain'")  # …or by id, filtered
+ids, X = st.vectors(enc, where="series_id = 'alf dra'")                 # numpy matrix for analysis
+
+from findakin.analysis import cluster_embeddings, detect_anomalies, project_embeddings
+labels = cluster_embeddings(X, method="hdbscan")
+outliers = detect_anomalies(X, method="lof", contamination=0.02)
+xy = project_embeddings(X, method="umap")
+```
+
+Same verbs on the command line:
+
+```bash
+findakin ingest ~/spectra/alphadra --source staros --tag campaign:alphadra
+findakin embed --strategy dct --dim 256
+findakin search ~/spectra/new_alfdra.fits -k 10
+findakin info
+```
+
+## What is in the store
+
+A LanceDB directory, versioned, rebuildable from your files:
+
+| Table | Content |
+|---|---|
+| `spectra` | one row per spectrum: `id` (content hash), `source`, `object`, `series_id`, `t_mjd`, `instrument`, `observer`, `site`, `resolution`, `wl_min/wl_max`, `file_uri`, `tags`, raw header (JSON) |
+| `flux_native` | the native wavelength / flux arrays (re-embed with a new encoder without re-reading files) |
+| `emb__<encoder>` | one table per encoder: `(id, vector, provenance)` — `encoder_id = strategy:model_version:dim:grid:norm` |
+| `encoders` | the encoder registry (config, dimension) |
+
+`series_id` groups spectra that form a trajectory in time: an object followed over epochs
+(default), a night of sky spectra (`series_from="night"`, e.g. aurorae), or a folder.
+
+## Roadmap (short)
+
+Phase 0 — store, ingestion, kernel encoders, k-NN, CLI ✅ · Phase 1 — common λ grids
+(inter-instrument alignment), `flux__<grid>` tables, vector indexes · Phase 2 — named
+populations, clusters / anomalies / projections stored as results, **trajectory anomalies**,
+Plotly notebook helpers · Phase 3 — learned encoders registry, encoder benchmark with an
+*instrument-leakage* score · Phase 4 — `findakin-mcp` over the store · Phase 5 — thin HTTP
+façade for STAROS / SpecRelay. Details: [docs/roadmap/](docs/roadmap/).
+
+## Development
+
+```bash
+uv venv .venv --python 3.12 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest -q
+ruff check src tests
+```
+
+The landing page lives in [website/](website/) (Vite + React, deployed separately). Project
+notes and decisions: [docs/](docs/) and [stuff/](stuff/).
+
+## License
+
+MIT — © 2026 Matthieu Le Lain.

findakin-2.0.0a1/docs/README.md

@@ -0,0 +1,35 @@
+# 📖 Documentation Findakin
+
+> **Bibliothèque Python locale** de recherche de similarité et d'analyse de population sur des
+> spectres astronomiques, adossée à spectro-kernel (un spectre → un vecteur) et LanceDB (store
+> local versionné). Le code de l'application web v1 est archivé sous le tag git `v1-webapp`.
+
+---
+
+## 🗂️ Structure
+
+```
+docs/
+├── roadmap/                         # 🗺️ Décisions et évolutions
+│   ├── findakin-v2-local-first.md   # ★ La décision d'architecture v2 (lib + LanceDB) et le plan
+│   ├── kernel-vs-findakin.md        # ★ Frontière spectro-kernel ↔ Findakin
+│   ├── vision.md, backlog.md, …     # Réflexions antérieures (époque SaaS, à lire comme historique)
+│
+└── archive/
+    └── v1-webapp/                   # 📦 Documentation de l'application web v1 (API REST, infra cloud)
+        ├── reference/
+        └── app_description.md
+```
+
+---
+
+## 🚀 Démarrage rapide
+
+→ Le [README](../README.md) à la racine : installation, `Store`, CLI.
+→ [roadmap/findakin-v2-local-first.md](roadmap/findakin-v2-local-first.md) : pourquoi cette forme, tables du store, plan par phases.
+
+---
+
+## 📅 Dernière mise à jour
+
+28 janvier 2026

findakin-2.0.0a1/docs/archive/v1-webapp/reference/README.md

@@ -0,0 +1,60 @@
+# 📚 Documentation Findakin
+
+> **Documentation technique de référence**
+
+---
+
+## ⚠️ Important : Findakin n'est pas une solution d'archivage
+
+**Findakin est un service d'indexation vectorielle pour la recherche par similarité**, pas un système d'archivage ou de sauvegarde de spectres. 
+
+- Les spectres peuvent être supprimés, réindexés ou modifiés à tout moment
+- Le service conserve une copie des spectres pour l'affichage, mais ce n'est pas sa fonction principale
+- Les spectres sont stockés de manière optimisée pour la recherche, pas pour la préservation à long terme
+- **Conservez toujours vos fichiers originaux dans un système de sauvegarde approprié** (serveur de fichiers, système de versioning, archive institutionnelle, etc.)
+
+Findakin est conçu pour :
+- ✅ Rechercher rapidement des spectres similaires dans de grandes collections
+- ✅ Expérimenter avec différentes stratégies de vectorisation
+- ✅ Analyser les relations entre spectres via leurs embeddings
+- ❌ **Pas** pour remplacer vos systèmes d'archivage classiques
+
+---
+
+## 📖 Contenu
+
+Cette documentation décrit l'état actuel d'Findakin et évolue avec chaque nouvelle fonctionnalité implémentée.
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](architecture.md) | Stack technique, composants, décisions d'architecture (ADRs) |
+| [Concepts](concepts.md) | Embeddings, vecteurs, similarité, stratégies |
+| [API](api.md) | Documentation complète de l'API REST v1 |
+| [Infrastructure](infrastructure.md) | Services cloud, Docker, déploiement |
+
+---
+
+## 🏗️ Architecture en bref
+
+```
+Frontend (React)  →  API (FastAPI)  →  Worker de jobs (file MongoDB)
+                          ↓
+            ┌─────────────┼─────────────┐
+            ↓             ↓             ↓
+      MongoDB Atlas   Qdrant Cloud   Cloudflare R2
+      (métadonnées)    (vecteurs)     (fichiers)
+```
+
+---
+
+## 🔗 Liens rapides
+
+- **API Docs** : `/docs` (Swagger UI)
+- **Roadmap** : [../roadmap/](../roadmap/)
+- **Archive** : [../archive/](../archive/)
+
+---
+
+## 📅 Dernière mise à jour
+
+28 janvier 2026