Metadata-Version: 2.4
Name: tock-genai-core
Version: 1.9.1
Summary: 
License-File: LICENSE
Author: Baptiste Le Goff
Author-email: baptiste.le-goff@arkea.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: boto3 (>=1.35.96,<2.0.0)
Requires-Dist: google-api-core (>=2.25.1,<3.0.0)
Requires-Dist: google-cloud-secret-manager (>=2.22.0,<3.0.0)
Requires-Dist: google-cloud-storage (>=3.1.0,<4.0.0)
Requires-Dist: kubernetes (==33.1.0)
Requires-Dist: langchain (>=0.3.23,<0.4.0)
Requires-Dist: langchain-community (>=0.3.21,<0.4.0)
Requires-Dist: langchain-openai (>=0.3.13,<0.4.0)
Requires-Dist: langchain-postgres (>=0.0.14,<0.0.15)
Requires-Dist: langfuse (>=3.2.1,<4.0.0)
Requires-Dist: opensearch-py (>=2.8.0,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pydantic-settings (>=2.7.1,<3.0.0)
Requires-Dist: text-generation (>=0.7.0,<0.8.0)
Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
Description-Content-Type: text/markdown

# tock-genai-core
Composants principaux d'IA générative : models, factories, gestion des erreurs utilisés dans les composants Gen AI python de tock.

## Architecture

Le projet est structuré en trois composants principaux :

- **Models** : Contient les définitions des classes et modèles de données utilisés dans l'application
- **Services/Factories** : Regroupe la logique métier et les fonctions utilisées par les routes


## Technologies

- **Backend** : Python
- **Base de données** :
  - pgvector pour la base de données vectorielle
- **LLM & RAG** :
  - Langchain pour l'orchestration
  - Support de guardrails
  - Reranker pour l'amélioration des résultats
  - Langfuse pour le monitoring


## Providers disponibles

- **LLMProvider** (LLM)
    - TGI = "HuggingFaceTextGenInference"
    - OpenAI = "OpenAI"
    - Vllm = "Vllm"

- **GuardrailProvider** (Guardrail)
    - BloomZ = "BloomzGuardrail"

- **EMProvider** (Embedding)
    - BloomZ = "BloomzEmbeddings"
    - OpenAI = "OpenAI"
    - Vllm = "Vllm"

- **VectorDBProvider** (Database)
    - OpenSearch = "OPENSEARCH"
    - PGVector = "PGVECTOR"
    - PGVectorStore = "PGVECTORSTORE"

- **ContextualCompressorProvider** (Contetual Compressor)
    - BloomZ = "BloomzRerank"

## Secret Keys

Types disponibles :  
- **RawSecretKey** : stocke directement la valeur du secret.  
  - Champ principal : `secret`  
  - Alias rétro-compatible : `value` (encore utilisable pour compatibilité, mais à éviter dans les nouvelles configurations).
- **AwsSecretKey** : référence un secret dans **AWS Secrets Manager**.  
- **KubernetesSecretKey** : référence un secret dans **Kubernetes Secrets**.  
- **GcpSecretKey** : référence un secret dans **GCP Secret Manager**.

### GCP Secret Manager

Pour utiliser `GcpSecretKey`, un `project_id` GCP doit être disponible.  
Il est résolu automatiquement de la façon suivante :

1. Si la variable d’environnement `GCP_PROJECT_ID` est définie -> elle est utilisée directement.  
2. Sinon, le `project_id` est automatiquement détecté à partir des credentials Google (`GOOGLE_APPLICATION_CREDENTIALS`).  

## Settings

- **Embedding**
  
  - Classe parente
    ```
    BaseEMSetting:
        provider: EMProvider
        model: Optional[str]
        api_key: Optional[SecretKey]
        api_base: str
        pooling: Optional[str]
        space_type: Optional[str]
    ```
  - Classes enfants
    ```
    BloomZEMSetting(BaseEMSetting):
        provider: Literal[EMProvider.BloomZ]
    ```


    ```
    VLLMEMSetting(BaseEMSetting):
        provider: Literal[EMProvider.Vllm]
        model: str
    ```


    ```
    OpenAIEMSetting(BaseEMSetting):
        provider: Literal[EMProvider.OpenAI]
        api_base: str
        api_version: str
        deployment: str
    ```

- **Contextual compressor**

  - Classe parente
    ```
    BaseCompressorSetting:
        provider: ContextualCompressorProvider
        endpoint: str
        api_key: Optional[SecretKey]
    ```

  - Classe enfant
    ```
    BloomZCompressorSetting(BaseCompressorSetting):
        provider: Literal[ContextualCompressorProvider.BloomZ]
        min_score: float
        max_documents: Optional[int]
        label: Optional[str]
    ```

- **Database** 

  - Classe parente
    ```
    BaseVectorDBSetting:
        index: Optional[str]
        provider: VectorDBProvider
        db_url: str
    ```
  - Classes enfants
    ```
    OpenSearchSetting(BaseVectorDBSetting):
        provider: Literal[VectorDBProvider.OpenSearch]
        username: SecretKey
        password: SecretKey
        use_ssl: bool
        verify_certs: bool
    ```

    ```
    class PGVectorSetting(BaseVectorDBSetting):
        provider: Literal[VectorDBProvider.PGVector]
        username: SecretKey
        password: SecretKey 
        db_name: str
        sslmode: Optional[str]
        namespace: str
    ```

    ```
    class PGVectorStoreSetting(PGVectorSetting):
        provider: Literal[VectorDBProvider.PGVectorStore]
        common_metadata_columns: Optional[List[MetadataColumnSetting]]
        fts_column: Optional[str]
        fts_language: str
    ```

- **Guardrail**

  - Classe parente
    ```
    BaseGuardrailSetting:
        provider: GuardrailProvider
        api_base: str
        max_score: Optional[float]
        api_key: Optional[SecretKey]
    ```

  - Classe enfant
    ```
    BloomZGuardrailSetting(BaseGuardrailSetting):
        provider: Literal[GuardrailProvider.BloomZ]
    ```

- **Langfuse**
  ```
  LangfuseSetting:
      host: Optional[str]
      public_key: Optional[SecretKey]
      secret_key: Optional[SecretKey]
      metadata: Optional[Dict[str, Any]]
  ```

- **LLM**

  - Classe parente
    ```
    BaseLLMSetting:
        provider: LLMProvider
        model: Optional[str]
        api_key: Optional[SecretKey]
        temperature: float
    ```

  - Classes enfants
    ```
    OpenAILLMSetting(BaseLLMSetting):
        provider: Literal[LLMProvider.OpenAI]
        api_base: str
        api_version: str
        deployment: str
    ```

    ```
    HuggingFaceTextGenInferenceLLMSetting(BaseLLMSetting):
        provider: Literal[LLMProvider.TGI]
        repetition_penalty: float
        max_new_tokens: int
        api_base: str
        streaming: bool
    ```

    ```
    VllmSetting(BaseLLMSetting):
        provider: Literal[LLMProvider.Vllm]
        api_base: str
        max_new_tokens: int
        additional_model_kwargs: Optional[Dict[str, Any]]
    ```

## PGVector vs PGVectorStore

Deux providers PostgreSQL coexistent, chacun avec sa propre factory (`PGVectorFactory`/`PGVectorStoreFactory`), tous les deux dispatchés par `get_vector_db_factory` selon `db_settings.provider`. Aucun des deux n'est déprécié : `PGVector` (v1) reste inchangé pour les applications consommatrices qui l'utilisent déjà, `PGVectorStore` (v2) est un provider additionnel, à choisir explicitement.

- **`PGVector`** (`VectorDBProvider.PGVector`, classe `PGVectorSetting`) : basé sur `langchain_postgres.vectorstores.PGVector`. Toutes les collections sont stockées dans deux tables partagées (`langchain_pg_collection`/`langchain_pg_embedding`), avec un filtrage sur métadonnées qui accepte n'importe quelle clé JSON arbitraire.
- **`PGVectorStore`** (`VectorDBProvider.PGVectorStore`, classe `PGVectorStoreSetting`) : basé sur `langchain_postgres.v2.PGVectorStore`/`PGEngine`. Chaque collection est stockée dans sa propre table physique, avec un jeu de colonnes de métadonnées déclarées (`common_metadata_columns`) plutôt qu'un filtrage JSON arbitraire.

`PGVectorStoreSetting` hérite de `PGVectorSetting` (mêmes champs de connexion) et ajoute :
- `common_metadata_columns: Optional[List[MetadataColumnSetting]]` : colonnes de métadonnées à créer sur la table physique de chaque nouvelle collection (`MetadataColumnSetting(name, data_type)`). tock-genai-core n'a aucune opinion sur le contenu de cette liste : c'est à l'application appelante de la définir selon son propre modèle de métadonnées (l'orchestrateur, par exemple, la dérive de son propre modèle `EmbeddingCMetadata`).
- `fts_column: Optional[str]` : si renseigné, un index GIN de recherche plein-texte (`to_tsvector`) est créé sur cette colonne pour chaque nouvelle table de collection.
- `fts_language: str` (défaut `"english"`) : la langue de configuration `to_tsvector`/`to_tsquery` utilisée pour l'index de `fts_column`.

