vectoramp 0.1.0__py3-none-any.whl

vectoramp/__init__.py

@@ -0,0 +1,45 @@
+"""VectorAmp Python SDK."""
+
+from .client import VectorAmp
+from .embeddings import (
+    EMBEDDING_DIMENSIONS,
+    EMBEDDINGS,
+    OPENAI_TEXT_EMBEDDING_3_LARGE,
+    OPENAI_TEXT_EMBEDDING_3_SMALL,
+    VECTORAMP_EMBEDDING_4B,
+    openai,
+)
+from .exceptions import APIError, AuthenticationError, VectorAmpError
+from .resources import Dataset
+from .sources import (
+    ConfluenceSource,
+    FileUploadSource,
+    GCSSource,
+    GenericSource,
+    GoogleDriveSource,
+    JiraSource,
+    S3Source,
+    WebSource,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConfluenceSource",
+    "Dataset",
+    "EMBEDDING_DIMENSIONS",
+    "EMBEDDINGS",
+    "FileUploadSource",
+    "GCSSource",
+    "GenericSource",
+    "GoogleDriveSource",
+    "JiraSource",
+    "OPENAI_TEXT_EMBEDDING_3_LARGE",
+    "OPENAI_TEXT_EMBEDDING_3_SMALL",
+    "S3Source",
+    "VectorAmp",
+    "VECTORAMP_EMBEDDING_4B",
+    "VectorAmpError",
+    "WebSource",
+    "openai",
+]

vectoramp/client.py

