wyrlo 0.1.0__tar.gz

wyrlo-0.1.0/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

wyrlo-0.1.0/NOTICE

@@ -0,0 +1,6 @@
+WYRLO SDKs
+Copyright 2026 Mayeul FLORY, entrepreneur individuel (FUSION-IA) — contact@wyrlo.io
+
+This product includes software developed for WYRLO (https://www.wyrlo.io).
+Licensed under the Apache License, Version 2.0. The WYRLO service itself (API, engine,
+nightly loop, developer console) is proprietary and is not part of this repository.

wyrlo-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: wyrlo
+Version: 0.1.0
+Summary: SDK Python de WYRLO : dites « je ne sais pas » plutôt qu'une réponse fausse.
+Author-email: "Mayeul FLORY, entrepreneur individuel (FUSION-IA)" <contact@wyrlo.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://www.wyrlo.io
+Project-URL: Source, https://github.com/WYRLO-AI/wyrlo-sdk
+Keywords: rag,llm,reliability,hallucination,guardrails,wyrlo
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.14; extra == "llamaindex"
+Dynamic: license-file
+
+# wyrlo
+
+SDK Python de [WYRLO](https://www.wyrlo.io) : votre RAG dit « je ne sais pas » plutôt
+qu'une réponse fausse. Python 3.9+, aucune dépendance. **Côté serveur uniquement.**
+
+Le paquet n'est pas encore publié sur PyPI : la version 0.1.0 est prête et sera publiée
+à l'ouverture, sur accord du fondateur. Documentation : https://www.wyrlo.io/docs.
+
+En attendant, installez-le depuis le dépôt :
+
+```bash
+pip install /chemin/vers/wyrlo-sdk/python
+```
+
+## Utilisation
+
+```python
+from wyrlo import Wyrlo
+
+wyrlo = Wyrlo()  # lit WYRLO_API_KEY
+
+res = wyrlo.guard(
+    question=question,
+    passages=[{"id": d.id, "text": d.text, "source": d.file} for d in docs],
+    answer=answer,  # la réponse produite par votre LLM
+)
+
+if not res.should_answer:
+    return "Je ne sais pas. " + res.reason
+return res.answer  # citez res.kept_passages
+```
+
+Recommandé : préparez la recherche avec le vocabulaire de vos réglages, et passez le
+même identifiant de requête à `guard` :
+
+```python
+prepared = wyrlo.prepare(question)
+docs = search(prepared.query)  # votre recherche
+res = wyrlo.guard(question=question, passages=..., answer=answer,
+                  request_id=prepared.request_id)
+```
+
+`prepare` ne lève pas d'exception en cas de panne : il renvoie la question d'origine
+(`degraded=True`). Pendant un test partiel des réglages, `res.settings_variant` vaut
+`"control"` ou `"candidate"`.
+
+Si votre interface propose un pouce (en haut / en bas), transmettez-le avec le
+`trace_id` de la réponse (aucun texte envoyé) : `wyrlo.feedback(res.trace_id, helpful=True)`.
+
+Ou laissez le SDK appeler votre LLM : `generate=lambda passages: llm(question, passages)`.
+Les passages peuvent aussi être de simples chaînes.
+
+## LangChain et LlamaIndex
+
+Deux petites intégrations, testées avec les vraies bibliothèques (versions de
+`requirements-integrations.txt`). Elles appellent votre retriever et votre LLM, puis
+`guard` ; le résultat est le même `GuardResult`, et une panne de WYRLO ne lève jamais
+d'exception.
+
+```bash
+pip install "wyrlo[langchain]"     # ajoute langchain-core
+pip install "wyrlo[llamaindex]"    # ajoute llama-index-core
+```
+
+```python
+from wyrlo.langchain import guarded_chain
+
+rag = guarded_chain(retriever, prompt | llm)   # prompt : {question} et {context}
+res = rag.invoke("Quel est le délai de rétractation ?")
+```
+
+```python
+from wyrlo.llamaindex import GuardedQueryEngine
+
+engine = GuardedQueryEngine(index.as_retriever(similarity_top_k=5), llm)
+res = engine.query("Quel est le délai de rétractation ?")
+```
+
+Passages envoyés : identifiant (`Document.id` ou `node_id`), texte, source
+(`metadata["source"]`, ou `file_name` pour LlamaIndex) et score s'il existe.
+
+## Pannes : jamais bloquant
+
+Panne réseau, délai dépassé (3 s au total par défaut, nouvelle tentative comprise) ou erreur 5xx :
+une nouvelle tentative
+avec le même `request_id` (la question n'est comptée qu'une fois), puis un résultat
+**dégradé** : `decision="answer"`, `confidence="unverified"`, `degraded=True`.
+
+Plafond mensuel de l'offre gratuite atteint (2 000 questions analysées par mois) : même
+résultat dégradé, avec `quota_exceeded=True`, jusqu'au mois suivant.
+
+Une clé absente ou refusée, ou une requête invalide, lève `WyrloError`
+(`status`, `code`, `details`).
+
+## Options
+
+```python
+Wyrlo(api_key="wyr_live_…", base_url=None, timeout=3.0, max_retries=1, region=None, mask=None)
+```
+
+`base_url` : par défaut `WYRLO_BASE_URL`, sinon `DEFAULT_BASE_URL` (exporté par le
+paquet) : `https://api.wyrlo.io/functions/v1` (point d'entrée `/guard`) ; la valeur
+n'est écrite qu'à cet endroit du code. Une valeur vide retombe sur l'adresse par
+défaut ; les barres obliques finales sont retirées.
+
+`region` : par défaut `WYRLO_REGION`, sinon `eu-west-3` (Paris ; une valeur vide
+retombe aussi sur Paris). Chaque appel envoie l'en-tête `X-Region` : sans lui, Supabase
+exécuterait la fonction dans la région la plus proche de votre serveur (par exemple
+`us-east-1`), alors que la question, les passages et la réponse y arrivent en clair,
+avant masquage. L'en-tête de réponse `x-sb-edge-region` confirme la région de traitement.
+
+## Masquage côté client
+
+WYRLO masque les données personnelles reconnaissables avant tout traitement. Avec
+`mask=True`, ce masquage se fait **sur votre serveur, avant l'envoi** : les valeurs ne
+quittent jamais votre machine, WYRLO ne reçoit que des marques (`[EMAIL_1]`,
+`[TELEPHONE_1]`…).
+
+```python
+wyrlo = Wyrlo(mask=True)
+res = wyrlo.guard(question=question, passages=passages, answer=answer)
+# res.answer, res.reason et res.unsupported_sentences contiennent les vraies valeurs.
+# res.local_masking : LocalMasking(method="rules", counts={"EMAIL": 2, "TELEPHONE": 1})
+```
+
+Masqués (règles avec contrôle de validité, les mêmes que celles de WYRLO, bibliothèque
+standard seulement) : e-mails, téléphones (France et international), IBAN (clé vérifiée),
+cartes bancaires (contrôle de Luhn), numéro de sécurité sociale (clé vérifiée ou mot-clé
+proche), adresses IP, numéros de passeport et de carte d'identité (avec un mot-clé),
+adresses postales (numéro et type de voie), clés d'API et jetons reconnaissables. Une
+même valeur reçoit la même marque dans la question, la réponse et les passages.
+
+**Non masqués** : les noms de personnes et d'entreprises, les adresses sans numéro ni type
+de voie (lieu-dit), et tout identifiant sans forme reconnaissable. Les dates, montants et numéros de commande restent aussi : la
+vérification doit pouvoir les comparer. Pour les noms, passez votre propre fonction, par
+exemple Presidio installé sur votre machine (rien n'en sort) :
+
+```python
+from presidio_analyzer import AnalyzerEngine
+from presidio_anonymizer import AnonymizerEngine
+
+analyseur, anonymiseur = AnalyzerEngine(), AnonymizerEngine()
+
+def masque(textes):
+    # Reçoit tous les textes d'un appel, rend autant de textes masqués.
+    return [
+        anonymiseur.anonymize(text=t, analyzer_results=analyseur.analyze(text=t, language="en")).text
+        for t in textes
+    ]
+
+wyrlo = Wyrlo(mask=masque)
+```
+
+Si le masquage échoue (exception, nombre de textes différent), **rien n'est envoyé** :
+la réponse passe sans vérification (`degraded=True`, étape `anonymize` dans
+`skipped_steps`). Les fonctions `mask_texts` et `unmask_text` sont aussi exportées.
+
+## Index sans copie (mode B)
+
+Ouvert sur demande, projet par projet. WYRLO découpe vos documents, masque les données
+personnelles, calcule les vecteurs (Mistral AI, point d'accès européen), puis oublie le
+texte : seuls l'adresse, l'empreinte et le vecteur de chaque passage sont gardés.
+
+```python
+wyrlo.index(
+    "docs/cgv.md",
+    "2026-11-07",
+    title="Conditions générales de vente",  # recommandé : meilleure recherche, jamais conservé
+    text=contenu,
+    labels=["cgv"],
+)
+# Beaucoup de documents : 100 par appel, un résultat par document.
+lot = wyrlo.index_many(
+    [{"id": f.chemin, "version": f.version, "title": f.titre, "text": f.texte} for f in fichiers]
+)
+
+# 8 passages (environ 600 caractères chacun) : assez de contexte pour la réponse.
+res = wyrlo.search(question, k=8)
+passages = [
+    {
+        "id": f"{r['document']}#{r['start']}",
+        "text": lire_chez_vous(r["document"])[r["start"] : r["start"] + r["length"]],
+        "address": {k: r[k] for k in ("document", "version", "start", "length", "fingerprint")},
+    }
+    for r in res.results
+]
+out = wyrlo.guard(question=question, passages=passages, generate=generate)
+# Un passage modifié depuis son indexation revient avec stale=True : c'est un signal,
+# il ne change pas la décision. Relisez le document à jour et réindexez-le.
+
+wyrlo.remove("docs/cgv.md")  # toujours possible, même mode B coupé
+wyrlo.index_stats()  # chiffres seulement, aucun identifiant
+```
+
+- `search` ne lève jamais d'exception pour une panne : liste vide, `degraded=True`, à
+  compléter par votre propre recherche. `keyword_hits` fusionne vos résultats par mots-clés.
+- `index`, `remove` et `index_stats` lèvent `WyrloError` pour toute erreur, panne comprise
+  (`unavailable`) : refaire l'appel est sans risque (même `version` : « unchanged »).
+- Mode B coupé : `WyrloError` 403 `index_disabled`.
+- Avec l'option `mask`, `index` refuse d'envoyer le texte (`mask_unsupported`), car
+  positions et empreintes doivent porter sur votre texte d'origine ; passez
+  `allow_unmasked=True` pour l'envoyer quand même. Dans `guard`, un passage dont le
+  masquage change le texte part sans son adresse (il ne serait jamais reconnu).
+- `index_many` : jusqu'à 100 documents en un appel (corps de 512 Kio au plus), dans le même
+  espace, avec un résultat par document (`indexed`, `unchanged` ou `failed`). Un document
+  refusé n'empêche pas les autres ; avec le code `overloaded`, renvoyez-le plus tard.
+- `title` (facultatif, 300 caractères au plus) : titre du document, placé en tête de chaque
+  passage pour le calcul des vecteurs, jamais conservé. Envoyez-le quand le document en a
+  un : mesuré sur 283 questions jamais vues, le bon passage arrive dans les 5 premiers pour
+  85,2 % des questions avec le titre, contre 79,9 % sans. Changez la `version` si le titre
+  change.
+- Limites : 5 000 documents et 100 000 passages par projet ; 2 000 passages et
+  400 000 caractères par document.
+
+### Un espace par client final (mode C, plateformes)
+
+Si vous offrez un assistant à vos propres clients, rangez les documents de chacun dans
+son espace, avec un identifiant opaque de votre choix (jamais un nom ni une adresse
+e-mail ; lettres, chiffres, « . _ : - », 100 caractères au plus). Chaque recherche ne voit
+qu'un seul espace, filtré par la base de WYRLO :
+
+```python
+wyrlo.index("cgv.md", "v3", text=contenu, tenant="client-42")
+wyrlo.search(question, tenant="client-42")  # jamais les documents d'un autre
+wyrlo.remove("cgv.md", tenant="client-42")
+wyrlo.index_stats(tenant="client-42")
+wyrlo.remove_tenant("client-42")  # tout l'espace, tout de suite (fin de contrat)
+```
+
+Sans `tenant`, tout se passe dans l'espace par défaut du projet. Les limites restent
+celles du projet.
+Les retrievers LangChain et LlamaIndex prennent le même paramètre :
+`WyrloRetriever(client=wyrlo, read=lire, tenant="client-42")`.
+
+`passages_from_search(res.results, read)` fait la boucle ci-dessus pour vous : `read`
+reçoit `(document, version, start, length)` et rend le texte, ou `None` si le document
+n'existe plus (le résultat est alors écarté). Pour LangChain et LlamaIndex, un retriever
+fait la même chose et garde l'adresse jusqu'à `guard` :
+
+```python
+from wyrlo.langchain import WyrloRetriever, guarded_chain
+
+rag = guarded_chain(WyrloRetriever(client=wyrlo, read=read, k=8), prompt | llm)
+
+from wyrlo.llamaindex import GuardedQueryEngine, WyrloRetriever
+
+engine = GuardedQueryEngine(WyrloRetriever(wyrlo, read, k=8), llm)
+```
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Les tests des intégrations sont sautés si les bibliothèques manquent ;
+`scripts/deploy.sh` les lance dans un environnement où elles sont installées.

wyrlo-0.1.0/README.md

@@ -0,0 +1,257 @@
+# wyrlo
+
+SDK Python de [WYRLO](https://www.wyrlo.io) : votre RAG dit « je ne sais pas » plutôt
+qu'une réponse fausse. Python 3.9+, aucune dépendance. **Côté serveur uniquement.**
+
+Le paquet n'est pas encore publié sur PyPI : la version 0.1.0 est prête et sera publiée
+à l'ouverture, sur accord du fondateur. Documentation : https://www.wyrlo.io/docs.
+
+En attendant, installez-le depuis le dépôt :
+
+```bash
+pip install /chemin/vers/wyrlo-sdk/python
+```
+
+## Utilisation
+
+```python
+from wyrlo import Wyrlo
+
+wyrlo = Wyrlo()  # lit WYRLO_API_KEY
+
+res = wyrlo.guard(
+    question=question,
+    passages=[{"id": d.id, "text": d.text, "source": d.file} for d in docs],
+    answer=answer,  # la réponse produite par votre LLM
+)
+
+if not res.should_answer:
+    return "Je ne sais pas. " + res.reason
+return res.answer  # citez res.kept_passages
+```
+
+Recommandé : préparez la recherche avec le vocabulaire de vos réglages, et passez le
+même identifiant de requête à `guard` :
+
+```python
+prepared = wyrlo.prepare(question)
+docs = search(prepared.query)  # votre recherche
+res = wyrlo.guard(question=question, passages=..., answer=answer,
+                  request_id=prepared.request_id)
+```
+
+`prepare` ne lève pas d'exception en cas de panne : il renvoie la question d'origine
+(`degraded=True`). Pendant un test partiel des réglages, `res.settings_variant` vaut
+`"control"` ou `"candidate"`.
+
+Si votre interface propose un pouce (en haut / en bas), transmettez-le avec le
+`trace_id` de la réponse (aucun texte envoyé) : `wyrlo.feedback(res.trace_id, helpful=True)`.
+
+Ou laissez le SDK appeler votre LLM : `generate=lambda passages: llm(question, passages)`.
+Les passages peuvent aussi être de simples chaînes.
+
+## LangChain et LlamaIndex
+
+Deux petites intégrations, testées avec les vraies bibliothèques (versions de
+`requirements-integrations.txt`). Elles appellent votre retriever et votre LLM, puis
+`guard` ; le résultat est le même `GuardResult`, et une panne de WYRLO ne lève jamais
+d'exception.
+
+```bash
+pip install "wyrlo[langchain]"     # ajoute langchain-core
+pip install "wyrlo[llamaindex]"    # ajoute llama-index-core
+```
+
+```python
+from wyrlo.langchain import guarded_chain
+
+rag = guarded_chain(retriever, prompt | llm)   # prompt : {question} et {context}
+res = rag.invoke("Quel est le délai de rétractation ?")
+```
+
+```python
+from wyrlo.llamaindex import GuardedQueryEngine
+
+engine = GuardedQueryEngine(index.as_retriever(similarity_top_k=5), llm)
+res = engine.query("Quel est le délai de rétractation ?")
+```
+
+Passages envoyés : identifiant (`Document.id` ou `node_id`), texte, source
+(`metadata["source"]`, ou `file_name` pour LlamaIndex) et score s'il existe.
+
+## Pannes : jamais bloquant
+
+Panne réseau, délai dépassé (3 s au total par défaut, nouvelle tentative comprise) ou erreur 5xx :
+une nouvelle tentative
+avec le même `request_id` (la question n'est comptée qu'une fois), puis un résultat
+**dégradé** : `decision="answer"`, `confidence="unverified"`, `degraded=True`.
+
+Plafond mensuel de l'offre gratuite atteint (2 000 questions analysées par mois) : même
+résultat dégradé, avec `quota_exceeded=True`, jusqu'au mois suivant.
+
+Une clé absente ou refusée, ou une requête invalide, lève `WyrloError`
+(`status`, `code`, `details`).
+
+## Options
+
+```python
+Wyrlo(api_key="wyr_live_…", base_url=None, timeout=3.0, max_retries=1, region=None, mask=None)
+```
+
+`base_url` : par défaut `WYRLO_BASE_URL`, sinon `DEFAULT_BASE_URL` (exporté par le
+paquet) : `https://api.wyrlo.io/functions/v1` (point d'entrée `/guard`) ; la valeur
+n'est écrite qu'à cet endroit du code. Une valeur vide retombe sur l'adresse par
+défaut ; les barres obliques finales sont retirées.
+
+`region` : par défaut `WYRLO_REGION`, sinon `eu-west-3` (Paris ; une valeur vide
+retombe aussi sur Paris). Chaque appel envoie l'en-tête `X-Region` : sans lui, Supabase
+exécuterait la fonction dans la région la plus proche de votre serveur (par exemple
+`us-east-1`), alors que la question, les passages et la réponse y arrivent en clair,
+avant masquage. L'en-tête de réponse `x-sb-edge-region` confirme la région de traitement.
+
+## Masquage côté client
+
+WYRLO masque les données personnelles reconnaissables avant tout traitement. Avec
+`mask=True`, ce masquage se fait **sur votre serveur, avant l'envoi** : les valeurs ne
+quittent jamais votre machine, WYRLO ne reçoit que des marques (`[EMAIL_1]`,
+`[TELEPHONE_1]`…).
+
+```python
+wyrlo = Wyrlo(mask=True)
+res = wyrlo.guard(question=question, passages=passages, answer=answer)
+# res.answer, res.reason et res.unsupported_sentences contiennent les vraies valeurs.
+# res.local_masking : LocalMasking(method="rules", counts={"EMAIL": 2, "TELEPHONE": 1})
+```
+
+Masqués (règles avec contrôle de validité, les mêmes que celles de WYRLO, bibliothèque
+standard seulement) : e-mails, téléphones (France et international), IBAN (clé vérifiée),
+cartes bancaires (contrôle de Luhn), numéro de sécurité sociale (clé vérifiée ou mot-clé
+proche), adresses IP, numéros de passeport et de carte d'identité (avec un mot-clé),
+adresses postales (numéro et type de voie), clés d'API et jetons reconnaissables. Une
+même valeur reçoit la même marque dans la question, la réponse et les passages.
+
+**Non masqués** : les noms de personnes et d'entreprises, les adresses sans numéro ni type
+de voie (lieu-dit), et tout identifiant sans forme reconnaissable. Les dates, montants et numéros de commande restent aussi : la
+vérification doit pouvoir les comparer. Pour les noms, passez votre propre fonction, par
+exemple Presidio installé sur votre machine (rien n'en sort) :
+
+```python
+from presidio_analyzer import AnalyzerEngine
+from presidio_anonymizer import AnonymizerEngine
+
+analyseur, anonymiseur = AnalyzerEngine(), AnonymizerEngine()
+
+def masque(textes):
+    # Reçoit tous les textes d'un appel, rend autant de textes masqués.
+    return [
+        anonymiseur.anonymize(text=t, analyzer_results=analyseur.analyze(text=t, language="en")).text
+        for t in textes
+    ]
+
+wyrlo = Wyrlo(mask=masque)
+```
+
+Si le masquage échoue (exception, nombre de textes différent), **rien n'est envoyé** :
+la réponse passe sans vérification (`degraded=True`, étape `anonymize` dans
+`skipped_steps`). Les fonctions `mask_texts` et `unmask_text` sont aussi exportées.
+
+## Index sans copie (mode B)
+
+Ouvert sur demande, projet par projet. WYRLO découpe vos documents, masque les données
+personnelles, calcule les vecteurs (Mistral AI, point d'accès européen), puis oublie le
+texte : seuls l'adresse, l'empreinte et le vecteur de chaque passage sont gardés.
+
+```python
+wyrlo.index(
+    "docs/cgv.md",
+    "2026-11-07",
+    title="Conditions générales de vente",  # recommandé : meilleure recherche, jamais conservé
+    text=contenu,
+    labels=["cgv"],
+)
+# Beaucoup de documents : 100 par appel, un résultat par document.
+lot = wyrlo.index_many(
+    [{"id": f.chemin, "version": f.version, "title": f.titre, "text": f.texte} for f in fichiers]
+)
+
+# 8 passages (environ 600 caractères chacun) : assez de contexte pour la réponse.
+res = wyrlo.search(question, k=8)
+passages = [
+    {
+        "id": f"{r['document']}#{r['start']}",
+        "text": lire_chez_vous(r["document"])[r["start"] : r["start"] + r["length"]],
+        "address": {k: r[k] for k in ("document", "version", "start", "length", "fingerprint")},
+    }
+    for r in res.results
+]
+out = wyrlo.guard(question=question, passages=passages, generate=generate)
+# Un passage modifié depuis son indexation revient avec stale=True : c'est un signal,
+# il ne change pas la décision. Relisez le document à jour et réindexez-le.
+
+wyrlo.remove("docs/cgv.md")  # toujours possible, même mode B coupé
+wyrlo.index_stats()  # chiffres seulement, aucun identifiant
+```
+
+- `search` ne lève jamais d'exception pour une panne : liste vide, `degraded=True`, à
+  compléter par votre propre recherche. `keyword_hits` fusionne vos résultats par mots-clés.
+- `index`, `remove` et `index_stats` lèvent `WyrloError` pour toute erreur, panne comprise
+  (`unavailable`) : refaire l'appel est sans risque (même `version` : « unchanged »).
+- Mode B coupé : `WyrloError` 403 `index_disabled`.
+- Avec l'option `mask`, `index` refuse d'envoyer le texte (`mask_unsupported`), car
+  positions et empreintes doivent porter sur votre texte d'origine ; passez
+  `allow_unmasked=True` pour l'envoyer quand même. Dans `guard`, un passage dont le
+  masquage change le texte part sans son adresse (il ne serait jamais reconnu).
+- `index_many` : jusqu'à 100 documents en un appel (corps de 512 Kio au plus), dans le même
+  espace, avec un résultat par document (`indexed`, `unchanged` ou `failed`). Un document
+  refusé n'empêche pas les autres ; avec le code `overloaded`, renvoyez-le plus tard.
+- `title` (facultatif, 300 caractères au plus) : titre du document, placé en tête de chaque
+  passage pour le calcul des vecteurs, jamais conservé. Envoyez-le quand le document en a
+  un : mesuré sur 283 questions jamais vues, le bon passage arrive dans les 5 premiers pour
+  85,2 % des questions avec le titre, contre 79,9 % sans. Changez la `version` si le titre
+  change.
+- Limites : 5 000 documents et 100 000 passages par projet ; 2 000 passages et
+  400 000 caractères par document.
+
+### Un espace par client final (mode C, plateformes)
+
+Si vous offrez un assistant à vos propres clients, rangez les documents de chacun dans
+son espace, avec un identifiant opaque de votre choix (jamais un nom ni une adresse
+e-mail ; lettres, chiffres, « . _ : - », 100 caractères au plus). Chaque recherche ne voit
+qu'un seul espace, filtré par la base de WYRLO :
+
+```python
+wyrlo.index("cgv.md", "v3", text=contenu, tenant="client-42")
+wyrlo.search(question, tenant="client-42")  # jamais les documents d'un autre
+wyrlo.remove("cgv.md", tenant="client-42")
+wyrlo.index_stats(tenant="client-42")
+wyrlo.remove_tenant("client-42")  # tout l'espace, tout de suite (fin de contrat)
+```
+
+Sans `tenant`, tout se passe dans l'espace par défaut du projet. Les limites restent
+celles du projet.
+Les retrievers LangChain et LlamaIndex prennent le même paramètre :
+`WyrloRetriever(client=wyrlo, read=lire, tenant="client-42")`.
+
+`passages_from_search(res.results, read)` fait la boucle ci-dessus pour vous : `read`
+reçoit `(document, version, start, length)` et rend le texte, ou `None` si le document
+n'existe plus (le résultat est alors écarté). Pour LangChain et LlamaIndex, un retriever
+fait la même chose et garde l'adresse jusqu'à `guard` :
+
+```python
+from wyrlo.langchain import WyrloRetriever, guarded_chain
+
+rag = guarded_chain(WyrloRetriever(client=wyrlo, read=read, k=8), prompt | llm)
+
+from wyrlo.llamaindex import GuardedQueryEngine, WyrloRetriever
+
+engine = GuardedQueryEngine(WyrloRetriever(wyrlo, read, k=8), llm)
+```
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Les tests des intégrations sont sautés si les bibliothèques manquent ;
+`scripts/deploy.sh` les lance dans un environnement où elles sont installées.

wyrlo-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wyrlo"
+version = "0.1.0"
+description = "SDK Python de WYRLO : dites « je ne sais pas » plutôt qu'une réponse fausse."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Mayeul FLORY, entrepreneur individuel (FUSION-IA)", email = "contact@wyrlo.io" }]
+keywords = ["rag", "llm", "reliability", "hallucination", "guardrails", "wyrlo"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=1.0"]
+llamaindex = ["llama-index-core>=0.14"]
+
+[project.urls]
+Homepage = "https://www.wyrlo.io"
+Source = "https://github.com/WYRLO-AI/wyrlo-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+wyrlo = ["py.typed"]

wyrlo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+