reportify-sdk 0.1.0__py3-none-any.whl

reportify_sdk/__init__.py

@@ -0,0 +1,31 @@
+"""
+Reportify SDK - Python client for Reportify API
+
+A user-friendly SDK for accessing financial data, document search,
+and knowledge base through the Reportify API.
+
+Usage:
+    from reportify_sdk import Reportify
+
+    client = Reportify(api_key="your-api-key")
+    docs = client.search("Tesla earnings", num=10)
+"""
+
+from reportify_sdk.client import Reportify
+from reportify_sdk.exceptions import (
+    ReportifyError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    APIError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Reportify",
+    "ReportifyError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "APIError",
+]

reportify_sdk/client.py

@@ -0,0 +1,362 @@
+"""
+Reportify Client
+
+Main client class for interacting with the Reportify API.
+"""
+
+from typing import Any
+
+import httpx
+
+from reportify_sdk.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+
+class Reportify:
+    """
+    Reportify API Client
+
+    A user-friendly client for accessing financial data, document search,
+    and knowledge base through the Reportify API.
+
+    Args:
+        api_key: Your Reportify API key
+        base_url: Base URL for the API (default: https://api.reportify.cn)
+        timeout: Request timeout in seconds (default: 30)
+
+    Example:
+        >>> from reportify_sdk import Reportify
+        >>> client = Reportify(api_key="your-api-key")
+        >>> docs = client.search("Tesla earnings", num=10)
+    """
+
+    DEFAULT_BASE_URL = "https://api.reportify.cn"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ):
+        if not api_key:
+            raise AuthenticationError("API key is required")
+
+        self.api_key = api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=self._get_headers(),
+            timeout=timeout,
+        )
+
+        # Initialize sub-modules (lazy loading)
+        self._stock = None
+        self._timeline = None
+        self._kb = None
+        self._docs = None
+        self._tools = None
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get default headers for API requests"""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "reportify-sdk-python/0.1.0",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Make an HTTP request to the API
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: API endpoint path
+            params: Query parameters
+            json: JSON body data
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            RateLimitError: If rate limit is exceeded
+            NotFoundError: If resource is not found
+            APIError: For other API errors
+        """
+        try:
+            response = self._client.request(
+                method=method,
+                url=path,
+                params=params,
+                json=json,
+            )
+
+            # Handle error responses
+            if response.status_code == 401:
+                raise AuthenticationError()
+            elif response.status_code == 429:
+                raise RateLimitError()
+            elif response.status_code == 404:
+                raise NotFoundError()
+            elif response.status_code >= 400:
+                error_msg = response.text
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("detail", error_data.get("message", error_msg))
+                except Exception:
+                    pass
+                raise APIError(error_msg, status_code=response.status_code)
+
+            return response.json()
+
+        except httpx.TimeoutException:
+            raise APIError("Request timeout", status_code=408)
+        except httpx.RequestError as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a GET request"""
+        return self._request("GET", path, params=params)
+
+    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a POST request"""
+        return self._request("POST", path, json=json)
+
+    # -------------------------------------------------------------------------
+    # Search Methods
+    # -------------------------------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        *,
+        num: int = 10,
+        categories: list[str] | None = None,
+        symbols: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search documents across all categories
+
+        Args:
+            query: Search query string
+            num: Number of results to return (default: 10, max: 100)
+            categories: Filter by document categories
+            symbols: Filter by stock symbols (e.g., ["US:AAPL", "HK:0700"])
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+
+        Returns:
+            List of matching documents
+
+        Example:
+            >>> docs = client.search("Tesla earnings", num=10)
+            >>> for doc in docs:
+            ...     print(doc["title"])
+        """
+        data = {
+            "query": query,
+            "num": num,
+        }
+        if categories:
+            data["categories"] = categories
+        if symbols:
+            data["symbols"] = symbols
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v2/search", json=data)
+        return response.get("docs", [])
+
+    def search_news(
+        self,
+        query: str,
+        *,
+        num: int = 10,
+        symbols: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search news articles
+
+        Args:
+            query: Search query string
+            num: Number of results to return
+            symbols: Filter by stock symbols
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+
+        Returns:
+            List of news articles
+        """
+        data = {"query": query, "num": num}
+        if symbols:
+            data["symbols"] = symbols
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v2/search/news", json=data)
+        return response.get("docs", [])
+
+    def search_reports(
+        self,
+        query: str,
+        *,
+        num: int = 10,
+        symbols: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search research reports
+
+        Args:
+            query: Search query string
+            num: Number of results to return
+            symbols: Filter by stock symbols
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+
+        Returns:
+            List of research reports
+        """
+        data = {"query": query, "num": num}
+        if symbols:
+            data["symbols"] = symbols
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v2/search/reports", json=data)
+        return response.get("docs", [])
+
+    def search_filings(
+        self,
+        query: str,
+        *,
+        num: int = 10,
+        symbols: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search company filings and announcements
+
+        Args:
+            query: Search query string
+            num: Number of results to return
+            symbols: Filter by stock symbols
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+
+        Returns:
+            List of filings
+        """
+        data = {"query": query, "num": num}
+        if symbols:
+            data["symbols"] = symbols
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v2/search/filings", json=data)
+        return response.get("docs", [])
+
+    def search_transcripts(
+        self,
+        query: str,
+        *,
+        num: int = 10,
+        symbols: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search earnings call transcripts
+
+        Args:
+            query: Search query string
+            num: Number of results to return
+            symbols: Filter by stock symbols
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+
+        Returns:
+            List of transcripts
+        """
+        data = {"query": query, "num": num}
+        if symbols:
+            data["symbols"] = symbols
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v2/search/conference-calls", json=data)
+        return response.get("docs", [])
+
+    # -------------------------------------------------------------------------
+    # Sub-modules (lazy loading)
+    # -------------------------------------------------------------------------
+
+    @property
+    def stock(self):
+        """Stock data module for financial statements, prices, etc."""
+        if self._stock is None:
+            from reportify_sdk.stock import StockModule
+            self._stock = StockModule(self)
+        return self._stock
+
+    @property
+    def timeline(self):
+        """Timeline module for following companies, topics, etc."""
+        if self._timeline is None:
+            from reportify_sdk.timeline import TimelineModule
+            self._timeline = TimelineModule(self)
+        return self._timeline
+
+    @property
+    def kb(self):
+        """Knowledge base module for searching user uploaded documents"""
+        if self._kb is None:
+            from reportify_sdk.kb import KBModule
+            self._kb = KBModule(self)
+        return self._kb
+
+    @property
+    def docs(self):
+        """Documents module for accessing document content and metadata"""
+        if self._docs is None:
+            from reportify_sdk.docs import DocsModule
+            self._docs = DocsModule(self)
+        return self._docs
+
+    def close(self):
+        """Close the HTTP client"""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

reportify_sdk/docs.py

@@ -0,0 +1,173 @@
+"""
+Documents Module
+
+Provides access to document content, metadata, and summaries.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reportify_sdk.client import Reportify
+
+
+class DocsModule:
+    """
+    Documents module for accessing document content and metadata
+
+    Access through the main client:
+        >>> client = Reportify(api_key="xxx")
+        >>> doc = client.docs.get("doc_id")
+    """
+
+    def __init__(self, client: "Reportify"):
+        self._client = client
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._get(path, params=params)
+
+    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._post(path, json=json)
+
+    def get(self, doc_id: str) -> dict[str, Any]:
+        """
+        Get document content and metadata
+
+        Retrieves the full content of a document including chunks.
+
+        Args:
+            doc_id: Document ID
+
+        Returns:
+            Document dictionary with content and metadata
+
+        Example:
+            >>> doc = client.docs.get("abc123")
+            >>> print(doc["title"])
+            >>> print(doc["content"][:500])
+        """
+        return self._get(f"/v1/docs/{doc_id}")
+
+    def summary(self, doc_id: str) -> dict[str, Any]:
+        """
+        Get document summary
+
+        Retrieves the AI-generated summary of a document.
+
+        Args:
+            doc_id: Document ID
+
+        Returns:
+            Summary dictionary with title, summary text, and key points
+
+        Example:
+            >>> summary = client.docs.summary("abc123")
+            >>> print(summary["summary"])
+            >>> for point in summary.get("key_points", []):
+            ...     print(f"- {point}")
+        """
+        return self._get(f"/v1/docs/{doc_id}/summary")
+
+    def raw_content(self, doc_id: str) -> dict[str, Any]:
+        """
+        Get raw document content
+
+        Retrieves the original content of a document without processing.
+
+        Args:
+            doc_id: Document ID
+
+        Returns:
+            Raw content dictionary
+        """
+        return self._get(f"/v1/docs/{doc_id}/raw-content")
+
+    def list(
+        self,
+        *,
+        symbols: list[str] | None = None,
+        categories: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> dict[str, Any]:
+        """
+        List documents with filters
+
+        Args:
+            symbols: Filter by stock symbols
+            categories: Filter by document categories
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+            page: Page number (default: 1)
+            page_size: Number of items per page (default: 20)
+
+        Returns:
+            Dictionary with documents list and pagination info
+
+        Example:
+            >>> result = client.docs.list(symbols=["US:AAPL"], page_size=10)
+            >>> for doc in result["docs"]:
+            ...     print(doc["title"])
+        """
+        data: dict[str, Any] = {
+            "page_num": page,
+            "page_size": page_size,
+        }
+        if symbols:
+            data["symbols"] = symbols
+        if categories:
+            data["categories"] = categories
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        return self._post("/v1/docs", json=data)
+
+    def search_chunks(
+        self,
+        query: str,
+        *,
+        symbols: list[str] | None = None,
+        categories: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        num: int = 10,
+    ) -> list[dict[str, Any]]:
+        """
+        Search document chunks semantically
+
+        Performs semantic search across document chunks.
+
+        Args:
+            query: Search query string
+            symbols: Filter by stock symbols
+            categories: Filter by document categories
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+            num: Number of results to return
+
+        Returns:
+            List of matching chunks with document info
+
+        Example:
+            >>> chunks = client.docs.search_chunks("revenue guidance", num=5)
+            >>> for chunk in chunks:
+            ...     print(chunk["content"])
+        """
+        data: dict[str, Any] = {
+            "query": query,
+            "num": num,
+        }
+        if symbols:
+            data["symbols"] = symbols
+        if categories:
+            data["categories"] = categories
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v1/search/chunks", json=data)
+        return response.get("chunks", [])

reportify_sdk/exceptions.py

@@ -0,0 +1,41 @@
+"""
+Reportify SDK Exceptions
+
+Custom exception classes for handling API errors.
+"""
+
+
+class ReportifyError(Exception):
+    """Base exception for Reportify SDK"""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class AuthenticationError(ReportifyError):
+    """Raised when API key is invalid or missing"""
+
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(message, status_code=401)
+
+
+class RateLimitError(ReportifyError):
+    """Raised when rate limit is exceeded"""
+
+    def __init__(self, message: str = "Rate limit exceeded"):
+        super().__init__(message, status_code=429)
+
+
+class NotFoundError(ReportifyError):
+    """Raised when requested resource is not found"""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, status_code=404)
+
+
+class APIError(ReportifyError):
+    """Raised for general API errors"""
+
+    pass

reportify_sdk/kb.py

@@ -0,0 +1,76 @@
+"""
+Knowledge Base Module
+
+Provides access to user's personal knowledge base for searching
+uploaded documents and folders.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reportify_sdk.client import Reportify
+
+
+class KBModule:
+    """
+    Knowledge base module for searching user uploaded documents
+
+    Access through the main client:
+        >>> client = Reportify(api_key="xxx")
+        >>> results = client.kb.search("revenue breakdown")
+    """
+
+    def __init__(self, client: "Reportify"):
+        self._client = client
+
+    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._post(path, json=json)
+
+    def search(
+        self,
+        query: str,
+        *,
+        folder_ids: list[str] | None = None,
+        doc_ids: list[str] | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        num: int = 10,
+    ) -> list[dict[str, Any]]:
+        """
+        Search user's knowledge base
+
+        Performs semantic search across documents the user has uploaded
+        to their personal knowledge base.
+
+        Args:
+            query: Search query string
+            folder_ids: Filter by specific folder IDs
+            doc_ids: Filter by specific document IDs
+            start_date: Start date filter (YYYY-MM-DD)
+            end_date: End date filter (YYYY-MM-DD)
+            num: Number of results to return (default: 10)
+
+        Returns:
+            List of matching chunks with document information
+
+        Example:
+            >>> results = client.kb.search("quarterly revenue", num=5)
+            >>> for chunk in results:
+            ...     print(chunk["content"][:100])
+            ...     print(f"From: {chunk['doc']['title']}")
+        """
+        data: dict[str, Any] = {
+            "query": query,
+            "num": num,
+        }
+        if folder_ids:
+            data["folder_ids"] = folder_ids
+        if doc_ids:
+            data["doc_ids"] = doc_ids
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v1/tools/kb/search", json=data)
+        return response.get("chunks", [])