coresens 0.1.0__tar.gz

coresens-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+env/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.env

coresens-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: coresens
+Version: 0.1.0
+Summary: Official Python SDK for CoreSens Neural Search & Web Retrieval API
+Project-URL: Homepage, https://coresens.ru
+Project-URL: Documentation, https://docs.coresens.ru
+Project-URL: Repository, https://github.com/coresens/coresens-python
+Author-email: CoreSens Team <dev@coresens.ru>
+License: MIT
+Keywords: ai,crawler,llm,neural-search,rag,retrieval,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# CoreSens Python SDK
+
+Официальная Python-библиотека для взаимодействия с **CoreSens API** — отечественным движком Neural Search & Web Retrieval для AI-агентов и RAG-систем.
+
+---
+
+## 🚀 Установка
+
+```bash
+pip install coresens

coresens-0.1.0/README.md

@@ -0,0 +1,10 @@
+# CoreSens Python SDK
+
+Официальная Python-библиотека для взаимодействия с **CoreSens API** — отечественным движком Neural Search & Web Retrieval для AI-агентов и RAG-систем.
+
+---
+
+## 🚀 Установка
+
+```bash
+pip install coresens

coresens-0.1.0/example_test.py

@@ -0,0 +1,43 @@
+import asyncio
+from coresens import CoreSens, AsyncCoreSens
+
+BASE_URL = "**************************"
+API_KEY = "vw_live_******************************************"
+
+
+def test_sync():
+    print("--- 1. Тест синхронного поиска ---")
+    client = CoreSens(api_key=API_KEY, base_url=BASE_URL)
+    
+    try:
+        response = client.search(
+            query="Обратная инженерия",
+            num_results=2,
+            contents={"highlights": True, "text": True}
+        )
+        print(f"Запрос: {response.query} (Задержка: {response.latency_ms} мс)")
+        for item in response.results:
+            print(f"- [{item.score}] {item.title}: {item.url}")
+            print(f"  Питч: {item.pitch}")
+            print(f"  Хайлайты: {item.highlights}")
+    except Exception as e:
+        print(f"Ошибка: {e}")
+    finally:
+        client.close()
+
+
+async def test_async():
+    print("\n--- 2. Тест асинхронного извлечения (Extract) ---")
+    async with AsyncCoreSens(api_key=API_KEY, base_url=BASE_URL) as client:
+        try:
+            res = await client.extract(urls=["https://habr.com/ru/news/715642/"])
+            for doc in res.documents:
+                print(f"Извлечено: {doc.title} (Символов: {doc.char_count})")
+                print(f"Markdown превью: {str(doc.markdown_content)[:150]}...")
+        except Exception as e:
+            print(f"Ошибка async: {e}")
+
+
+if __name__ == "__main__":
+    test_sync()
+    asyncio.run(test_async())

coresens-0.1.0/project.md

@@ -0,0 +1,10 @@
+coresens-python/
+├── pyproject.toml
+├── README.md
+└── src/
+    └── coresens/
+        ├── __init__.py
+        ├── exceptions.py
+        ├── models.py
+        ├── client.py
+        └── async_client.py

coresens-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "coresens"
+version = "0.1.0"
+description = "Official Python SDK for CoreSens Neural Search & Web Retrieval API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "CoreSens Team", email = "dev@coresens.ru" },
+]
+keywords = ["search", "neural-search", "rag", "ai", "crawler", "retrieval", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+
+# [Dev-Assistant]: Минимальный набор зависимостей. Только проверенный HTTP-клиент и валидатор типов.
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://coresens.ru"
+Documentation = "https://docs.coresens.ru"
+Repository = "https://github.com/coresens/coresens-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coresens"]

coresens-0.1.0/src/coresens/__init__.py

