agent-lab-sdk 0.1.14__tar.gz → 0.1.15__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of agent-lab-sdk might be problematic. Click here for more details.

Files changed (27) hide show
  1. agent_lab_sdk-0.1.15/PKG-INFO +242 -0
  2. agent_lab_sdk-0.1.15/README.md +213 -0
  3. agent_lab_sdk-0.1.15/agent_lab_sdk.egg-info/PKG-INFO +242 -0
  4. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/pyproject.toml +1 -1
  5. agent_lab_sdk-0.1.14/PKG-INFO +0 -65
  6. agent_lab_sdk-0.1.14/README.md +0 -36
  7. agent_lab_sdk-0.1.14/agent_lab_sdk.egg-info/PKG-INFO +0 -65
  8. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/LICENSE +0 -0
  9. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/__init__.py +0 -0
  10. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/langgraph/checkpoint/__init__.py +0 -0
  11. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/langgraph/checkpoint/agw_saver.py +0 -0
  12. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/llm/__init__.py +0 -0
  13. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/llm/agw_token_manager.py +0 -0
  14. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/llm/gigachat_token_manager.py +0 -0
  15. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/llm/llm.py +0 -0
  16. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/llm/throttled.py +0 -0
  17. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/metrics/__init__.py +0 -0
  18. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/metrics/metrics.py +0 -0
  19. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/schema/__init__.py +0 -0
  20. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/schema/log_message.py +0 -0
  21. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/storage/__init__.py +0 -0
  22. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk/storage/storage.py +0 -0
  23. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk.egg-info/SOURCES.txt +0 -0
  24. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk.egg-info/dependency_links.txt +0 -0
  25. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk.egg-info/requires.txt +0 -0
  26. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/agent_lab_sdk.egg-info/top_level.txt +0 -0
  27. {agent_lab_sdk-0.1.14 → agent_lab_sdk-0.1.15}/setup.cfg +0 -0
