yamcps-docs 0.1.0__tar.gz

yamcps_docs-0.1.0/.github/workflows/verify_release.py

@@ -0,0 +1,69 @@
+"""Validate the exact plugin artifacts before uploading them to PyPI."""
+
+import argparse
+import tarfile
+import zipfile
+from email.parser import BytesParser
+from pathlib import Path
+
+
+def _wheel_metadata(path: Path) -> bytes:
+    with zipfile.ZipFile(path) as wheel:
+        names = wheel.namelist()
+        metadata_paths = [name for name in names if name.endswith(".dist-info/METADATA")]
+        if len(metadata_paths) != 1 or "yamcps_docs/__init__.py" not in names:
+            raise ValueError("Wheel must contain docs and exactly one metadata file")
+        return wheel.read(metadata_paths[0])
+
+
+def _source_metadata(path: Path) -> bytes:
+    with tarfile.open(path, "r:gz") as archive:
+        members = [
+            m
+            for m in archive.getmembers()
+            if m.name.count("/") == 1 and m.name.endswith("/PKG-INFO")
+        ]
+        if len(members) != 1:
+            raise ValueError("Expected one root source metadata file")
+        stream = archive.extractfile(members[0])
+        if stream is None:
+            raise ValueError("Missing source metadata")
+        with stream:
+            return stream.read()
+
+
+def verify(directory: Path, tag: str) -> None:
+    """Require exactly one yamcps-docs wheel and sdist matching a v-prefixed tag.
+
+    Args:
+        directory: Dedicated output directory for the plugin build.
+        tag: GitHub release tag, such as v0.1.0.
+
+    Raises:
+        ValueError: Unexpected artifacts, distribution name or version.
+    """
+    files = sorted(directory.iterdir())
+    wheels = [p for p in files if p.name.endswith(".whl")]
+    sources = [p for p in files if p.name.endswith(".tar.gz")]
+    if len(files) != 2 or len(wheels) != 1 or len(sources) != 1:
+        raise ValueError("Expected exactly one plugin wheel and one source archive")
+    if not tag.startswith("v") or not tag[1:]:
+        raise ValueError("Release tag must have the form v<package-version>")
+    metadata = [_wheel_metadata(wheels[0]), _source_metadata(sources[0])]
+    for raw in metadata:
+        message = BytesParser().parsebytes(raw)
+        if message["Name"] != "yamcps-docs" or message["Version"] != tag[1:]:
+            raise ValueError("Only yamcps-docs matching the release tag may be published")
+
+
+def main() -> None:
+    """Validate a build directory against its release tag."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", type=Path)
+    parser.add_argument("--tag", required=True)
+    args = parser.parse_args()
+    verify(args.directory, args.tag)
+
+
+if __name__ == "__main__":
+    main()

yamcps_docs-0.1.0/.github/workflows/workflow.yaml

@@ -0,0 +1,65 @@
+name: Publish yamcps-docs to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build plugin distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Verify release is based on main
+        run: git merge-base --is-ancestor HEAD origin/main
+      - name: Install build tools
+        run: python -m pip install build twine
+      # hatch-vcs reads the release tag from the complete Git history above.
+      # Keep the metadata check below: an inferred development version must not be published.
+      - name: Build only the plugin package
+        run: python -m build --outdir dist/package .
+      - name: Validate distribution identity and release version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python .github/workflows/verify_release.py dist/package --tag "$RELEASE_TAG"
+      - name: Check PyPI metadata
+        run: python -m twine check --strict dist/package/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: yamcps-docs-distributions
+          path: dist/package/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish plugin distribution
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/yamcps-docs
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: yamcps-docs-distributions
+          path: dist/package
+      - name: Publish yamcps-docs only
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/package/

yamcps_docs-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# 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
+*.lcov
+.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/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# 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/Zensical 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/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

yamcps_docs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JoReci
+
+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.

yamcps_docs-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: yamcps-docs
+Version: 0.1.0
+Summary: Local document retrieval connector for yamcps
+Project-URL: Repository, https://github.com/JoReci2/yamcps-docs
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: yamcps>=0.1
+Provides-Extra: dev
+Requires-Dist: bandit; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: editables; extra == 'dev'
+Requires-Dist: hatch-vcs<1,>=0.4; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: radon; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: formats
+Requires-Dist: pypdf<7,>=5; extra == 'formats'
+Requires-Dist: python-docx<2,>=1; extra == 'formats'
+Description-Content-Type: text/markdown
+
+# yamcps-docs
+
+Recherche documentaire locale via le RAG natif du moteur
+[yamcps](https://github.com/JoReci2/yamcps). Le plugin expose les documents indexés
+en lecture seule dans MCP ; l'ingestion se fait séparément en ligne de commande.
+Aucun secret n'est requis.
+
+TXT et Markdown UTF-8 sont pris en charge de base ; PDF texte et DOCX nécessitent
+l'extra `formats`. L'extraction ne fait ni OCR, ni extraction de figures, ni
+reconstruction de la mise en page.
+
+## Démarrage rapide
+
+Python ≥ 3.12 et un moteur yamcps compatible avec les configurations et le RAG
+natifs sont requis. Installer le plugin dans le même environnement que le moteur :
+
+```sh
+python -m pip install 'yamcps-docs[formats]'
+yamcps configs set --connector docs
+```
+
+Laisser les champs `index` et `model` vides pour utiliser l'index par défaut du
+moteur et la recherche lexicale. Depuis la racine de ce dépôt, essayer le devis de travaux
+fictif fourni :
+
+```sh
+yamcps-docs ingest examples/manifest.json
+yamcps serve --connector docs
+```
+
+Les fichiers d'exemple sont disponibles dans [examples](examples) ; hors du dépôt,
+les copier ensemble dans un dossier local. Depuis le client MCP, demander de
+rechercher `DEV-2026-0042` dans le corpus `demo/travaux`.
+
+Le serveur n'ingère rien au démarrage. Utiliser le même compte et la même
+configuration pour l'ingestion et le serveur. Le manifeste remplace le contenu du
+corpus désigné : ne pas utiliser l'exemple pour remplacer un corpus existant.
+
+Par exemple, demander ensuite : « Quel est le montant TTC du devis et quel acompte
+est prévu ? » ou « La peinture est-elle comprise dans le poste TRV-003 ? », avec
+les passages sources à l'appui.
+
+## Configuration
+
+Configurer les chemins avec `yamcps configs set --connector docs` ; aucun export
+de variable d'environnement n'est nécessaire. Les valeurs sont enregistrées dans
+un fichier JSON local. Préférer des chemins absolus pour éviter les différences
+de répertoire courant.
+
+| Champ | Description | Valeur par défaut | Ancienne variable de repli |
+| --- | --- | --- | --- |
+| `index` | Chemin de l'index SQLite | Vide : index du moteur pour `docs` | `YAMCPS_DOCS_INDEX` |
+| `model` | Dossier d'un modèle sémantique local | Vide : recherche lexicale | `YAMCPS_DOCS_MODEL` |
+
+Les deux champs sont facultatifs. Voir le
+[guide de configuration du moteur](https://github.com/JoReci2/yamcps/blob/main/docs/configuration.md)
+pour leur priorité, `--config-file` et le mode non interactif. Pour un fichier de
+configuration personnalisé, le transmettre aux deux commandes :
+
+```sh
+yamcps-docs ingest /chemin/vers/manifest.json --config-file /chemin/vers/config.json
+yamcps serve --connector docs --config-file /chemin/vers/config.json
+```
+
+### Recherche sémantique locale optionnelle
+
+Sans modèle, la recherche est lexicale et ne comprend pas les synonymes. Installer
+l'extra `rag`, puis télécharger explicitement un modèle Sentence Transformers
+avec yamcps depuis Hugging Face. Par exemple, pour un modèle multilingue :
+
+```sh
+python -m pip install 'yamcps[rag]'
+yamcps models download sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+```
+
+La commande affiche le chemin absolu du dossier téléchargé. Par défaut, il se
+trouve sous `~/.local/share/yamcps/models/<organisation>--<modele>/<commit>`.
+L'option `--revision` permet de choisir une branche, un tag ou un commit ;
+`--destination /chemin/absolu/vers/un-nouveau-dossier` fixe le dossier local.
+Le téléchargement nécessite une connexion réseau et n'active pas le modèle.
+
+Pour activer la recherche hybride, renseigner le chemin affiché dans le champ
+`model`, puis ingérer le corpus dans un nouvel index. Un modèle compatible déjà
+présent sur la machine peut aussi être utilisé directement :
+
+```sh
+yamcps configs set --connector docs --name model --value /chemin/absolu/vers/modele-local
+yamcps configs set --connector docs --name index --value /chemin/absolu/docs-hybrid.sqlite3
+yamcps-docs ingest /chemin/vers/manifest.json
+yamcps serve --connector docs
+```
+
+Utiliser le même modèle pour l'ingestion et la recherche. Un changement de modèle
+exige un nouvel index et une réingestion. Aucun modèle n'est fourni ni téléchargé
+automatiquement, et aucun code distant n'est autorisé. Côté serveur, le modèle est
+chargé au premier appel MCP, dans un thread, jamais à l'import ou à l'enregistrement
+du plugin.
+
+Pour un serveur hors ligne, télécharger le modèle sur une machine connectée,
+puis copier son dossier sur le serveur, y installer aussi l'extra `rag` et
+configurer `model` avec le chemin local de cette copie.
+Évaluer sa qualité sur vos questions métier ; aucune qualification IVVQ n'est
+revendiquée.
+
+## Ingestion d'un corpus
+
+Créer un manifeste JSON à côté des fichiers à indexer. Par exemple, avec `devis-travaux.md`
+dans le même dossier que `manifest.json` :
+
+```json
+{
+  "corpus": "demo/travaux",
+  "sources": [
+    {
+      "path": "devis-travaux.md",
+      "document_id": "DEV-2026-0042",
+      "revision": "1.0",
+      "metadata": {"project": "renovation-salon", "status": "example", "type": "devis"}
+    }
+  ]
+}
+```
+
+Puis lancer :
+
+```sh
+yamcps-docs ingest /chemin/vers/manifest.json
+```
+
+Le manifeste est un **snapshot complet d'un seul corpus** : retirer une source
+supprime cette révision de l'index. Garder explicitement les anciennes révisions
+souhaitées. Les métadonnées sont facultatives et associent des clés à des valeurs
+textuelles ; elles servent aux filtres de recherche. L'extraction de toutes les
+sources se termine avant la synchronisation atomique du corpus. Une ingestion
+identique réutilise les passages existants.
+
+Les chemins des sources sont relatifs au dossier du manifeste. Les chemins
+absolus, les traversées `..` et les liens symboliques sont refusés. Chaque source
+est limitée à 20 MiB et à 4 millions de caractères extraits ; un texte vide est
+refusé. N'ingérer que des fichiers de confiance.
+
+Le découpage utilise au plus 1200 caractères par passage, sans chevauchement.
+L'option `--chunk-size` permet une valeur de 64 à 16000. Un passage peut couper une
+phrase ou un tableau. Les contenus sont stockés en clair dans SQLite : protéger
+le dossier avec les droits du système et sauvegarder l'index si nécessaire.
+
+## Recherche et citations dans MCP
+
+| Outil | Paramètres | Description |
+| --- | --- | --- |
+| `docs_search` | `query`, `corpus`, `filters=None`, `limit=5` | Recherche de passages sourcés ; limite de 1 à 20 |
+| `docs_get_document` | `corpus`, `document_id`, `revision` | Texte extrait d'une révision précise |
+| `docs_get_passage` | `passage_id` | Passage cité et provenance exacte |
+| `docs_index_status` | `corpus` | Mode, compteurs et date du dernier passage modifié |
+
+Toujours préciser le corpus lors d'une recherche. Les filtres correspondent
+exactement aux métadonnées du manifeste, par exemple
+`{"project": "renovation-salon", "type": "devis"}` ; ils ne constituent pas des droits
+d'accès.
+
+Les ressources `docs://source/{corpus}/{document_id}/{revision}` (segments encodés)
+et `docs://passage/{passage_id}` exposent aussi les références citées. Pour une
+citation vérifiable, conserver `document_id`, `revision`, `source_uri`,
+`passage_id` et les offsets `start`/`end` renvoyés. Ces offsets désignent des
+caractères dans le texte extrait, début inclus et fin exclue ; ils ne garantissent
+pas une pagination dans le document original.
+
+L'index est une copie des sources au moment de l'ingestion. La date indiquée par
+`docs_index_status` concerne les passages modifiés et ne prouve pas la fraîcheur
+des fichiers sources. Un index absent produit une erreur explicative au premier
+appel, sans empêcher les autres plugins de démarrer. Aucune mutation de l'index
+n'est exposée au modèle via MCP.
+
+Le skill embarqué
+[docs-research](src/yamcps_docs/skills/docs-research/SKILL.md) guide la recherche de
+preuves et la citation des révisions exactes.
+
+## Contribution
+
+Voir [contributing.md](contributing.md) pour l'installation de développement,
+l'intégration au moteur et les validations.