@@ -0,0 +1,46 @@
+# [Dev-Assistant]: Главный экспорт библиотеки CoreSens.
+# Позволяет импортировать всё необходимое напрямую: from coresens import CoreSens, AsyncCoreSens
+
+from coresens.client import CoreSens
+from coresens.async_client import AsyncCoreSens
+from coresens.models import (
+    SearchRequest,
+    SearchResponse,
+    SearchResultItem,
+    ContentOptions,
+    ExtractRequest,
+    ExtractResponse,
+    ExtractedDocument,
+)
+from coresens.exceptions import (
+    CoreSensError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    RateLimitError,
+    InvalidRequestError,
+    InternalServerError,
+    APIConnectionError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CoreSens",
+    "AsyncCoreSens",
+    "SearchRequest",
+    "SearchResponse",
+    "SearchResultItem",
+    "ContentOptions",
+    "ExtractRequest",
+    "ExtractResponse",
+    "ExtractedDocument",
+    "CoreSensError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "InternalServerError",
+    "APIConnectionError",
+]

coresens-0.1.0/src/coresens/async_client.py

@@ -0,0 +1,154 @@
+# [Dev-Assistant]: Асинхронный HTTP-клиент для CoreSens API на базе httpx.AsyncClient.
+# Безопасен для использования в асинхронных фреймворках (FastAPI, LangGraph, aiogram).
+
+import os
+from typing import List, Optional, Union, Dict, Any
+import httpx
+
+from coresens.models import (
+    SearchRequest,
+    SearchResponse,
+    ContentOptions,
+    TimeRangeType,
+    ExtractRequest,
+    ExtractResponse
+)
+from coresens.exceptions import (
+    CoreSensError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    RateLimitError,
+    InvalidRequestError,
+    InternalServerError,
+    APIConnectionError
+)
+
+
+class AsyncCoreSens:
+    """
+    Асинхронный клиент для взаимодействия с CoreSens API.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.coresens.ru",
+        timeout: float = 30.0,
+        max_retries: int = 2
+    ):
+        self.api_key = api_key or os.getenv("CORESENS_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "API-ключ не найден. Передайте его явно: AsyncCoreSens(api_key='...') "
+                "или установите переменную окружения CORESENS_API_KEY."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "X-API-Key": self.api_key,
+                "User-Agent": "CoreSens-Async-Python-SDK/0.1.0",
+                "Content-Type": "application/json",
+            },
+            timeout=self.timeout
+        )
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Транслирует HTTP-статусы в типизированные исключения SDK."""
+        try:
+            error_data = response.json()
+            message = error_data.get("detail", response.text)
+        except Exception:
+            error_data = None
+            message = response.text or f"HTTP {response.status_code}"
+
+        status_code = response.status_code
+
+        if status_code == 401:
+            raise AuthenticationError(f"Неверный или просроченный API-ключ: {message}", error_data)
+        elif status_code == 402:
+            raise RateLimitError(f"Недостаточно средств на балансе: {message}", error_data)
+        elif status_code == 403:
+            raise PermissionDeniedError(f"Доступ запрещен: {message}", error_data)
+        elif status_code == 404:
+            raise NotFoundError(f"Ресурс не найден: {message}", error_data)
+        elif status_code in (400, 422):
+            raise InvalidRequestError(f"Ошибка валидации запроса: {message}", error_data)
+        elif status_code == 429:
+            raise RateLimitError(f"Превышен лимит запросов: {message}", error_data)
+        elif status_code >= 500:
+            raise InternalServerError(f"Ошибка сервера CoreSens (HTTP {status_code}): {message}", error_data)
+        else:
+            raise CoreSensError(f"Неизвестная ошибка API (HTTP {status_code}): {message}", error_data)
+
+    async def search(
+        self,
+        query: str,
+        num_results: int = 3,
+        time_range: Optional[TimeRangeType] = "auto",
+        languages: Optional[List[str]] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        contents: Optional[Union[ContentOptions, Dict[str, Any]]] = None,
+    ) -> SearchResponse:
+        """
+        Асинхронный семантический поиск по векторизованному Рунету.
+        """
+        if isinstance(contents, dict):
+            contents_obj = ContentOptions(**contents)
+        elif contents is None:
+            contents_obj = ContentOptions()
+        else:
+            contents_obj = contents
+
+        req_payload = SearchRequest(
+            query=query,
+            num_results=num_results,
+            time_range=time_range,
+            languages=languages,
+            start_published_date=start_published_date,
+            end_published_date=end_published_date,
+            contents=contents_obj
+        )
+
+        try:
+            response = await self._client.post("/v1/search", json=req_payload.model_dump(exclude_none=True))
+        except httpx.RequestError as e:
+            raise APIConnectionError(f"Сетевая ошибка при запросе к CoreSens: {str(e)}")
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return SearchResponse.model_validate(response.json())
+
+    async def extract(self, urls: List[str]) -> ExtractResponse:
+        """
+        Асинхронное мгновенное извлечение страниц в чистый Markdown и метаданные.
+        """
+        req_payload = ExtractRequest(urls=urls)
+
+        try:
+            response = await self._client.post("/v1/extract", json=req_payload.model_dump())
+        except httpx.RequestError as e:
+            raise APIConnectionError(f"Сетевая ошибка при запросе к CoreSens: {str(e)}")
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return ExtractResponse.model_validate(response.json())
+
+    async def aclose(self) -> None:
+        """Закрывает асинхронный пул соединений."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.aclose()

coresens-0.1.0/src/coresens/client.py

@@ -0,0 +1,156 @@
+# [Dev-Assistant]: Синхронный HTTP-клиент для CoreSens API на базе httpx.Client.
+# Автоматически управляет токеном, пулом соединений и маппингом ошибок в кастомные исключения.
+
+import os
+from typing import List, Optional, Union, Dict, Any
+import httpx
+
+from coresens.models import (
+    SearchRequest,
+    SearchResponse,
+    ContentOptions,
+    TimeRangeType,
+    ExtractRequest,
+    ExtractResponse
+)
+from coresens.exceptions import (
+    CoreSensError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    RateLimitError,
+    InvalidRequestError,
+    InternalServerError,
+    APIConnectionError
+)
+
+
+class CoreSens:
+    """
+    Синхронный клиент для взаимодействия с CoreSens Neural Search & Web Retrieval API.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.coresens.ru",
+        timeout: float = 30.0,
+        max_retries: int = 2
+    ):
+        # 1. Извлекаем API-ключ (аргумент -> переменная окружения)
+        self.api_key = api_key or os.getenv("CORESENS_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "API-ключ не найден. Передайте его явно: CoreSens(api_key='...') "
+                "или установите переменную окружения CORESENS_API_KEY."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        # 2. Инициализируем HTTP-сессию с авторизацией
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "X-API-Key": self.api_key,
+                "User-Agent": "CoreSens-Python-SDK/0.1.0",
+                "Content-Type": "application/json",
+            },
+            timeout=self.timeout
+        )
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Транслирует HTTP-статусы в типизированные исключения SDK."""
+        try:
+            error_data = response.json()
+            message = error_data.get("detail", response.text)
+        except Exception:
+            error_data = None
+            message = response.text or f"HTTP {response.status_code}"
+
+        status_code = response.status_code
+
+        if status_code == 401:
+            raise AuthenticationError(f"Неверный или просроченный API-ключ: {message}", error_data)
+        elif status_code == 402:
+            raise RateLimitError(f"Недостаточно средств на балансе: {message}", error_data)
+        elif status_code == 403:
+            raise PermissionDeniedError(f"Доступ запрещен: {message}", error_data)
+        elif status_code == 404:
+            raise NotFoundError(f"Ресурс не найден: {message}", error_data)
+        elif status_code in (400, 422):
+            raise InvalidRequestError(f"Ошибка валидации запроса: {message}", error_data)
+        elif status_code == 429:
+            raise RateLimitError(f"Превышен лимит запросов: {message}", error_data)
+        elif status_code >= 500:
+            raise InternalServerError(f"Ошибка сервера CoreSens (HTTP {status_code}): {message}", error_data)
+        else:
+            raise CoreSensError(f"Неизвестная ошибка API (HTTP {status_code}): {message}", error_data)
+
+    def search(
+        self,
+        query: str,
+        num_results: int = 3,
+        time_range: Optional[TimeRangeType] = "auto",
+        languages: Optional[List[str]] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        contents: Optional[Union[ContentOptions, Dict[str, Any]]] = None,
+    ) -> SearchResponse:
+        """
+        Семантический нейропоиск по векторизованному Рунету.
+        """
+        if isinstance(contents, dict):
+            contents_obj = ContentOptions(**contents)
+        elif contents is None:
+            contents_obj = ContentOptions()
+        else:
+            contents_obj = contents
+
+        req_payload = SearchRequest(
+            query=query,
+            num_results=num_results,
+            time_range=time_range,
+            languages=languages,
+            start_published_date=start_published_date,
+            end_published_date=end_published_date,
+            contents=contents_obj
+        )
+
+        try:
+            response = self._client.post("/v1/search", json=req_payload.model_dump(exclude_none=True))
+        except httpx.RequestError as e:
+            raise APIConnectionError(f"Сетевая ошибка при запросе к CoreSens: {str(e)}")
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return SearchResponse.model_validate(response.json())
+
+    def extract(self, urls: List[str]) -> ExtractResponse:
+        """
+        Мгновенное извлечение страниц в чистый Markdown и метаданные.
+        """
+        req_payload = ExtractRequest(urls=urls)
+
+        try:
+            response = self._client.post("/v1/extract", json=req_payload.model_dump())
+        except httpx.RequestError as e:
+            raise APIConnectionError(f"Сетевая ошибка при запросе к CoreSens: {str(e)}")
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return ExtractResponse.model_validate(response.json())
+
+    def close(self) -> None:
+        """Закрывает пул соединений."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