@@ -0,0 +1,133 @@
+"""Top-level VectorAmp client."""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Iterator, Optional, Type
+
+import httpx
+
+from .connections import ConnectionsResource
+from .resources import DatasetsResource, IngestionResource, IntelligenceResource, SchedulesResource
+from .transport import BaseTransport, RestTransport
+from .types import JSON, ConversationTurn
+
+
+class VectorAmp:
+    """Synchronous VectorAmp API client.
+
+    Args:
+        api_key: API key to send as bearer auth. Defaults to
+            ``VECTORAMP_API_KEY`` when omitted.
+        base_url: API origin. Defaults to ``https://api.vectoramp.com``.
+        timeout: Request timeout in seconds. Defaults to ``30.0``.
+        transport: Optional custom transport, primarily for tests or adapters.
+        http_client: Optional ``httpx.Client`` used by the default REST transport.
+
+    Attributes:
+        datasets: Dataset management, search, embedding, and insertion APIs.
+        ingestion: Source, upload, and ingestion-job APIs.
+        sources: Alias for ``ingestion``.
+        connections: OAuth connection management for providers.
+        schedules: Recurring ingestion schedule management.
+        intelligence: RAG query and streaming APIs.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = "https://api.vectoramp.com",
+        timeout: float = 30.0,
+        transport: Optional[BaseTransport] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        resolved_api_key = api_key or os.getenv("VECTORAMP_API_KEY") or ""
+        self.transport = transport or RestTransport(
+            api_key=resolved_api_key,
+            base_url=base_url,
+            timeout=timeout,
+            client=http_client,
+        )
+        self.datasets = DatasetsResource(self.transport, client=self)
+        self.ingestion = IngestionResource(self.transport)
+        self.sources = self.ingestion
+        self.connections = ConnectionsResource(self.transport)
+        self.schedules = SchedulesResource(self.transport)
+        self.intelligence = IntelligenceResource(self.transport)
+
+    def ask(
+        self,
+        query: str,
+        *,
+        dataset_id: Optional[str] = None,
+        top_k: int = 5,
+        conversation_history: Optional[list[ConversationTurn]] = None,
+        include_sources: bool = True,
+    ) -> JSON:
+        """Ask a non-streaming RAG question.
+
+        Args:
+            query: Natural-language question.
+            dataset_id: Optional dataset to ground the answer in. When omitted,
+                the API chooses its configured/default scope.
+            top_k: Number of retrieved chunks to consider. Defaults to ``5``.
+            conversation_history: Optional prior chat turns.
+            include_sources: Whether to include source chunks. Defaults to ``True``.
+
+        Returns:
+            JSON response from ``/intelligence/query``.
+        """
+        return self.intelligence.query(
+            query,
+            dataset_id=dataset_id,
+            top_k=top_k,
+            conversation_history=conversation_history,
+            include_sources=include_sources,
+        )
+
+    def ask_stream(
+        self,
+        query: str,
+        *,
+        dataset_id: Optional[str] = None,
+        top_k: int = 5,
+        conversation_history: Optional[list[ConversationTurn]] = None,
+        include_sources: bool = True,
+    ) -> Iterator[JSON]:
+        """Yield Server-Sent Event chunks for a streaming RAG answer.
+
+        Args:
+            query: Natural-language question.
+            dataset_id: Optional dataset to ground the answer in. When omitted,
+                the API chooses its configured/default scope.
+            top_k: Number of retrieved chunks to consider. Defaults to ``5``.
+            conversation_history: Optional prior chat turns.
+            include_sources: Whether to include source chunks. Defaults to ``True``.
+
+        Returns:
+            Iterator of JSON Server-Sent Event payloads.
+        """
+        yield from self.intelligence.stream(
+            query,
+            dataset_id=dataset_id,
+            top_k=top_k,
+            conversation_history=conversation_history,
+            include_sources=include_sources,
+        )
+
+    def close(self) -> None:
+        """Close the underlying transport and HTTP connection pool."""
+        self.transport.close()
+
+    def __enter__(self) -> "VectorAmp":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        self.close()

vectoramp/connections.py

@@ -0,0 +1,123 @@
+"""OAuth connection management for the VectorAmp SDK.
+
+Connections hold the stored OAuth grant for a provider (Google Drive, Atlassian,
+etc.). They live at the gateway root ``/connections`` namespace (not under
+``/ingestion``) and are referenced from a source via ``connection_id``.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+from .transport import BaseTransport
+from .types import JSON
+
+
+def _print_authorization_url(url: str) -> None:
+    """Default ``on_url`` handler: print the authorization URL and instructions."""
+    print(
+        "To authorize this connection, open the following URL in your browser:\n"
+        f"  {url}\n"
+        "Waiting for authorization to complete..."
+    )
+
+
+class ConnectionsResource:
+    """OAuth connection management.
+
+    A connection captures the OAuth authorization for a provider so that
+    ingestion sources can reuse it via ``connection_id`` instead of embedding
+    raw credentials. Use :meth:`connect` for the full interactive
+    create-authorize-poll flow, or the lower-level CRUD methods directly.
+    """
+
+    def __init__(self, transport: BaseTransport) -> None:
+        self._transport = transport
+
+    def list(self, *, provider: Optional[str] = None) -> JSON:
+        """List connections for the calling organization.
+
+        Args:
+            provider: Optional provider filter (e.g. ``"google_drive"``).
+
+        Returns:
+            Connection list JSON from ``/connections``.
+        """
+        return self._transport.request("GET", "/connections", params={"provider": provider})
+
+    def create(self, provider: str, *, source_type: Optional[str] = None) -> JSON:
+        """Create a pending connection and return its authorization URL.
+
+        Args:
+            provider: OAuth provider identifier (e.g. ``"google_drive"``).
+            source_type: Optional source type the connection will be used for.
+
+        Returns:
+            Created connection JSON with ``id``, ``provider``, ``status``, and
+            ``authorization_url``.
+        """
+        body: JSON = {"provider": provider}
+        if source_type is not None:
+            body["source_type"] = source_type
+        return self._transport.request("POST", "/connections", json_body=body)
+
+    def get(self, connection_id: str) -> JSON:
+        """Return one connection by id."""
+        return self._transport.request("GET", f"/connections/{connection_id}")
+
+    def delete(self, connection_id: str) -> JSON:
+        """Delete a connection."""
+        return self._transport.request("DELETE", f"/connections/{connection_id}")
+
+    def connect(
+        self,
+        provider: str,
+        *,
+        source_type: Optional[str] = None,
+        on_url: Optional[Callable[[str], None]] = None,
+        poll_interval: float = 2.0,
+        timeout: float = 300.0,
+    ) -> JSON:
+        """Run the full create-authorize-poll connection flow.
+
+        Creates a connection, surfaces its ``authorization_url`` (via ``on_url``,
+        which defaults to printing the URL and instructions), then polls until the
+        connection reports ``status == "connected"`` or ``timeout`` elapses.
+
+        Args:
+            provider: OAuth provider identifier (e.g. ``"google_drive"``).
+            source_type: Optional source type the connection will be used for.
+            on_url: Callback invoked with the authorization URL. Defaults to
+                printing the URL and instructions to stdout.
+            poll_interval: Seconds between status polls. Defaults to ``2.0``.
+            timeout: Maximum seconds to wait for authorization. Defaults to ``300.0``.
+
+        Returns:
+            The connected connection JSON.
+
+        Raises:
+            ValueError: If the create response lacks an id.
+            TimeoutError: If the connection is not connected before ``timeout``.
+        """
+        connection = self.create(provider, source_type=source_type)
+        connection_id = connection.get("id") or connection.get("connection_id")
+        if connection_id is None:
+            raise ValueError("Connection creation response did not include id.")
+        connection_id = str(connection_id)
+
+        authorization_url = connection.get("authorization_url")
+        if authorization_url is not None:
+            callback = on_url or _print_authorization_url
+            callback(str(authorization_url))
+
+        deadline = time.monotonic() + timeout
+        while True:
+            current = self.get(connection_id)
+            if current.get("status") == "connected":
+                return current
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Connection {connection_id} was not connected within {timeout}s."
+                )
+            time.sleep(poll_interval)

