Metadata-Version: 2.4
Name: assistant-service-kit
Version: 0.6.0
Summary: Reusable kit for building LangChain-based assistant services with auth, tenancy, tools, RAG, tracing, and observability.
Author: Assistant Service Kit Contributors
License-Expression: MIT
Keywords: assistant,langchain,rag,fastapi,tenancy
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: pydantic<3,>=2
Requires-Dist: PyJWT[crypto]<3,>=2.9
Requires-Dist: SQLAlchemy<3,>=2
Requires-Dist: httpx<1,>=0.28
Requires-Dist: langchain-core<2,>=1.4
Provides-Extra: server
Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "server"
Provides-Extra: rag
Requires-Dist: langchain-text-splitters<2,>=1.1; extra == "rag"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "postgres"
Provides-Extra: gemini
Requires-Dist: langchain-google-genai<5,>=4.2; extra == "gemini"
Provides-Extra: openai
Requires-Dist: langchain-openai<2,>=1; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic<2,>=1; extra == "anthropic"
Provides-Extra: test
Requires-Dist: pytest<10,>=9; extra == "test"
Requires-Dist: pytest-cov<8,>=7; extra == "test"
Requires-Dist: httpx<1,>=0.28; extra == "test"
Provides-Extra: all
Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "all"
Requires-Dist: langchain-text-splitters<2,>=1.1; extra == "all"
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "all"
Requires-Dist: langchain-google-genai<5,>=4.2; extra == "all"
Requires-Dist: langchain-openai<2,>=1; extra == "all"
Requires-Dist: langchain-anthropic<2,>=1; extra == "all"
Provides-Extra: dev
Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "dev"
Requires-Dist: langchain-text-splitters<2,>=1.1; extra == "dev"
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "dev"
Requires-Dist: langchain-google-genai<5,>=4.2; extra == "dev"
Requires-Dist: langchain-openai<2,>=1; extra == "dev"
Requires-Dist: langchain-anthropic<2,>=1; extra == "dev"
Requires-Dist: pytest<10,>=9; extra == "dev"
Requires-Dist: pytest-cov<8,>=7; extra == "dev"
Requires-Dist: httpx<1,>=0.28; extra == "dev"
Dynamic: license-file

# Assistant Service Kit

Reusable Python package for building LangChain-based assistant services with FastAPI, auth, tenancy, tools, RAG, tracing, storage, and observability.

## Install

Base runtime:

```bash
pip install assistant-service-kit
```

Provider-specific installs:

```bash
pip install "assistant-service-kit[rag,gemini]"
pip install "assistant-service-kit[rag,openai]"
pip install "assistant-service-kit[rag,anthropic]"
```

For local development from this package directory:

```bash
pip install -e ".[dev]"
```

## Core Pieces

- `Assistant`: simple facade for building a FastAPI assistant quickly.
- `AssistantDefinition`: declares the assistant server contract.
- `AssistantEndpoints` / `EndpointPolicy`: declares enabled routes, custom paths, names, global endpoint policy, and endpoint permissions.
- `AuthConnector`: supports no-auth, user-only, trusted internal token, API key, and custom identity resolution.
- `LLMProviderRegistry`: Gemini, OpenAI, Anthropic, and fake chat model providers.
- `EmbeddingProviderRegistry`: Gemini, OpenAI, Anthropic, and fake embedding providers.
- `ApiClient` / `ApiClientConfig`: reusable HTTP client for tools, including API key, bearer, forwarded token, and gateway-delegated token auth.
- `ToolRegistry` / `ToolPolicy`: exposes and validates tools by tenant, user, roles, and limits.
- `SQLAlchemyTraceStore` / `InMemoryTraceStore`: reusable chat trace persistence.
- `PostgresRagStore` / `VectorStoreConnector`: reusable RAG storage and vector-store integration points.
- `create_assistant_sqlalchemy_models`: standard SQLAlchemy trace and RAG models for the common case.
- `answer_with_langchain_agent`: LangChain tool-calling orchestrator with observability metadata.

## Minimal Example

```python
from assistant_service_kit import (
    Assistant,
    AssistantEndpoints,
    DatabaseConfig,
    TenancyMode,
    create_sqlalchemy_database,
)

database = create_sqlalchemy_database(DatabaseConfig(debug=True, debug_url="sqlite:///:memory:"))

assistant = Assistant(
    name="demo",
    title="Demo Assistant",
    base_path="/api/assistant",
    tenancy=TenancyMode.NONE,
    prompt="Answer clearly.",
    endpoints=AssistantEndpoints(chat=False, conversations=False, messages=False, feedback=False),
)

assistant.with_no_auth()
assistant.with_llm(provider="fake", model="fake", extra={"response": "ok"})
assistant.with_database(database)

app = assistant.fastapi()
```

Declarative tools:

```python
from pydantic import BaseModel
from assistant_service_kit import ApiClientConfig, ToolPolicy, ToolRegistry


class SearchArgs(BaseModel):
    query: str


tools = ToolRegistry()
tools.api_tool(
    name="search_data",
    description="Search tenant data.",
    args_schema=SearchArgs,
    policy=ToolPolicy(requires_tenant=True, requires_user=True, max_limit=10),
    client="data_api",
    method="GET",
    path="/internal/search/",
    params="payload",
)


assistant.with_api_client("data_api", ApiClientConfig(base_url="https://internal-api.example"))
assistant.with_tools(tools)
```

Use `@tools.tool(...)` when a tool needs custom Python logic instead of a direct API call.

For standard SQLAlchemy persistence:

```python
from assistant_service_kit import DatabaseConfig, create_sqlalchemy_database

database = create_sqlalchemy_database(
    DatabaseConfig(
        debug=True,
        debug_url="sqlite:///./assistant.db",
        url="postgresql+psycopg2://user:pass@host/db",
    )
)

assistant.with_database(database)
assistant.with_rag(database, default_limit=4, max_limit=8, chunk_size=800, chunk_overlap=120)
app = assistant.fastapi()
```

For advanced integrations, call `assistant.build()` to get an `AssistantDefinition`, or build `AssistantDefinition` and connectors directly.

## Status

The package is in alpha. APIs can change until the first stable release.