coresens-0.1.0/src/coresens/exceptions.py

@@ -0,0 +1,48 @@
+# [Dev-Assistant]: Иерархия исключений для библиотеки CoreSens.
+# Позволяет пользователям SDK элегантно перехватывать сетевые и API ошибки.
+
+from typing import Any, Optional, Dict
+
+
+class CoreSensError(Exception):
+    """Базовое исключение для всех ошибок SDK CoreSens."""
+    
+    def __init__(self, message: str, raw_response: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.raw_response = raw_response
+
+
+class AuthenticationError(CoreSensError):
+    """Ошибка аутентификации (HTTP 401). Неверный или отсутствующий API-ключ."""
+    pass
+
+
+class PermissionDeniedError(CoreSensError):
+    """Ошибка прав доступа (HTTP 403). Заблокирован аккаунт или нет доступа к методу."""
+    pass
+
+
+class NotFoundError(CoreSensError):
+    """Ресурс не найден (HTTP 404)."""
+    pass
+
+
+class RateLimitError(CoreSensError):
+    """Превышен лимит запросов или закончились токены тарифа (HTTP 429)."""
+    pass
+
+
+class InvalidRequestError(CoreSensError):
+    """Некорректные параметры запроса (HTTP 400 / 422)."""
+    pass
+
+
+class InternalServerError(CoreSensError):
+    """Внутренняя ошибка на стороне серверов CoreSens (HTTP 5xx)."""
+    pass
+
+
+class APIConnectionError(CoreSensError):
+    """Сетевая ошибка: невозможно соединиться с хостом или сработал таймаут."""
+    pass

coresens-0.1.0/src/coresens/models.py

@@ -0,0 +1,115 @@
+# [Dev-Assistant]: Строго синхронизированные Pydantic v2 модели с app/domain/search.py и app/api/v1/endpoints/extract.py.
+
+from typing import List, Optional, Literal, Dict, Any
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseCoreSensModel(BaseModel):
+    """Базовая модель с защитой от изменения схемы бэкенда."""
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        arbitrary_types_allowed=True
+    )
+
+
+# ==========================================================
+# 1. СХЕМЫ ДЛЯ SEARCH API (/v1/search)
+# ==========================================================
+
+class ContentOptions(BaseCoreSensModel):
+    """Настройки извлечения контента в результатах поиска."""
+    text: bool = Field(
+        default=False, 
+        description="Возвращать ли полный очищенный Markdown контент страницы (экономия токенов)"
+    )
+    highlights: bool = Field(
+        default=True, 
+        description="Возвращать ли семантические цитаты"
+    )
+    highlights_per_url: int = Field(
+        default=2, 
+        description="Количество ключевых цитат на каждый найденный URL"
+    )
+
+
+TimeRangeType = Literal["auto", "day", "week", "month", "year", "any"]
+
+
+class SearchRequest(BaseCoreSensModel):
+    """Схема POST-запроса на поиск."""
+    query: str = Field(..., min_length=2, description="Поисковый запрос от LLM-агента или пользователя")
+    num_results: int = Field(default=3, ge=1, le=10, description="Количество результатов в выдаче")
+    time_range: Optional[TimeRangeType] = Field(
+        default="auto",
+        description="Окно свежести: 'auto', 'day', 'week', 'month', 'year', 'any'"
+    )
+    languages: Optional[List[str]] = Field(
+        default=None, 
+        description="Фильтр по ISO-639-1 языкам (например, ['ru', 'en'])"
+    )
+    start_published_date: Optional[str] = Field(
+        default=None,
+        description="Нижний порог даты публикации в ISO (например, '2026-09-01')"
+    )
+    end_published_date: Optional[str] = Field(
+        default=None,
+        description="Верхний порог даты публикации в ISO"
+    )
+    contents: ContentOptions = Field(default_factory=ContentOptions)
+
+
+class SearchResultItem(BaseCoreSensModel):
+    """Отдельный результат в выдаче поиска."""
+    title: str
+    url: str
+    canonical_url: str
+    pitch: str = Field(description="Краткая выжимка / питч страницы для сниппета")
+    score: float = Field(description="Скор релевантности Cross-Encoder от 0 до 1")
+    published_date: Optional[str] = None
+    highlights: List[str] = Field(default_factory=list, description="Точечные семантические цитаты")
+    text: Optional[str] = Field(default=None, description="Полный очищенный Markdown контент страницы")
+
+
+class SearchResponse(BaseCoreSensModel):
+    """Ответ API на поисковый запрос."""
+    query: str
+    results: List[SearchResultItem] = Field(default_factory=list)
+    total_results: int
+    latency_ms: int
+
+
+# ==========================================================
+# 2. СХЕМЫ ДЛЯ EXTRACT API (/v1/extract)
+# ==========================================================
+
+class ExtractRequest(BaseCoreSensModel):
+    """Схема POST-запроса на извлечение в Markdown."""
+    urls: List[str] = Field(..., min_length=1, description="Список URL для мгновенного извлечения")
+
+
+class ExtractedDocument(BaseCoreSensModel):
+    """Финальный структурированный документ страницы."""
+    url: str
+    canonical_url: str
+    doc_id: str = Field(description="SHA-256 от канонического URL")
+    title: Optional[str] = None
+    markdown_content: Optional[str] = None
+    content_hash: Optional[str] = None
+    author: Optional[str] = None
+    published_date: Optional[str] = None
+    published_at: Optional[int] = Field(default=None, description="UTC UNIX timestamp публикации")
+    language: Optional[str] = None
+    status_code: int = 200
+    is_modified: bool = True
+    etag: Optional[str] = None
+    last_modified_header: Optional[str] = None
+    char_count: int = 0
+    is_spa: bool = False
+    needs_headless_render: bool = False
+    error: Optional[str] = None
+
+
+class ExtractResponse(BaseCoreSensModel):
+    """Ответ API на запрос краулинга/извлечения."""
+    documents: List[ExtractedDocument] = Field(default_factory=list)