event-extraction-agent 1.0.0__tar.gz

event_extraction_agent-1.0.0/LICENSE

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

event_extraction_agent-1.0.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: event-extraction-agent
+Version: 1.0.0
+Summary: Python library for extracting structured event data from text posts with LLM agents.
+Author: event-extraction-agent contributors
+License: MIT License
+        
+        Copyright (c) 2026 Slava Tyutyunov
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/olivoreo/event-extraction-agent
+Project-URL: Repository, https://github.com/olivoreo/event-extraction-agent
+Project-URL: Issues, https://github.com/olivoreo/event-extraction-agent/issues
+Project-URL: Source, https://github.com/olivoreo/event-ai-agent
+Keywords: event extraction,llm,structured data,vk,pipeline
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# event_extraction_agent
+
+`event_extraction_agent` - Python-библиотека для извлечения структурированных данных о мероприятиях из текстовых постов с помощью LLM.
+
+Главный и стабильный способ использования - `ExtractionPipeline`: вы передаете источник постов и `ExtractionAgentConfig`, а на выходе получаете `BatchExtractionResult` со всеми событиями, статусами, ошибками и методами сохранения результата.
+
+## Установка
+
+```bash
+pip install event-extraction-agent
+```
+
+Для локальной разработки из репозитория:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Быстрый старт
+
+```python
+from event_extraction_agent import (
+    ExtractionAgentConfig,
+    ExtractionPipeline,
+    OllamaChatClient,
+    SourcePost,
+)
+
+
+class MySource:
+    def fetch_posts(self) -> list[SourcePost]:
+        return [
+            SourcePost(
+                text="12 июня в 18:00 пройдет открытая лекция.",
+                source_name="Example source",
+                source_url="https://example.com/posts/123",
+                published_at="2026-06-01T10:00:00+03:00",
+                external_id="post-123",
+            )
+        ]
+
+
+pipeline = ExtractionPipeline(
+    source=MySource(),
+    agent_config=ExtractionAgentConfig(
+        main_client=OllamaChatClient(model="qwen2.5:3b"),
+    ),
+)
+
+result = pipeline.run()
+
+for outcome in result.outcomes:
+    if outcome.event:
+        print(outcome.event.model_dump(mode="json"))
+    else:
+        print(outcome.status, outcome.errors)
+```
+
+Минимально в `ExtractionAgentConfig` нужно передать `main_client`. Если `refinement_client` не задан, уточнение типа события выполняется тем же клиентом.
+
+## Сохранение результата
+
+`pipeline.run()` возвращает `BatchExtractionResult`. Его можно сохранить в JSON:
+
+```python
+result = pipeline.run()
+result.save_json("events_result.json")
+```
+
+И загрузить обратно:
+
+```python
+from event_extraction_agent import BatchExtractionResult
+
+previous = BatchExtractionResult.load_json("events_result.json")
+```
+
+## Incremental processing
+
+Pipeline может сам загрузить предыдущий результат и сохранить новый:
+
+```python
+pipeline = ExtractionPipeline(
+    source=source,
+    agent_config=agent_config,
+    previous_result_path="events_result.json",
+    save_result_path="events_result.json",
+)
+
+result = pipeline.run()
+print(result.cached, result.processed)
+```
+
+Incremental-режим пропускает LLM extraction, если у нового поста совпали `external_id` и нормализованный текст для LLM (`raw_text`, если он задан, иначе `text`) с предыдущим результатом. Результаты со статусом `llm_error` по умолчанию обрабатываются повторно.
+
+## VK source
+
+Для VK есть готовый source adapter:
+
+```python
+from event_extraction_agent import ExtractionAgentConfig, ExtractionPipeline, OllamaChatClient, VKSource
+
+source = VKSource(
+    access_token="vk-service-token",
+    sources=[
+        "https://vk.com/club123",
+        "public456",
+        "my_community_domain",
+        -789,
+    ],
+    posts_per_source_limit=20,
+)
+
+result = ExtractionPipeline(
+    source=source,
+    agent_config=ExtractionAgentConfig(
+        main_client=OllamaChatClient(model="qwen2.5:3b"),
+    ),
+    previous_result_path="events_result.json",
+    save_result_path="events_result.json",
+).run()
+```
+
+`VKSource` получает посты через `wall.get`, очищает текст для LLM, добавляет `source_name`, `source_url`, `published_at`, `external_id` и возвращает список `SourcePost`.
+
+Если один VK source недоступен, остальные источники по умолчанию продолжают обрабатываться. Ошибки доступны через `source.errors` или `fetch_posts_with_errors()`:
+
+```python
+fetch_result = source.fetch_posts_with_errors()
+
+for error in fetch_result.errors:
+    print(error.source, error.code, error)
+```
+
+По умолчанию `VKSource` использует rate limit `20` запросов в секунду и retry/backoff для временных ошибок VK, HTTP `429`/`5xx` и сетевых сбоев.
+
+## Настройка агента
+
+Все настройки LLM и extraction-поведения передаются через `ExtractionAgentConfig`:
+
+```python
+config = ExtractionAgentConfig(
+    main_client=main_client,
+    refinement_client=refinement_client,
+    use_event_type_refinement=True,
+    current_datetime="2026-06-10T12:00:00+03:00",
+    min_request_interval_seconds=2.1,
+    max_retries=1,
+)
+```
+
+Поддерживается любой LLM-клиент с методом:
+
+```python
+complete(system_prompt: str, user_prompt: str) -> str
+```
+
+В пакете есть готовые клиенты:
+
+- `OllamaChatClient`
+- `GroqChatClient`
+
+## Что возвращает pipeline
+
+`BatchExtractionResult` содержит:
+
+- `outcomes`: результаты по каждому посту;
+- `extracted`, `skipped`, `invalid`, `llm_errors`: счетчики статусов;
+- `cached`, `processed`: счетчики incremental-режима;
+- `error_count`, `error_limit_reached`: информация о batch-лимитах;
+- `save_json(path)` и `load_json(path)`.
+
+Каждый `ExtractionOutcome` содержит исходный `SourcePost`, статус обработки, найденное `Event` или структурированные ошибки.
+
+## Границы пакета
+
+В пакет входит extraction-ядро, pipeline, модели, LLM-клиенты для Ollama/Groq и VK source adapter.
+
+Пакет намеренно не включает:
+
+- базу данных;
+- HTTP API;
+- расписания;
+- чтение секретов из `.env`;
+- обработку VK-вложений;
+- source adapters кроме VK.
+
+Приложение, которое использует библиотеку, отвечает за конфигурацию, секреты, хранение данных и собственные источники.
+
+## Происхождение пакета
+
+`event_extraction_agent` выделен из проекта [olivoreo/event-ai-agent](https://github.com/olivoreo/event-ai-agent). Из исходного проекта перенесено extraction-ядро: модели события, промпты, валидация, исправление ответа LLM и клиенты для Ollama/Groq.
+
+При переносе намеренно не включались backend API, база данных, загрузчики внешних источников и экспериментальные ML-компоненты. Цель пакета - сделать extraction-логику переиспользуемой в других проектах.

event_extraction_agent-1.0.0/README.md

@@ -0,0 +1,195 @@
+# event_extraction_agent
+
+`event_extraction_agent` - Python-библиотека для извлечения структурированных данных о мероприятиях из текстовых постов с помощью LLM.
+
+Главный и стабильный способ использования - `ExtractionPipeline`: вы передаете источник постов и `ExtractionAgentConfig`, а на выходе получаете `BatchExtractionResult` со всеми событиями, статусами, ошибками и методами сохранения результата.
+
+## Установка
+
+```bash
+pip install event-extraction-agent
+```
+
+Для локальной разработки из репозитория:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Быстрый старт
+
+```python
+from event_extraction_agent import (
+    ExtractionAgentConfig,
+    ExtractionPipeline,
+    OllamaChatClient,
+    SourcePost,
+)
+
+
+class MySource:
+    def fetch_posts(self) -> list[SourcePost]:
+        return [
+            SourcePost(
+                text="12 июня в 18:00 пройдет открытая лекция.",
+                source_name="Example source",
+                source_url="https://example.com/posts/123",
+                published_at="2026-06-01T10:00:00+03:00",
+                external_id="post-123",
+            )
+        ]
+
+
+pipeline = ExtractionPipeline(
+    source=MySource(),
+    agent_config=ExtractionAgentConfig(
+        main_client=OllamaChatClient(model="qwen2.5:3b"),
+    ),
+)
+
+result = pipeline.run()
+
+for outcome in result.outcomes:
+    if outcome.event:
+        print(outcome.event.model_dump(mode="json"))
+    else:
+        print(outcome.status, outcome.errors)
+```
+
+Минимально в `ExtractionAgentConfig` нужно передать `main_client`. Если `refinement_client` не задан, уточнение типа события выполняется тем же клиентом.
+
+## Сохранение результата
+
+`pipeline.run()` возвращает `BatchExtractionResult`. Его можно сохранить в JSON:
+
+```python
+result = pipeline.run()
+result.save_json("events_result.json")
+```
+
+И загрузить обратно:
+
+```python
+from event_extraction_agent import BatchExtractionResult
+
+previous = BatchExtractionResult.load_json("events_result.json")
+```
+
+## Incremental processing
+
+Pipeline может сам загрузить предыдущий результат и сохранить новый:
+
+```python
+pipeline = ExtractionPipeline(
+    source=source,
+    agent_config=agent_config,
+    previous_result_path="events_result.json",
+    save_result_path="events_result.json",
+)
+
+result = pipeline.run()
+print(result.cached, result.processed)
+```
+
+Incremental-режим пропускает LLM extraction, если у нового поста совпали `external_id` и нормализованный текст для LLM (`raw_text`, если он задан, иначе `text`) с предыдущим результатом. Результаты со статусом `llm_error` по умолчанию обрабатываются повторно.
+
+## VK source
+
+Для VK есть готовый source adapter:
+
+```python
+from event_extraction_agent import ExtractionAgentConfig, ExtractionPipeline, OllamaChatClient, VKSource
+
+source = VKSource(
+    access_token="vk-service-token",
+    sources=[
+        "https://vk.com/club123",
+        "public456",
+        "my_community_domain",
+        -789,
+    ],
+    posts_per_source_limit=20,
+)
+
+result = ExtractionPipeline(
+    source=source,
+    agent_config=ExtractionAgentConfig(
+        main_client=OllamaChatClient(model="qwen2.5:3b"),
+    ),
+    previous_result_path="events_result.json",
+    save_result_path="events_result.json",
+).run()
+```
+
+`VKSource` получает посты через `wall.get`, очищает текст для LLM, добавляет `source_name`, `source_url`, `published_at`, `external_id` и возвращает список `SourcePost`.
+
+Если один VK source недоступен, остальные источники по умолчанию продолжают обрабатываться. Ошибки доступны через `source.errors` или `fetch_posts_with_errors()`:
+
+```python
+fetch_result = source.fetch_posts_with_errors()
+
+for error in fetch_result.errors:
+    print(error.source, error.code, error)
+```
+
+По умолчанию `VKSource` использует rate limit `20` запросов в секунду и retry/backoff для временных ошибок VK, HTTP `429`/`5xx` и сетевых сбоев.
+
+## Настройка агента
+
+Все настройки LLM и extraction-поведения передаются через `ExtractionAgentConfig`:
+
+```python
+config = ExtractionAgentConfig(
+    main_client=main_client,
+    refinement_client=refinement_client,
+    use_event_type_refinement=True,
+    current_datetime="2026-06-10T12:00:00+03:00",
+    min_request_interval_seconds=2.1,
+    max_retries=1,
+)
+```
+
+Поддерживается любой LLM-клиент с методом:
+
+```python
+complete(system_prompt: str, user_prompt: str) -> str
+```
+
+В пакете есть готовые клиенты:
+
+- `OllamaChatClient`
+- `GroqChatClient`
+
+## Что возвращает pipeline
+
+`BatchExtractionResult` содержит:
+
+- `outcomes`: результаты по каждому посту;
+- `extracted`, `skipped`, `invalid`, `llm_errors`: счетчики статусов;
+- `cached`, `processed`: счетчики incremental-режима;
+- `error_count`, `error_limit_reached`: информация о batch-лимитах;
+- `save_json(path)` и `load_json(path)`.
+
+Каждый `ExtractionOutcome` содержит исходный `SourcePost`, статус обработки, найденное `Event` или структурированные ошибки.
+
+## Границы пакета
+
+В пакет входит extraction-ядро, pipeline, модели, LLM-клиенты для Ollama/Groq и VK source adapter.
+
+Пакет намеренно не включает:
+
+- базу данных;
+- HTTP API;
+- расписания;
+- чтение секретов из `.env`;
+- обработку VK-вложений;
+- source adapters кроме VK.
+
+Приложение, которое использует библиотеку, отвечает за конфигурацию, секреты, хранение данных и собственные источники.
+
+## Происхождение пакета
+
+`event_extraction_agent` выделен из проекта [olivoreo/event-ai-agent](https://github.com/olivoreo/event-ai-agent). Из исходного проекта перенесено extraction-ядро: модели события, промпты, валидация, исправление ответа LLM и клиенты для Ollama/Groq.
+
+При переносе намеренно не включались backend API, база данных, загрузчики внешних источников и экспериментальные ML-компоненты. Цель пакета - сделать extraction-логику переиспользуемой в других проектах.

event_extraction_agent-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "event-extraction-agent"
+version = "1.0.0"
+description = "Python library for extracting structured event data from text posts with LLM agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "event-extraction-agent contributors" }
+]
+keywords = ["event extraction", "llm", "structured data", "vk", "pipeline"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+dependencies = [
+  "pydantic>=2,<3"
+]
+
+[project.urls]
+Homepage = "https://github.com/olivoreo/event-extraction-agent"
+Repository = "https://github.com/olivoreo/event-extraction-agent"
+Issues = "https://github.com/olivoreo/event-extraction-agent/issues"
+Source = "https://github.com/olivoreo/event-ai-agent"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+event_extraction_agent = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

event_extraction_agent-1.0.0/setup.cfg

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

event_extraction_agent-1.0.0/src/event_extraction_agent/__init__.py

@@ -0,0 +1,55 @@
+"""Public API for the event extraction package."""
+
+from event_extraction_agent.agent import (
+    ExtractionAgent,
+    GroqChatClient,
+    LLMClient,
+    OllamaChatClient,
+)
+from event_extraction_agent.models import (
+    AttendanceType,
+    BatchExtractionResult,
+    BatchExtractionSettings,
+    BatchMode,
+    Event,
+    EventStatus,
+    EventType,
+    ExtractionAgentConfig,
+    ExtractionError,
+    ExtractionOutcome,
+    ExtractionStatus,
+    SourcePost,
+)
+from event_extraction_agent.pipeline import ExtractionPipeline
+from event_extraction_agent.sources import SourceAdapter
+from event_extraction_agent.vk import (
+    VKApiError,
+    VKFetchResult,
+    VKPostSource,
+    VKSource,
+)
+
+__all__ = [
+    "AttendanceType",
+    "BatchExtractionResult",
+    "BatchExtractionSettings",
+    "BatchMode",
+    "Event",
+    "EventStatus",
+    "EventType",
+    "ExtractionAgentConfig",
+    "ExtractionAgent",
+    "ExtractionError",
+    "ExtractionOutcome",
+    "ExtractionStatus",
+    "ExtractionPipeline",
+    "GroqChatClient",
+    "LLMClient",
+    "OllamaChatClient",
+    "SourceAdapter",
+    "SourcePost",
+    "VKApiError",
+    "VKFetchResult",
+    "VKPostSource",
+    "VKSource",
+]