@@ -0,0 +1,242 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-lab-sdk
3
+ Version: 0.1.15
4
+ Summary: SDK для работы с Agent Lab
5
+ Author-email: Andrew Ohurtsov <andermirik@yandex.com>
6
+ License: Proprietary and Confidential — All Rights Reserved
7
+ Keywords: agent,lab,sdk
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Software Development :: Libraries
11
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: License :: Other/Proprietary License
17
+ Classifier: Operating System :: OS Independent
18
+ Requires-Python: <4.0,>=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: requests
22
+ Requires-Dist: langgraph~=0.4.1
23
+ Requires-Dist: langchain_gigachat
24
+ Requires-Dist: prometheus-client
25
+ Requires-Dist: langchain
26
+ Requires-Dist: httpx~=0.27.2
27
+ Requires-Dist: orjson>=3.9.7
28
+ Dynamic: license-file
29
+
30
+ # Agent Lab SDK
31
+
32
+ Набор утилит и обёрток для упрощённой работы с LLM, Agent Gateway и метриками в проектах Giga Labs.
33
+
34
+ ## Установка
35
+
36
+ ```bash
37
+ pip install agent_lab_sdk
38
+ ```
39
+
40
+ ## Содержание
41
+
42
+ 1. [Модуль `agent_lab_sdk.llm`](#1-модуль-agent_lab_sdkllm)
43
+ 2. [Модуль `agent_lab_sdk.llm.throttled`](#2-модуль-agent_lab_sdkllmthrottled)
44
+ 3. [Модуль `agent_lab_sdk.metrics`](#3-модуль-agent_lab_sdkmetrics)
45
+ 4. [Хранилище](#4-хранилище)
46
+ 5. [Схема](#5-схема)
47
+ 6. [Сборка и публикация](#6-сборка-и-публикация)
48
+
49
+ ---
50
+
51
+ ## 1. Модуль `agent_lab_sdk.llm`
52
+
53
+ ### 1.1. Получение модели
54
+
55
+ ```python
56
+ from agent_lab_sdk.llm import get_model
57
+
58
+ # Использует токен из окружения по умолчанию
59
+ model = get_model()
60
+
61
+ # Передача явных параметров
62
+ model = get_model(
63
+ access_token="YOUR_TOKEN",
64
+ timeout=60,
65
+ scope="GIGACHAT_API_CORP"
66
+ )
67
+ ```
68
+
69
+ > если не передавать access_token, токен будет выбран через GigaChatTokenManager
70
+
71
+ > планы на ближайшее будущее: get_model оборачивает внутри себя throttled классы.
72
+
73
+ ### 1.2. Менеджеры токенов
74
+
75
+ | Класс | Описание | Пример использования |
76
+ | ---------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
77
+ | `AgwTokenManager` | Кеширование + получение токена через Agent Gateway | `token = AgwTokenManager.get_token("provider")` |
78
+ | `GigaChatTokenManager` | Кеширование + получение через GigaChat OAuth с использованием пользовательских секретов | `token = GigaChatTokenManager.get_token()` |
79
+
80
+ ### 1.3. Переменные окружения
81
+
82
+ | Переменная | Описание | Значение по умолчанию / Пример |
83
+ | ---------------------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
84
+ | `GIGACHAT_SCOPE` | Scope GigaChat API | `GIGACHAT_API_PERS` |
85
+ | `GLOBAL_GIGACHAT_TIMEOUT` | Таймаут запросов к GigaChat (секунды) | `120` |
86
+ | `USE_TOKEN_PROVIDER_AGW` | Использовать `AgwTokenManager` | `true` |
87
+ | `GIGACHAT_CREDENTIALS` | Базовые креды для GigaChat (`b64(clientId:secretId)`) | `Y2xpZW50SWQ6c2VjcmV0SWQ=` |
88
+ | `GIGACHAT_TOKEN_PATH` | Путь к файлу кеша токена GigaChat | `/tmp/gigachat_token.json` |
89
+ | `GIGACHAT_TOKEN_FETCH_RETRIES` | Количество попыток получения токена (GigaChat) | `3` |
90
+ | `USE_GIGACHAT_ADVANCED` | Включает запрос токена GigaChat API в продвинутом режиме | `true` |
91
+ | `GIGACHAT_BASE_URL` | Базовый URL GigaChat для расширенного режима | `https://ngw.devices.sberbank.ru:9443/api/v2/oauth` |
92
+ | `TOKEN_PROVIDER_AGW_URL` | URL Agent Gateway для получения AGW-токена | `https://agent-gateway.apps.advosd.sberdevices.ru` |
93
+ | `TOKEN_PROVIDER_AGW_DEFAULT_MAX_RETRIES` | Макс. попыток запроса токена (AGW) | `3` |
94
+ | `TOKEN_PROVIDER_AGW_TIMEOUT_SEC` | Таймаут запроса к AGW (секунды) | `5` |
95
+
96
+ ---
97
+
98
+ <a name="throttled"></a>
99
+
100
+ ## 2. Модуль `agent_lab_sdk.llm.throttled`
101
+
102
+ Позволяет ограничивать число одновременных вызовов к GigaChat и сервису эмбеддингов, автоматически собирая соответствующие метрики.
103
+
104
+ ```python
105
+ from agent_lab_sdk.llm import GigaChatTokenManager
106
+ from agent_lab_sdk.llm.throttled import ThrottledGigaChat, ThrottledGigaChatEmbeddings
107
+
108
+ access_token = GigaChatTokenManager.get_token()
109
+
110
+ # Чат с учётом ограничений
111
+ chat = ThrottledGigaChat(access_token=access_token)
112
+ response = chat.invoke("Привет!")
113
+
114
+ # Эмбеддинги с учётом ограничений
115
+ emb = ThrottledGigaChatEmbeddings(access_token=access_token)
116
+ vectors = emb.embed_documents(["Text1", "Text2"])
117
+ ```
118
+
119
+ ### 2.1. Переменные окружения для ограничения
120
+
121
+ | Переменная | Описание | Значение по умолчанию |
122
+ | --------------------------------- | ------------------------------------------- | --------------------- |
123
+ | `MAX_CHAT_CONCURRENCY` | Максимум одновременных чат-запросов | `100000` |
124
+ | `MAX_EMBED_CONCURRENCY` | Максимум одновременных запросов эмбеддингов | `100000` |
125
+ | `EMBEDDINGS_MAX_BATCH_SIZE_PARTS` | Макс. размер батча частей для эмбеддингов | `90` |
126
+
127
+ ### 2.2. Метрики
128
+
129
+ Метрики доступны через `agent_lab_sdk.metrics.get_metric`:
130
+
131
+ | Метрика | Описание | Тип |
132
+ | ------------------------- | ---------------------------------------------- | --------- |
133
+ | `chat_slots_in_use` | Число занятых слотов для чата | Gauge |
134
+ | `chat_waiting_tasks` | Число задач, ожидающих освобождения слота чата | Gauge |
135
+ | `chat_wait_time_seconds` | Время ожидания слота чата (секунды) | Histogram |
136
+ | `embed_slots_in_use` | Число занятых слотов для эмбеддингов | Gauge |
137
+ | `embed_waiting_tasks` | Число задач, ожидающих слота эмбеддингов | Gauge |
138
+ | `embed_wait_time_seconds` | Время ожидания слота эмбеддингов (секунды) | Histogram |
139
+
140
+ ---
141
+
142
+ <a name="metrics"></a>
143
+
144
+ ## 3. Модуль `agent_lab_sdk.metrics`
145
+
146
+ Предоставляет удобный интерфейс для создания и управления метриками через Prometheus-клиент.
147
+
148
+ ### 3.1. Основные функции
149
+
150
+ ```python
151
+ from agent_lab_sdk.metrics import get_metric
152
+
153
+ # Создать метрику
154
+ g = get_metric(
155
+ metric_type="gauge", # тип: "gauge", "counter" или "histogram"
156
+ name="my_gauge", # имя метрики в Prometheus
157
+ documentation="Моя метрика gauge" # описание
158
+ )
159
+
160
+ # Увеличить счётчик
161
+ g.inc()
162
+
163
+ # Установить конкретное значение
164
+ g.set(42)
165
+ ```
166
+
167
+ ### 3.2. Пример использования в коде
168
+
169
+ ```python
170
+ from agent_lab_sdk.metrics import get_metric
171
+ import time
172
+
173
+ # Счётчик HTTP-запросов с метками
174
+ reqs = get_metric(
175
+ metric_type="counter",
176
+ name="http_requests_total",
177
+ documentation="Всего HTTP-запросов",
178
+ labelnames=["method", "endpoint"]
179
+ )
180
+ reqs.labels("GET", "/api").inc()
181
+
182
+ # Гистограмма задержек
183
+ lat = get_metric(
184
+ metric_type="histogram",
185
+ name="http_request_latency_seconds",
186
+ documentation="Длительность HTTP-запроса",
187
+ buckets=[0.1, 0.5, 1.0, 5.0]
188
+ )
189
+ with lat.time():
190
+ time.sleep(0.5)
191
+
192
+ print(reqs.collect())
193
+ print(lat.collect())
194
+ ```
195
+
196
+ ## 4. Хранилище
197
+
198
+ ### 4.1 SD Ассетница
199
+
200
+ функция `store_file_in_sd_asset` сохраняет base64‑файл в хранилище S3 и отдаёт публичную ссылку на файл
201
+
202
+ ```python
203
+ from agent_lab_sdk.storage import store_file_in_sd_asset
204
+
205
+ store_file_in_storage("my-agent-name-filename.png", file_b64, "giga-agents")
206
+ ```
207
+
208
+ ### 4.2 AGW Checkpointer
209
+
210
+ AGW поддерживает langgraph checkpoint API и в SDK представлен `AsyncAGWCheckpointSaver`, который позволяет сохранять состояние графа в AGW напрямую.
211
+
212
+ ## 5. Схема
213
+
214
+ TODO: описание LogMessage
215
+
216
+ ## 6. Сборка и публикация
217
+
218
+ 1. Установка twine
219
+
220
+ ```bash
221
+ pip install --upgrade build twine
222
+ ```
223
+
224
+ 2. Собрать и загрузить в pypi
225
+
226
+ перед обновлением сборки нужно не забыть поменять версию в [pyproject.toml](/pyproject.toml)
227
+ ```bash
228
+ python -m build && python -m twine upload dist/*
229
+ ```
230
+
231
+ 3. Ссылка на проект pypi
232
+
233
+ > https://pypi.org/project/agent-lab-sdk/
234
+
235
+ 4. установка локально в editable mode. Предварительно может потребоваться выбрать необходимое окружение
236
+ ```bash
237
+ pip install -e .
238
+ ```
239
+
240
+ # Примеры использования
241
+
242
+ TBD
@@ -0,0 +1,213 @@
1
+ # Agent Lab SDK
2
+
3
+ Набор утилит и обёрток для упрощённой работы с LLM, Agent Gateway и метриками в проектах Giga Labs.
4
+
5
+ ## Установка
6
+
7
+ ```bash
8
+ pip install agent_lab_sdk
9
+ ```
10
+
11
+ ## Содержание
12
+
13
+ 1. [Модуль `agent_lab_sdk.llm`](#1-модуль-agent_lab_sdkllm)
14
+ 2. [Модуль `agent_lab_sdk.llm.throttled`](#2-модуль-agent_lab_sdkllmthrottled)
15
+ 3. [Модуль `agent_lab_sdk.metrics`](#3-модуль-agent_lab_sdkmetrics)
16
+ 4. [Хранилище](#4-хранилище)
17
+ 5. [Схема](#5-схема)
18
+ 6. [Сборка и публикация](#6-сборка-и-публикация)
19
+
20
+ ---
21
+
22
+ ## 1. Модуль `agent_lab_sdk.llm`
23
+
24
+ ### 1.1. Получение модели
25
+
26
+ ```python
27
+ from agent_lab_sdk.llm import get_model
28
+
29
+ # Использует токен из окружения по умолчанию
30
+ model = get_model()
31
+
32
+ # Передача явных параметров
33
+ model = get_model(
34
+ access_token="YOUR_TOKEN",
35
+ timeout=60,
36
+ scope="GIGACHAT_API_CORP"
37
+ )
38
+ ```
39
+
40
+ > если не передавать access_token, токен будет выбран через GigaChatTokenManager
41
+
42
+ > планы на ближайшее будущее: get_model оборачивает внутри себя throttled классы.
43
+
44
+ ### 1.2. Менеджеры токенов
45
+
46
+ | Класс | Описание | Пример использования |
47
+ | ---------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
48
+ | `AgwTokenManager` | Кеширование + получение токена через Agent Gateway | `token = AgwTokenManager.get_token("provider")` |
49
+ | `GigaChatTokenManager` | Кеширование + получение через GigaChat OAuth с использованием пользовательских секретов | `token = GigaChatTokenManager.get_token()` |
50
+
51
+ ### 1.3. Переменные окружения
52
+
53
+ | Переменная | Описание | Значение по умолчанию / Пример |
54
+ | ---------------------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
55
+ | `GIGACHAT_SCOPE` | Scope GigaChat API | `GIGACHAT_API_PERS` |
56
+ | `GLOBAL_GIGACHAT_TIMEOUT` | Таймаут запросов к GigaChat (секунды) | `120` |
57
+ | `USE_TOKEN_PROVIDER_AGW` | Использовать `AgwTokenManager` | `true` |
58
+ | `GIGACHAT_CREDENTIALS` | Базовые креды для GigaChat (`b64(clientId:secretId)`) | `Y2xpZW50SWQ6c2VjcmV0SWQ=` |
59
+ | `GIGACHAT_TOKEN_PATH` | Путь к файлу кеша токена GigaChat | `/tmp/gigachat_token.json` |
60
+ | `GIGACHAT_TOKEN_FETCH_RETRIES` | Количество попыток получения токена (GigaChat) | `3` |
61
+ | `USE_GIGACHAT_ADVANCED` | Включает запрос токена GigaChat API в продвинутом режиме | `true` |
62
+ | `GIGACHAT_BASE_URL` | Базовый URL GigaChat для расширенного режима | `https://ngw.devices.sberbank.ru:9443/api/v2/oauth` |
63
+ | `TOKEN_PROVIDER_AGW_URL` | URL Agent Gateway для получения AGW-токена | `https://agent-gateway.apps.advosd.sberdevices.ru` |
64
+ | `TOKEN_PROVIDER_AGW_DEFAULT_MAX_RETRIES` | Макс. попыток запроса токена (AGW) | `3` |
65
+ | `TOKEN_PROVIDER_AGW_TIMEOUT_SEC` | Таймаут запроса к AGW (секунды) | `5` |
66
+
67
+ ---
68
+
69
+ <a name="throttled"></a>
70
+
71
+ ## 2. Модуль `agent_lab_sdk.llm.throttled`
72
+
73
+ Позволяет ограничивать число одновременных вызовов к GigaChat и сервису эмбеддингов, автоматически собирая соответствующие метрики.
74
+
75
+ ```python
76
+ from agent_lab_sdk.llm import GigaChatTokenManager
77
+ from agent_lab_sdk.llm.throttled import ThrottledGigaChat, ThrottledGigaChatEmbeddings
78
+
79
+ access_token = GigaChatTokenManager.get_token()
80
+
81
+ # Чат с учётом ограничений
82
+ chat = ThrottledGigaChat(access_token=access_token)
83
+ response = chat.invoke("Привет!")
84
+
85
+ # Эмбеддинги с учётом ограничений
86
+ emb = ThrottledGigaChatEmbeddings(access_token=access_token)
87
+ vectors = emb.embed_documents(["Text1", "Text2"])
88
+ ```
89
+
90
+ ### 2.1. Переменные окружения для ограничения
91
+
92
+ | Переменная | Описание | Значение по умолчанию |
93
+ | --------------------------------- | ------------------------------------------- | --------------------- |
94
+ | `MAX_CHAT_CONCURRENCY` | Максимум одновременных чат-запросов | `100000` |
95
+ | `MAX_EMBED_CONCURRENCY` | Максимум одновременных запросов эмбеддингов | `100000` |
96
+ | `EMBEDDINGS_MAX_BATCH_SIZE_PARTS` | Макс. размер батча частей для эмбеддингов | `90` |
97
+
98
+ ### 2.2. Метрики
99
+
100
+ Метрики доступны через `agent_lab_sdk.metrics.get_metric`:
101
+
102
+ | Метрика | Описание | Тип |
103
+ | ------------------------- | ---------------------------------------------- | --------- |
104
+ | `chat_slots_in_use` | Число занятых слотов для чата | Gauge |
105
+ | `chat_waiting_tasks` | Число задач, ожидающих освобождения слота чата | Gauge |
106
+ | `chat_wait_time_seconds` | Время ожидания слота чата (секунды) | Histogram |
107
+ | `embed_slots_in_use` | Число занятых слотов для эмбеддингов | Gauge |
108
+ | `embed_waiting_tasks` | Число задач, ожидающих слота эмбеддингов | Gauge |
109
+ | `embed_wait_time_seconds` | Время ожидания слота эмбеддингов (секунды) | Histogram |
110
+
111
+ ---
112
+
113
+ <a name="metrics"></a>
114
+
115
+ ## 3. Модуль `agent_lab_sdk.metrics`
116
+
117
+ Предоставляет удобный интерфейс для создания и управления метриками через Prometheus-клиент.
118
+
119
+ ### 3.1. Основные функции
120
+
121
+ ```python
122
+ from agent_lab_sdk.metrics import get_metric
123
+
124
+ # Создать метрику
125
+ g = get_metric(
126
+ metric_type="gauge", # тип: "gauge", "counter" или "histogram"
127
+ name="my_gauge", # имя метрики в Prometheus
128
+ documentation="Моя метрика gauge" # описание
129
+ )
130
+
131
+ # Увеличить счётчик
132
+ g.inc()
133
+
134
+ # Установить конкретное значение
135
+ g.set(42)
136
+ ```
137
+
138
+ ### 3.2. Пример использования в коде
139
+
140
+ ```python
141
+ from agent_lab_sdk.metrics import get_metric
142
+ import time
143
+
144
+ # Счётчик HTTP-запросов с метками
145
+ reqs = get_metric(
146
+ metric_type="counter",
147
+ name="http_requests_total",
148
+ documentation="Всего HTTP-запросов",
149
+ labelnames=["method", "endpoint"]
150
+ )
151
+ reqs.labels("GET", "/api").inc()
152
+
153
+ # Гистограмма задержек
154
+ lat = get_metric(
155
+ metric_type="histogram",
156
+ name="http_request_latency_seconds",
157
+ documentation="Длительность HTTP-запроса",
158
+ buckets=[0.1, 0.5, 1.0, 5.0]
159
+ )
160
+ with lat.time():
161
+ time.sleep(0.5)
162
+
163
+ print(reqs.collect())
164
+ print(lat.collect())
165
+ ```
166
+
167
+ ## 4. Хранилище
168
+
169
+ ### 4.1 SD Ассетница
170
+
171
+ функция `store_file_in_sd_asset` сохраняет base64‑файл в хранилище S3 и отдаёт публичную ссылку на файл
172
+
173
+ ```python
174
+ from agent_lab_sdk.storage import store_file_in_sd_asset
175
+
176
+ store_file_in_storage("my-agent-name-filename.png", file_b64, "giga-agents")
177
+ ```
178
+
179
+ ### 4.2 AGW Checkpointer
180
+
181
+ AGW поддерживает langgraph checkpoint API и в SDK представлен `AsyncAGWCheckpointSaver`, который позволяет сохранять состояние графа в AGW напрямую.
182
+
183
+ ## 5. Схема
184
+
185
+ TODO: описание LogMessage
186
+
187
+ ## 6. Сборка и публикация
188
+
189
+ 1. Установка twine
190
+
191
+ ```bash
192
+ pip install --upgrade build twine
193
+ ```
194
+
195
+ 2. Собрать и загрузить в pypi
196
+
197
+ перед обновлением сборки нужно не забыть поменять версию в [pyproject.toml](/pyproject.toml)
198
+ ```bash
199
+ python -m build && python -m twine upload dist/*
200
+ ```
201
+
202
+ 3. Ссылка на проект pypi
203
+
204
+ > https://pypi.org/project/agent-lab-sdk/
205
+
206
+ 4. установка локально в editable mode. Предварительно может потребоваться выбрать необходимое окружение
207
+ ```bash
208
+ pip install -e .
209
+ ```
210
+
211
+ # Примеры использования
212
+
213
+ TBD
@@ -0,0 +1,242 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-lab-sdk
3
+ Version: 0.1.15
4
+ Summary: SDK для работы с Agent Lab
5
+ Author-email: Andrew Ohurtsov <andermirik@yandex.com>
6
+ License: Proprietary and Confidential — All Rights Reserved
7
+ Keywords: agent,lab,sdk
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Software Development :: Libraries
11
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: License :: Other/Proprietary License
17
+ Classifier: Operating System :: OS Independent
18
+ Requires-Python: <4.0,>=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: requests
22
+ Requires-Dist: langgraph~=0.4.1
23
+ Requires-Dist: langchain_gigachat
24
+ Requires-Dist: prometheus-client
25
+ Requires-Dist: langchain
26
+ Requires-Dist: httpx~=0.27.2
27
+ Requires-Dist: orjson>=3.9.7
28
+ Dynamic: license-file
29
+
30
+ # Agent Lab SDK
31
+
32
+ Набор утилит и обёрток для упрощённой работы с LLM, Agent Gateway и метриками в проектах Giga Labs.
33
+
34
+ ## Установка
35
+
36
+ ```bash
37
+ pip install agent_lab_sdk
38
+ ```
39
+
40
+ ## Содержание
41
+
42
+ 1. [Модуль `agent_lab_sdk.llm`](#1-модуль-agent_lab_sdkllm)
43
+ 2. [Модуль `agent_lab_sdk.llm.throttled`](#2-модуль-agent_lab_sdkllmthrottled)
44
+ 3. [Модуль `agent_lab_sdk.metrics`](#3-модуль-agent_lab_sdkmetrics)
45
+ 4. [Хранилище](#4-хранилище)
46
+ 5. [Схема](#5-схема)
47
+ 6. [Сборка и публикация](#6-сборка-и-публикация)
48
+
49
+ ---
50
+
51
+ ## 1. Модуль `agent_lab_sdk.llm`
52
+
53
+ ### 1.1. Получение модели
54
+
55
+ ```python
56
+ from agent_lab_sdk.llm import get_model
57
+
58
+ # Использует токен из окружения по умолчанию
59
+ model = get_model()
60
+
61
+ # Передача явных параметров
62
+ model = get_model(
63
+ access_token="YOUR_TOKEN",
64
+ timeout=60,
65
+ scope="GIGACHAT_API_CORP"
66
+ )
67
+ ```
68
+
69
+ > если не передавать access_token, токен будет выбран через GigaChatTokenManager
70
+
71
+ > планы на ближайшее будущее: get_model оборачивает внутри себя throttled классы.
72
+
73
+ ### 1.2. Менеджеры токенов
74
+
75
+ | Класс | Описание | Пример использования |
76
+ | ---------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
77
+ | `AgwTokenManager` | Кеширование + получение токена через Agent Gateway | `token = AgwTokenManager.get_token("provider")` |
78
+ | `GigaChatTokenManager` | Кеширование + получение через GigaChat OAuth с использованием пользовательских секретов | `token = GigaChatTokenManager.get_token()` |
79
+
80
+ ### 1.3. Переменные окружения
81
+
82
+ | Переменная | Описание | Значение по умолчанию / Пример |
83
+ | ---------------------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
84
+ | `GIGACHAT_SCOPE` | Scope GigaChat API | `GIGACHAT_API_PERS` |
85
+ | `GLOBAL_GIGACHAT_TIMEOUT` | Таймаут запросов к GigaChat (секунды) | `120` |
86
+ | `USE_TOKEN_PROVIDER_AGW` | Использовать `AgwTokenManager` | `true` |
87
+ | `GIGACHAT_CREDENTIALS` | Базовые креды для GigaChat (`b64(clientId:secretId)`) | `Y2xpZW50SWQ6c2VjcmV0SWQ=` |
88
+ | `GIGACHAT_TOKEN_PATH` | Путь к файлу кеша токена GigaChat | `/tmp/gigachat_token.json` |
89
+ | `GIGACHAT_TOKEN_FETCH_RETRIES` | Количество попыток получения токена (GigaChat) | `3` |
90
+ | `USE_GIGACHAT_ADVANCED` | Включает запрос токена GigaChat API в продвинутом режиме | `true` |
91
+ | `GIGACHAT_BASE_URL` | Базовый URL GigaChat для расширенного режима | `https://ngw.devices.sberbank.ru:9443/api/v2/oauth` |
92
+ | `TOKEN_PROVIDER_AGW_URL` | URL Agent Gateway для получения AGW-токена | `https://agent-gateway.apps.advosd.sberdevices.ru` |
93
+ | `TOKEN_PROVIDER_AGW_DEFAULT_MAX_RETRIES` | Макс. попыток запроса токена (AGW) | `3` |
94
+ | `TOKEN_PROVIDER_AGW_TIMEOUT_SEC` | Таймаут запроса к AGW (секунды) | `5` |
95
+
96
+ ---
97
+
98
+ <a name="throttled"></a>
99
+
100
+ ## 2. Модуль `agent_lab_sdk.llm.throttled`
101
+
102
+ Позволяет ограничивать число одновременных вызовов к GigaChat и сервису эмбеддингов, автоматически собирая соответствующие метрики.
103
+
104
+ ```python
105
+ from agent_lab_sdk.llm import GigaChatTokenManager
106
+ from agent_lab_sdk.llm.throttled import ThrottledGigaChat, ThrottledGigaChatEmbeddings
107
+
108
+ access_token = GigaChatTokenManager.get_token()
109
+
110
+ # Чат с учётом ограничений
111
+ chat = ThrottledGigaChat(access_token=access_token)
112
+ response = chat.invoke("Привет!")
113
+
114
+ # Эмбеддинги с учётом ограничений
115
+ emb = ThrottledGigaChatEmbeddings(access_token=access_token)
116
+ vectors = emb.embed_documents(["Text1", "Text2"])
117
+ ```
118
+
119
+ ### 2.1. Переменные окружения для ограничения
120
+
121
+ | Переменная | Описание | Значение по умолчанию |
122
+ | --------------------------------- | ------------------------------------------- | --------------------- |
123
+ | `MAX_CHAT_CONCURRENCY` | Максимум одновременных чат-запросов | `100000` |
124
+ | `MAX_EMBED_CONCURRENCY` | Максимум одновременных запросов эмбеддингов | `100000` |
125
+ | `EMBEDDINGS_MAX_BATCH_SIZE_PARTS` | Макс. размер батча частей для эмбеддингов | `90` |
126
+
127
+ ### 2.2. Метрики
128
+
129
+ Метрики доступны через `agent_lab_sdk.metrics.get_metric`:
130
+
131
+ | Метрика | Описание | Тип |
132
+ | ------------------------- | ---------------------------------------------- | --------- |
133
+ | `chat_slots_in_use` | Число занятых слотов для чата | Gauge |
134
+ | `chat_waiting_tasks` | Число задач, ожидающих освобождения слота чата | Gauge |
135
+ | `chat_wait_time_seconds` | Время ожидания слота чата (секунды) | Histogram |
136
+ | `embed_slots_in_use` | Число занятых слотов для эмбеддингов | Gauge |
137
+ | `embed_waiting_tasks` | Число задач, ожидающих слота эмбеддингов | Gauge |
138
+ | `embed_wait_time_seconds` | Время ожидания слота эмбеддингов (секунды) | Histogram |
139
+
140
+ ---
141
+
142
+ <a name="metrics"></a>
143
+
144
+ ## 3. Модуль `agent_lab_sdk.metrics`
145
+
146
+ Предоставляет удобный интерфейс для создания и управления метриками через Prometheus-клиент.
147
+
148
+ ### 3.1. Основные функции
149
+
150
+ ```python
151
+ from agent_lab_sdk.metrics import get_metric
152
+
153
+ # Создать метрику
154
+ g = get_metric(
155
+ metric_type="gauge", # тип: "gauge", "counter" или "histogram"
156
+ name="my_gauge", # имя метрики в Prometheus
157
+ documentation="Моя метрика gauge" # описание
158
+ )
159
+
160
+ # Увеличить счётчик
161
+ g.inc()
162
+
163
+ # Установить конкретное значение
164
+ g.set(42)
165
+ ```
166
+
167
+ ### 3.2. Пример использования в коде
168
+
169
+ ```python
170
+ from agent_lab_sdk.metrics import get_metric
171
+ import time
172
+
173
+ # Счётчик HTTP-запросов с метками
174
+ reqs = get_metric(
175
+ metric_type="counter",
176
+ name="http_requests_total",
177
+ documentation="Всего HTTP-запросов",
178
+ labelnames=["method", "endpoint"]
179
+ )
180
+ reqs.labels("GET", "/api").inc()
181
+
182
+ # Гистограмма задержек
183
+ lat = get_metric(
184
+ metric_type="histogram",
185
+ name="http_request_latency_seconds",
186
+ documentation="Длительность HTTP-запроса",
187
+ buckets=[0.1, 0.5, 1.0, 5.0]
188
+ )
189
+ with lat.time():
190
+ time.sleep(0.5)
191
+
192
+ print(reqs.collect())
193
+ print(lat.collect())
194
+ ```
195
+
196
+ ## 4. Хранилище
197
+
198
+ ### 4.1 SD Ассетница
199
+
200
+ функция `store_file_in_sd_asset` сохраняет base64‑файл в хранилище S3 и отдаёт публичную ссылку на файл
201
+
202
+ ```python
203
+ from agent_lab_sdk.storage import store_file_in_sd_asset
204
+
205
+ store_file_in_storage("my-agent-name-filename.png", file_b64, "giga-agents")
206
+ ```
207
+
208
+ ### 4.2 AGW Checkpointer
209
+
210
+ AGW поддерживает langgraph checkpoint API и в SDK представлен `AsyncAGWCheckpointSaver`, который позволяет сохранять состояние графа в AGW напрямую.
211
+
212
+ ## 5. Схема
213
+
214
+ TODO: описание LogMessage
215
+
216
+ ## 6. Сборка и публикация
217
+
218
+ 1. Установка twine
219
+
220
+ ```bash
221
+ pip install --upgrade build twine
222
+ ```
223
+
224
+ 2. Собрать и загрузить в pypi
225
+
226
+ перед обновлением сборки нужно не забыть поменять версию в [pyproject.toml](/pyproject.toml)
227
+ ```bash
228
+ python -m build && python -m twine upload dist/*
229
+ ```
230
+
231
+ 3. Ссылка на проект pypi
232
+
233
+ > https://pypi.org/project/agent-lab-sdk/
234
+
235
+ 4. установка локально в editable mode. Предварительно может потребоваться выбрать необходимое окружение
236
+ ```bash
237
+ pip install -e .
238
+ ```
239
+
240
+ # Примеры использования
241
+
242
+ TBD
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "agent-lab-sdk"
7
- version = "0.1.14"
7
+ version = "0.1.15"
8
8
  description = "SDK для работы с Agent Lab"
9
9
  readme = "README.md"
10
10
  license = { text = "Proprietary and Confidential — All Rights Reserved" }
@@ -1,65 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: agent-lab-sdk
3
- Version: 0.1.14
4
- Summary: SDK для работы с Agent Lab
5
- Author-email: Andrew Ohurtsov <andermirik@yandex.com>
6
- License: Proprietary and Confidential — All Rights Reserved
7
- Keywords: agent,lab,sdk
8
- Classifier: Development Status :: 4 - Beta
9
- Classifier: Intended Audience :: Developers
10
- Classifier: Topic :: Software Development :: Libraries
11
- Classifier: Topic :: Software Development :: Libraries :: Python Modules
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.11
14
- Classifier: Programming Language :: Python :: 3.12
15
- Classifier: Programming Language :: Python :: 3.13
16
- Classifier: License :: Other/Proprietary License
17
- Classifier: Operating System :: OS Independent
18
- Requires-Python: <4.0,>=3.11
19
- Description-Content-Type: text/markdown
20
- License-File: LICENSE
21
- Requires-Dist: requests
22
- Requires-Dist: langgraph~=0.4.1
23
- Requires-Dist: langchain_gigachat
24
- Requires-Dist: prometheus-client
25
- Requires-Dist: langchain
26
- Requires-Dist: httpx~=0.27.2
27
- Requires-Dist: orjson>=3.9.7
28
- Dynamic: license-file
29
-
30
- # Agent Lab SDK
31
-
32
- Набор утилит и обёрток для работы с LLM, AGW и метриками в проектах Agent Lab.
33
-
34
- ---
35
-
36
- 1. Установка twine
37
-
38
- ```
39
- pip install --upgrade build twine
40
- ```
41
-
42
- 2. Собрать и загрузить в pypi
43
-
44
- перед обновлением сборки нужно не забыть поменять версию в pyproject.toml
45
- ```
46
- python -m build && python -m twine upload dist/*
47
- ```
48
-
49
- 3. Ссылка на проект pypi
50
-
51
- > https://pypi.org/project/agent-lab-sdk/
52
-
53
- 4. установка локально
54
- ```
55
- pip install -e .
56
- ```
57
-
58
- 5. установка из интернета
59
- ```
60
- pip install agent-lab-sdk
61
- ```
62
-
63
- # Примеры использования
64
-
65
- TBD
@@ -1,36 +0,0 @@
1
- # Agent Lab SDK
2
-
3
- Набор утилит и обёрток для работы с LLM, AGW и метриками в проектах Agent Lab.
4
-
5
- ---
6
-
7
- 1. Установка twine
8
-
9
- ```
10
- pip install --upgrade build twine
11
- ```
12
-
13
- 2. Собрать и загрузить в pypi
14
-
15
- перед обновлением сборки нужно не забыть поменять версию в pyproject.toml
16
- ```
17
- python -m build && python -m twine upload dist/*
18
- ```
19
-
20
- 3. Ссылка на проект pypi
21
-
22
- > https://pypi.org/project/agent-lab-sdk/
23
-
24
- 4. установка локально
25
- ```
26
- pip install -e .
27
- ```
28
-
29
- 5. установка из интернета
30
- ```
31
- pip install agent-lab-sdk
32
- ```
33
-
34
- # Примеры использования
35
-
36
- TBD
@@ -1,65 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: agent-lab-sdk
3
- Version: 0.1.14
4
- Summary: SDK для работы с Agent Lab
5
- Author-email: Andrew Ohurtsov <andermirik@yandex.com>
6
- License: Proprietary and Confidential — All Rights Reserved
7
- Keywords: agent,lab,sdk
8
- Classifier: Development Status :: 4 - Beta
9
- Classifier: Intended Audience :: Developers
10
- Classifier: Topic :: Software Development :: Libraries
11
- Classifier: Topic :: Software Development :: Libraries :: Python Modules
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.11
14
- Classifier: Programming Language :: Python :: 3.12
15
- Classifier: Programming Language :: Python :: 3.13
16
- Classifier: License :: Other/Proprietary License
17
- Classifier: Operating System :: OS Independent
18
- Requires-Python: <4.0,>=3.11
19
- Description-Content-Type: text/markdown
20
- License-File: LICENSE
21
- Requires-Dist: requests
22
- Requires-Dist: langgraph~=0.4.1
23
- Requires-Dist: langchain_gigachat
24
- Requires-Dist: prometheus-client
25
- Requires-Dist: langchain
26
- Requires-Dist: httpx~=0.27.2
27
- Requires-Dist: orjson>=3.9.7
28
- Dynamic: license-file
29
-
30
- # Agent Lab SDK
31
-
32
- Набор утилит и обёрток для работы с LLM, AGW и метриками в проектах Agent Lab.
33
-
34
- ---
35
-
36
- 1. Установка twine
37
-
38
- ```
39
- pip install --upgrade build twine
40
- ```
41
-
42
- 2. Собрать и загрузить в pypi
43
-
44
- перед обновлением сборки нужно не забыть поменять версию в pyproject.toml
45
- ```
46
- python -m build && python -m twine upload dist/*
47
- ```
48
-
49
- 3. Ссылка на проект pypi
50
-
51
- > https://pypi.org/project/agent-lab-sdk/
52
-
53
- 4. установка локально
54
- ```
55
- pip install -e .
56
- ```
57
-
58
- 5. установка из интернета
59
- ```
60
- pip install agent-lab-sdk
61
- ```
62
-
63
- # Примеры использования
64
-
65
- TBD
File without changes
File without changes