- Revisiting RAG_SPECIALIST
- Adapt Catalogs & Retrievers to use specific types, removing tagging_fields - Adding CrewAI Implementation Guide
This commit is contained in:
Josako
@@ -2,31 +2,91 @@
|
||||
|
||||
## Name Sensitivity
|
||||
A lot of the required functionality to implement specialists has been automated. This automation is based on naming
|
||||
conventions. So ... names of variables, attributes, ... needs to be precise, or you'll get problems.
|
||||
conventions. So ... names of variables, attributes, ... needs to be precise, or you'll get into problems.
|
||||
|
||||
## Base Class: CrewAIBaseSpecialistExecutor
|
||||
|
||||
Inherit your SpecialistExecutor class from the base class CrewAIBaseSpecialistExecutor
|
||||
The base class for defining new CrewAI based Specialists is CrewAIBaseSpecialistExecutor. This class implements a lot of
|
||||
functionality out of the box, making the full development process easier to manage:
|
||||
|
||||
### Conventions
|
||||
- tasks are referenced by using the lower case name of the configured task
|
||||
- agents idem dito
|
||||
- Before the specialist execution
|
||||
- Retrieval of context (RAG Retrieval)
|
||||
- Build up of historic context (memory)
|
||||
- Initialisation of Agents, Tasks and tools (defined in the specialist configuration)
|
||||
- Initialisation of specialist state, based on historic context
|
||||
- During specialist execution
|
||||
- Updates to the history (ChatSession and Interaction)
|
||||
- Formatting of the results
|
||||
|
||||
### Specialise the __init__ method
|
||||
It enables the following functionality:
|
||||
|
||||
- Define the crews you want to use in your specialist implementation
|
||||
- Do other initialisations you require
|
||||
- Call super
|
||||
- Logging when requested (_log_tuning)
|
||||
- Sending progress updates (ept)
|
||||
- ...
|
||||
|
||||
### Type and Typeversion properties
|
||||
### Naming Conventions
|
||||
- tasks are referenced by using the lower case name of the configured task. Their names should always end on "_task"
|
||||
- agents idem dito, but their names should end on "_agent"
|
||||
- tools idem dito, but their names will end on "_tools"
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1 - Code location
|
||||
|
||||
The implementation of a specialist should be placed in the specialists folder. If the specialist is a global specialist
|
||||
(i.e. it can be used by all tenants), it will be in the globals folder. If it is created for a specific partner, we will
|
||||
place it in the folder for that partner (lower_case)
|
||||
|
||||
The naming of the implementation is dependent on the version of the specialist we are creating. If we implement a
|
||||
version 1.0, the implementation will be called "1_0.py". This implementation is also used for specialists with different
|
||||
patch versions (e.g. 1.0.1, 1.0.4, ...)
|
||||
|
||||
### Step 2: type and type_version properties
|
||||
|
||||
- Adapt the type and type_version properties to define the correct specialist. This refers to the actual specialist configuration!
|
||||
|
||||
### Implement _config_task_agents
|
||||
### Step 3: Specialist Setup
|
||||
|
||||
This method links the tasks to the agents that will perform LLM interactions. You can call the method _add_task_agent
|
||||
to link both.
|
||||
#### Specialising init
|
||||
|
||||
### Implement _config_pydantic_outputs
|
||||
Use specialisisation of the init method to define the crews you require, and if needed, additional initialisation code.
|
||||
|
||||
This method links the tasks to their pydantic outputs, and their name in the state class.
|
||||
#### configuring the specialist
|
||||
|
||||
- _config_task_agents
|
||||
- Link each task to the agent that will perform the task
|
||||
- use _add_task_agent for each of the tasks
|
||||
- _config_pytdantic_outputs
|
||||
- Link each task to a specific output (Pydantic)
|
||||
- use _add_pydantic_output for each of the tasks
|
||||
- _config_state_result_relations
|
||||
- Zorg dat er een automatische overdracht kan zijn van state naar result
|
||||
- use _add_state_result_relation om zo'n relatie toe te voegen
|
||||
- when you give the attributes in the state and result the same names, this becomes quite obvious and easy to maintain
|
||||
|
||||
### Step 4: Implement specialist execution
|
||||
|
||||
This is the entry method invoked to actually implement specialist logic.
|
||||
|
||||
#### Available data
|
||||
|
||||
- arguments: the arguments passed in the specialist invocation
|
||||
- formatted_context: the documents retrieved for the specialist
|
||||
- citations: the citations found in the retrieval process
|
||||
- self._formatted_history: a build-up of the history of the conversation
|
||||
- self._cached_session: the complete cached session
|
||||
- self.flow.state: the current flow state
|
||||
|
||||
#### Implementation guidelines
|
||||
|
||||
- allways use self.flow.state to update elements required to have available in consecutive calls, or elements you want to persist in the results
|
||||
- use the phase (defined in the state) to distinguish between phases in the specialist execution
|
||||
- Use "SelectionResult.create_for_type(self.type, self.type_version)" to return results.
|
||||
|
||||
### Step 5: Define Implementation Classes
|
||||
|
||||
- Define the Pydantic Output Classes to ensure structured outputs
|
||||
- Define an Input class, containing all potential inputs required for flows and crews to perform their activities
|
||||
- Define a FlowState (derived from EveAIFlowState) to maintain state throughout specialist execution
|
||||
- Define a Result (derived from SpecialistResult) to define all information that needs to be stored in the session
|
||||
- Define the Flow (derived from EveAICrewAIFlow) with the FlowState class
|
||||
118
documentation/tagging_fields_utils.md
Normal file
118
documentation/tagging_fields_utils.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Tagging Fields Hulpprogramma's
|
||||
|
||||
## Overzicht
|
||||
|
||||
Dit document beschrijft de functionaliteit voor "tagging fields" in het systeem. Deze code biedt een flexibele manier om metadata velden te definiëren, valideren en documenteren voor gebruik in verschillende onderdelen van de applicatie.
|
||||
|
||||
## Kernconcept
|
||||
|
||||
Tagging fields zijn configureerbare metadata velden die gebruikt worden om verschillende objecten in het systeem te categoriseren, filteren en organiseren. De code biedt een uitgebreide set hulpprogramma's om:
|
||||
|
||||
1. Velddefinities te maken en valideren
|
||||
2. Waarden te controleren op basis van veldbeperkingen
|
||||
3. Documentatie te genereren in verschillende formaten
|
||||
|
||||
## Hoofdklassen
|
||||
|
||||
### TaggingField
|
||||
|
||||
De `TaggingField` klasse vertegenwoordigt een enkel metadataveld met:
|
||||
|
||||
- **type**: Het gegevenstype (`string`, `integer`, `float`, `date`, `enum`, `color`)
|
||||
- **required**: Geeft aan of het veld verplicht is
|
||||
- **description**: Beschrijving van het veld
|
||||
- **allowed_values**: Mogelijke waarden voor enum typen
|
||||
- **min_value** / **max_value**: Begrenzingen voor numerieke waarden
|
||||
|
||||
Interne validatie zorgt ervoor dat:
|
||||
- Alleen geldige veldtypen worden gebruikt
|
||||
- Enum velden altijd toegestane waarden hebben
|
||||
- Numerieke velden geldige grenswaarden hebben
|
||||
|
||||
### TaggingFields
|
||||
|
||||
De `TaggingFields` klasse beheert een verzameling `TaggingField` objecten, gegroepeerd op naam. Het biedt:
|
||||
|
||||
- Conversie van/naar dictionaries met `from_dict()` en `to_dict()`
|
||||
- Centrale opslag voor alle metadataveld configuraties
|
||||
|
||||
### Constraints Klassen
|
||||
|
||||
Er zijn verschillende klassen die beperkingen definiëren voor elk type veld:
|
||||
|
||||
- **NumericConstraint**: Voor integer/float waarden (min/max grenzen)
|
||||
- **StringConstraint**: Voor tekstwaarden (lengte, patronen, verboden patronen)
|
||||
- **DateConstraint**: Voor datumwaarden (min/max datums, formaten)
|
||||
- **EnumConstraint**: Voor opsommingstypen (toegestane waarden, hoofdlettergevoeligheid)
|
||||
|
||||
Elke constraint klasse bevat een `validate()` methode om te controleren of een waarde voldoet aan de beperkingen.
|
||||
|
||||
### ArgumentDefinition en ArgumentDefinitions
|
||||
|
||||
Deze klassen breiden het concept uit naar functionele argumenten:
|
||||
|
||||
- **ArgumentDefinition**: Definieert een enkel argument met type en beperkingen
|
||||
- **ArgumentDefinitions**: Beheert een verzameling argumenten en biedt validatie
|
||||
|
||||
## Documentatie Generatie
|
||||
|
||||
De module bevat functies om automatisch documentatie te genereren voor tagging fields:
|
||||
|
||||
- `generate_field_documentation()`: Hoofdfunctie die documentatie genereert
|
||||
- Ondersteunt meerdere uitvoerformaten: Markdown, JSON, YAML
|
||||
- Biedt twee versieniveaus: basic en extended
|
||||
|
||||
```python
|
||||
# Voorbeeld van gebruik
|
||||
documentatie = generate_field_documentation(
|
||||
tagging_fields=fields_config,
|
||||
format="markdown",
|
||||
version="extended"
|
||||
)
|
||||
```
|
||||
|
||||
## Hulpfuncties voor Patroonverwerking
|
||||
|
||||
De module bevat ook hulpprogramma's voor het verwerken van regex patronen:
|
||||
|
||||
- `patterns_to_json()`: Zet tekstgebied-inhoud om naar JSON patronenlijst
|
||||
- `json_to_patterns()`: Zet JSON terug naar tekstgebied formaat
|
||||
- `json_to_pattern_list()`: Converteert JSON naar een Python lijst
|
||||
|
||||
## Validatie in Formulieren
|
||||
|
||||
In combinatie met webformulieren wordt de `validate_tagging_fields()` functie gebruikt om formulierinvoer te valideren tegen het tagging fields schema. Dit zorgt ervoor dat alleen geldige configuraties worden opgeslagen.
|
||||
|
||||
## Voorbeeld Implementatie
|
||||
|
||||
```python
|
||||
# Voorbeeld van tagging fields configuratie
|
||||
fields_config = {
|
||||
"priority": {
|
||||
"type": "enum",
|
||||
"required": True,
|
||||
"description": "Prioriteit van het item",
|
||||
"allowed_values": ["laag", "medium", "hoog"]
|
||||
},
|
||||
"deadline": {
|
||||
"type": "date",
|
||||
"required": False,
|
||||
"description": "Deadline voor voltooiing"
|
||||
},
|
||||
"tags": {
|
||||
"type": "string",
|
||||
"required": False,
|
||||
"description": "Zoektags voor het item"
|
||||
}
|
||||
}
|
||||
|
||||
# Maak een TaggingFields object
|
||||
fields = TaggingFields.from_dict(fields_config)
|
||||
|
||||
# Genereer documentatie
|
||||
docs = generate_field_documentation(fields_config, format="markdown")
|
||||
```
|
||||
|
||||
## Conclusie
|
||||
|
||||
De tagging fields functionaliteit biedt een krachtige en flexibele manier om metadata te beheren in de toepassing. Door gebruik te maken van sterke typering en validatie, zorgt het systeem ervoor dat gegevens consistent en betrouwbaar blijven, terwijl het toch aanpasbaar is aan verschillende gebruikssituaties.
|
||||
Reference in New Issue
Block a user