vectoramp/embeddings.py

@@ -0,0 +1,39 @@
+"""Embedding helpers for dataset creation."""
+
+from __future__ import annotations
+
+from typing import Dict, Literal, Mapping
+
+EmbeddingConfig = Dict[str, str]
+OpenAIEmbeddingSize = Literal["small", "large"]
+
+VECTORAMP_EMBEDDING_4B = "VectorAmp-Embedding-4B"
+OPENAI_TEXT_EMBEDDING_3_SMALL = "text-embedding-3-small"
+OPENAI_TEXT_EMBEDDING_3_LARGE = "text-embedding-3-large"
+
+EMBEDDING_DIMENSIONS: Mapping[str, int] = {
+    VECTORAMP_EMBEDDING_4B: 2560,
+    OPENAI_TEXT_EMBEDDING_3_SMALL: 1536,
+    OPENAI_TEXT_EMBEDDING_3_LARGE: 3072,
+}
+
+
+def openai(size: OpenAIEmbeddingSize = "small") -> EmbeddingConfig:
+    """Return an OpenAI BYOM embedding config for dataset creation."""
+
+    return {
+        "provider": "openai",
+        "model": (
+            OPENAI_TEXT_EMBEDDING_3_LARGE
+            if size == "large"
+            else OPENAI_TEXT_EMBEDDING_3_SMALL
+        ),
+        "secret_ref": "emb:openai:api_key",
+    }
+
+
+EMBEDDINGS = {
+    "vectoramp_4b": {"provider": "vectoramp", "model": VECTORAMP_EMBEDDING_4B},
+    "openai_small": openai("small"),
+    "openai_large": openai("large"),
+}

vectoramp/exceptions.py

@@ -0,0 +1,22 @@
+"""VectorAmp SDK exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class VectorAmpError(Exception):
+    """Base SDK exception."""
+
+
+class AuthenticationError(VectorAmpError):
+    """Raised when no API key is configured."""
+
+
+class APIError(VectorAmpError):
+    """Raised for non-successful API responses."""
+
+    def __init__(self, status_code: int, message: str, *, response: Any = None) -> None:
+        self.status_code = status_code
+        self.response = response
+        super().__init__(f"VectorAmp API error {status_code}: {message}")