chatsapi 0.1.0
The World's Fastest AI Agent Framework. Based on SBERT & SpaCy Transforms.
Requires Python: >=3.7

# ChatsAPI

**The World's Fastest AI Agent Framework.**  
Based on **SBERT** and **SpaCy Transforms**, ChatsAPI is designed to enable seamless natural language processing for AI-powered conversational agents. With hybrid search capabilities and an extensible architecture, ChatsAPI offers blazing-fast performance and intuitive route management.


![ChatsAPI-Banner.png](docs_src%2Fimages%2FChatsAPI-Banner.png)


## Features

- **SBERT & SpaCy-Based NLP**: Combines the power of Sentence-BERT embeddings and SpaCy for intelligent semantic matching and entity extraction.
- **Hybrid Search**: Supports HNSWlib-based nearest neighbor search and BM25 hybrid search for efficient query handling.
- **Dynamic Routing**: Easily define conversational routes with decorators.
- **Parameter Extraction**: Automatically extract parameters from user input with flexible type handling.
- **LLM Integration**: Integrates with popular LLMs such as OpenAI, Gemini, and LlamaAPI for extended conversational capabilities.
- **Conversation Management**: Supports multi-session conversation handling with unique session IDs.


## Installation

Install the package via pip:

```bash
pip install chatsapi
```


## Usage

### Initializing the Framework

```python
from chatsapi import ChatsAPI

chat = ChatsAPI(
    llm_type="gemini",  # Choose LLM type (e.g., gemini, openai, ollama)
    llm_model="models/gemini-pro",  # Specify model
    llm_api_key="YOUR_API_KEY"  # API key for the LLM
)
```


### Registering Routes

Define conversational routes using decorators. Routes map user inputs to specific handler functions.

```python
@chat.trigger("Want to cancel a credit card.")
@chat.extract([("card_number", "Credit card number (a 12-digit number)", str, None)])
async def cancel_credit_card(chat_message: str, extracted: dict):
    return {"message": chat_message, "extracted": extracted}
```

**Explanation:**
- `@chat.trigger`: Registers the route with a user-friendly description.
- `@chat.extract`: Automatically extracts parameters from user input.


### Running the Chat API

Use the `run` method to handle user inputs.

```python
async def main():
    response = await chat.run("I want to cancel my credit card.")
    print(response)
```


### Full Example: FastAPI Integration

```python
from fastapi import FastAPI, Request, Response
from pydantic import BaseModel
from chatsapi import ChatsAPI

app = FastAPI()
chat = ChatsAPI(
    llm_type="gemini",
    llm_model="models/gemini-pro",
    llm_api_key="YOUR_API_KEY",
)

@chat.trigger("Need help with account settings.")
@chat.extract([
    ("account_number", "Account number (a 9-digit number)", int, None),
    ("holder_name", "Account holder's name (a person name)", str, None)
])
async def account_help(chat_message: str, extracted: dict):
    return {"message": chat_message, "extracted": extracted}

class RequestModel(BaseModel):
    message: str

@app.post("/chat")
async def message(request: RequestModel):
    reply = await chat.run(request.message)
    return {"response": reply}
```


### Advanced: Conversation Management

ChatsAPI supports multi-session conversations using unique session IDs:

```python
session_id = chat.set_session()  # Start a new session
response = await chat.conversation("Tell me about my account", session_id)
print(response)

chat.end_session(session_id)  # End the session
```


### Supported LLMs

- OpenAI (ChatGPT)
- Gemini
- LlamaAPI
- Ollama


## Technical Details

- **SBERT**: Used for creating sentence embeddings.
- **HNSWlib**: Provides fast approximate nearest neighbor search.
- **BM25**: Implements Okapi BM25 for token-based matching.
- **SpaCy**: Handles natural language parsing and entity recognition.


![logical_flow.png](docs_src%2Fimages%2Flogical_flow.png)


## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.


## Contribution

Contributions are welcome! Feel free to open issues or submit pull requests.