`PGVectorStoreFactory.get_vector_store()` gère lui-même, en interne, la résolution/provisioning de la table physique d'une collection (table déjà existante vs première utilisation), afin de ne pas exposer cette logique aux applications appelantes ni la dupliquer entre elles.

## Fonctionnement

Chaque outil utilisé (database, embedding, llm, langfuse, ...) a besoin d'un certains nombre de paramètres qui sont référencés dans les models (classes de settings)

Ces classes sont ensuite héritées par des services ou des factories afin de pouvoir répondre au besoin.


Exemple de `get_vector_db_factory` qui crée une factory de base vectorielle basée sur le nom de l'application et les paramètres d'embedding fournis

```python
from tock-genai-core import get_vector_db_factory
from tock-genai-core import PGVectorSetting, VLLMEMSetting
from tock-genai-core import DBSetting, EMSetting


db_settings = PGVectorSetting(
    index = "first_index",
    provider = "PGVECTOR",
    db_url = "127.0.0.1:XXXX",
    db_name = "rag_sandbox_db",
    sslmode = "disable",
    username = {
      type = "Raw",
      value = "admin"
    },
    password = {
      type = "Raw",
      value = "example"
    },
    namespace = "test-name"
)

em_settings = VLLMEMSetting(
    provider = "Vllm",
    model = "model_name",
    api_base = "https://continue.com/v1"
)



def function_name(db_settings: DBSetting, em_settings: EMSetting):

    # do somethings

    vector = get_vector_db_factory(db_settings: DBSetting, em_settings: BaseEMSetting)

    # do somethings
```

