chatterer 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

chatterer-0.1.3.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.2
+Name: chatterer
+Version: 0.1.3
+Summary: The highest-level interface for various LLM APIs.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: instructor>=1.7.2
+Requires-Dist: langchain>=0.3.19
+Provides-Extra: all
+Requires-Dist: langchain-openai>=0.3.7; extra == "all"
+Requires-Dist: langchain-anthropic>=0.3.8; extra == "all"
+Requires-Dist: langchain-google-genai>=2.0.10; extra == "all"
+Requires-Dist: langchain-ollama>=0.2.3; extra == "all"
+
+# Chatterer
+
+**Simplified, Structured AI Assistant Framework**
+
+`chatterer` is a Python library designed as a type-safe LangChain wrapper for interacting with various language models (OpenAI, Anthropic, Gemini, Ollama, etc.). It supports structured outputs via Pydantic models, plain text responses, and asynchronous calls.
+
+The structured reasoning in `chatterer` is inspired by the [Atom-of-Thought](https://github.com/qixucen/atom) pipeline.
+
+---
+
+## Quick Install
+
+```bash
+pip install chatterer
+```
+
+---
+
+## Quickstart Example
+
+Generate text quickly using OpenAI:
+
+```python
+from chatterer import Chatterer
+
+chat = Chatterer.openai("gpt-4o-mini")
+response = chat.generate("What is the meaning of life?")
+print(response)
+```
+
+Messages can be input as plain strings or structured lists:
+
+```python
+response = chat.generate([{ "role": "user", "content": "What's 2+2?" }])
+print(response)
+```
+
+### Structured Output with Pydantic
+
+```python
+from pydantic import BaseModel
+
+class AnswerModel(BaseModel):
+    question: str
+    answer: str
+
+response = chat.generate_pydantic(AnswerModel, "What's the capital of France?")
+print(response.question, response.answer)
+```
+
+### Async Example
+
+```python
+import asyncio
+
+async def main():
+    response = await chat.agenerate("Explain async in Python briefly.")
+    print(response)
+
+asyncio.run(main())
+```
+
+---
+
+## Atom-of-Thought Pipeline (AoT)
+
+`AoTPipeline` provides structured reasoning by:
+
+- Detecting question domains (general, math, coding, philosophy, multihop).
+- Decomposing questions recursively.
+- Generating direct, decomposition-based, and simplified answers.
+- Combining answers via ensemble.
+
+### AoT Usage Example
+
+```python
+from chatterer import Chatterer
+from chatterer.strategies import AoTStrategy, AoTPipeline
+
+pipeline = AoTPipeline(chatterer=Chatterer.openai(), max_depth=2)
+strategy = AoTStrategy(pipeline=pipeline)
+
+question = "What would Newton discover if hit by an apple falling from 100 meters?"
+answer = strategy.invoke(question)
+print(answer)
+```
+
+---
+
+## Supported Models
+
+- **OpenAI**
+- **Anthropic**
+- **Google Gemini**
+- **Ollama** (local models)
+
+Initialize models easily:
+
+```python
+openai_chat = Chatterer.openai("gpt-4o-mini")
+anthropic_chat = Chatterer.anthropic("claude-3-7-sonnet-20250219")
+gemini_chat = Chatterer.google("gemini-2.0-flash")
+ollama_chat = Chatterer.ollama("deepseek-r1:1.5b")
+```
+
+---
+
+## Advanced Features
+
+- **Streaming responses**
+- **Async/Await support**
+- **Structured outputs with Pydantic models**
+
+---
+
+## Logging
+
+Built-in logging for easy debugging:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+---
+
+## Contributing
+
+Feel free to open an issue or pull request.
+
+---
+
+## License
+
+MIT License
+

chatterer-0.1.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+chatterer/__init__.py,sha256=8j0NJU6mH-aaaCKyQwvJif25n_p7plCCR7pkcij4daY,462
+chatterer/language_model.py,sha256=LgnUtETjvandKi1GrcXwTLDInhuFVGoFZNqfM0P0T4o,38470
+chatterer/strategies/__init__.py,sha256=AKDBC06AdNjPskERssCOsz3qGfFN31mxklmnfhHatJo,389
+chatterer/strategies/atom_of_thoughts.py,sha256=2cHq6kfB_RAb4NbM396NpD40E2aiavZKblMCtUi-u1Q,24948
+chatterer/strategies/base.py,sha256=b2gMPqodp97OP1dkHfj0UqixjdjVhmTw_V5qJ7i2S6g,427
+chatterer-0.1.3.dist-info/METADATA,sha256=1cmKFrkea0VqUyQiUaHCqpMYHwHTr6RzcWYk4syMZfw,3373
+chatterer-0.1.3.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+chatterer-0.1.3.dist-info/top_level.txt,sha256=7nSQKP0bHxPRc7HyzdbKsJdkvPgYD0214o6slRizv9s,10
+chatterer-0.1.3.dist-info/RECORD,,

chatterer/llms/__init__.py

@@ -1,20 +0,0 @@
-from importlib.util import find_spec
-
-from .base import LLM
-
-__all__ = ["LLM"]
-
-if find_spec("langchain_core") is not None:
-    from .langchain import LangchainLLM
-
-    __all__ += ["LangchainLLM"]
-
-if find_spec("ollama") is not None:
-    from .ollama import OllamaLLM
-
-    __all__ += ["OllamaLLM"]
-
-if find_spec("instructor") is not None:
-    from .instructor import InstructorLLM
-
-    __all__ += ["InstructorLLM"]

chatterer/llms/base.py

@@ -1,42 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import (
-    Any,
-    ClassVar,
-    Iterator,
-    Sequence,
-    Type,
-    TypeVar,
-)
-
-from openai.types.chat import ChatCompletionMessageParam
-from pydantic import BaseModel, ConfigDict, Field
-
-P = TypeVar("P", bound=BaseModel)
-
-
-class LLM(BaseModel, ABC):
-    call_kwargs: dict[str, Any] = Field(default_factory=dict)
-    model_config: ClassVar[ConfigDict] = ConfigDict(arbitrary_types_allowed=True)
-
-    def __call__(self, messages: Sequence[ChatCompletionMessageParam]) -> str:
-        return self.generate(messages)
-
-    @abstractmethod
-    def generate(self, messages: Sequence[ChatCompletionMessageParam]) -> str: ...
-
-    @abstractmethod
-    def generate_stream(self, messages: Sequence[ChatCompletionMessageParam]) -> Iterator[str]: ...
-
-    @abstractmethod
-    def generate_pydantic(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> P: ...
-
-    def generate_pydantic_stream(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> Iterator[P]:
-        raise NotImplementedError

chatterer/llms/instructor.py

@@ -1,127 +0,0 @@
-from os import environ
-from typing import (
-    Any,
-    Iterator,
-    Self,
-    Sequence,
-    Type,
-)
-
-from instructor import Instructor, Mode, from_openai
-from openai import OpenAI
-from openai.types.chat import ChatCompletionMessageParam
-from pydantic import BaseModel
-
-from .base import LLM, P
-
-
-class Response(BaseModel):
-    response: str
-
-
-class InstructorLLM(LLM):
-    inst: Instructor
-
-    @classmethod
-    def openai(cls, call_kwargs: dict[str, Any] = {"model": "o3-mini"}) -> Self:
-        return cls(
-            inst=from_openai(OpenAI(), Mode.TOOLS_STRICT),
-            call_kwargs=call_kwargs,
-        )
-
-    @classmethod
-    def anthropic(
-        cls,
-        call_kwargs: dict[str, Any] = {
-            "model": "claude-3-7-sonnet-20250219",
-            "temperature": 0.7,
-            "max_tokens": 8192,
-        },
-    ) -> Self:
-        from anthropic import Anthropic
-        from instructor import from_anthropic
-
-        return cls(
-            inst=from_anthropic(client=Anthropic(), mode=Mode.ANTHROPIC_TOOLS),
-            call_kwargs=call_kwargs,
-        )
-
-    @classmethod
-    def gemini(
-        cls,
-        model_name: str = "gemini-2.0-flash",
-        call_kwargs: dict[str, Any] = {},
-    ) -> Self:
-        from google.generativeai.generative_models import GenerativeModel
-        from instructor import from_gemini
-
-        return cls(
-            inst=from_gemini(client=GenerativeModel(model_name=model_name), mode=Mode.GEMINI_TOOLS),
-            call_kwargs=call_kwargs,
-        )
-
-    @classmethod
-    def deepseek(cls, call_kwargs: dict[str, Any] = {"model": "deepseek-chat"}) -> Self:
-        return cls(
-            inst=from_openai(
-                OpenAI(
-                    base_url="https://api.deepseek.com/v1",
-                    api_key=environ["DEEPSEEK_API_KEY"],
-                ),
-                Mode.TOOLS_STRICT,
-            ),
-            call_kwargs=call_kwargs,
-        )
-
-    def generate(self, messages: Sequence[ChatCompletionMessageParam]) -> str:
-        if self.inst is None:
-            raise ValueError("Instructor instance is not initialized")
-        res = self.inst.chat.completions.create(
-            response_model=Response,
-            messages=list(messages),
-            **self.call_kwargs,
-        )
-        return res.response
-
-    def generate_stream(self, messages: Sequence[ChatCompletionMessageParam]) -> Iterator[str]:
-        if self.inst is None:
-            raise ValueError("Instructor instance is not initialized")
-        last_content: str = ""
-        for res in self.inst.chat.completions.create_partial(
-            response_model=Response,
-            messages=list(messages),
-            **self.call_kwargs,
-        ):
-            content: str = res.response
-            delta: str = content.removeprefix(last_content)
-            if not delta:
-                continue
-            last_content = content
-            yield delta
-
-    def generate_pydantic(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> P:
-        if self.inst is None:
-            raise ValueError("Instructor instance is not initialized")
-        return self.inst.chat.completions.create(
-            response_model=response_model,
-            messages=list(messages),
-            **self.call_kwargs,
-        )
-
-    def generate_pydantic_stream(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> Iterator[P]:
-        if self.inst is None:
-            raise ValueError("Instructor instance is not initialized")
-        for res in self.inst.chat.completions.create_partial(
-            response_model=response_model,
-            messages=list(messages),
-            **self.call_kwargs,
-        ):
-            yield res

chatterer/llms/langchain.py

@@ -1,49 +0,0 @@
-from typing import (
-    Iterator,
-    Sequence,
-    Type,
-)
-
-from langchain_community.adapters.openai import (
-    convert_openai_messages,
-)
-from langchain_core.language_models.chat_models import BaseChatModel
-from openai.types.chat import ChatCompletionMessageParam
-
-from .base import LLM, P
-
-
-class LangchainLLM(LLM):
-    client: BaseChatModel
-
-    def generate(self, messages: Sequence[ChatCompletionMessageParam]) -> str:
-        content = self.client.invoke(convert_openai_messages([dict(msg) for msg in messages])).content
-        if isinstance(content, str):
-            return content
-        else:
-            return "".join(part for part in content if isinstance(part, str))
-
-    def generate_stream(self, messages: Sequence[ChatCompletionMessageParam]) -> Iterator[str]:
-        for chunk in self.client.stream(convert_openai_messages([dict(msg) for msg in messages])):
-            content = chunk.content
-            if isinstance(content, str):
-                yield content
-            elif isinstance(content, list):
-                for part in content:
-                    if isinstance(part, str):
-                        yield part
-                    else:
-                        continue
-            else:
-                continue
-
-    def generate_pydantic(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> P:
-        result = self.client.with_structured_output(response_model).invoke(convert_openai_messages([dict(msg) for msg in messages]))
-        if isinstance(result, response_model):
-            return result
-        else:
-            return response_model.model_validate(result)

chatterer/llms/ollama.py

@@ -1,69 +0,0 @@
-from typing import (
-    Any,
-    Callable,
-    Iterator,
-    Literal,
-    Mapping,
-    Optional,
-    Sequence,
-    Type,
-)
-
-from ollama import Options, Tool, chat
-from openai.types.chat import ChatCompletionMessageParam
-from pydantic.json_schema import JsonSchemaValue
-
-from .base import LLM, P
-
-
-class OllamaLLM(LLM):
-    model: str
-    tools: Optional[Sequence[Mapping[str, Any] | Tool | Callable]] = None
-    stream: bool = False
-    format: Optional[Literal["", "json"] | JsonSchemaValue] = None
-    options: Optional[Mapping[str, Any] | Options] = None
-    keep_alive: Optional[float | str] = None
-
-    def generate(self, messages: Sequence[ChatCompletionMessageParam]) -> str:
-        return "".join(self.generate_stream(messages))
-
-    def generate_stream(self, messages: Sequence[ChatCompletionMessageParam]) -> Iterator[str]:
-        model = str(self.call_kwargs.get("model", self.model))
-        format = self.call_kwargs.get("format", self.format)
-        options = self.call_kwargs.get("options", self.options)
-        keep_alive = self.call_kwargs.get("keep_alive", self.keep_alive)
-        tools = self.call_kwargs.get("tools", self.tools)
-        return (
-            res.message.content or ""
-            for res in chat(
-                model=model,
-                messages=messages,
-                tools=tools,
-                stream=True,
-                format=format,
-                options=options,
-                keep_alive=keep_alive,
-            )
-        )
-
-    def generate_pydantic(
-        self,
-        response_model: Type[P],
-        messages: Sequence[ChatCompletionMessageParam],
-    ) -> P:
-        model = str(self.call_kwargs.get("model", self.model))
-        format = response_model.model_json_schema()
-        options = self.call_kwargs.get("options", self.options)
-        keep_alive = self.call_kwargs.get("keep_alive", self.keep_alive)
-        return response_model.model_validate_json(
-            chat(
-                model=model,
-                messages=messages,
-                tools=None,
-                stream=False,
-                format=format,
-                options=options,
-                keep_alive=keep_alive,
-            ).message.content
-            or ""
-        )

chatterer-0.1.2.dist-info/METADATA

@@ -1,213 +0,0 @@
-Metadata-Version: 2.2
-Name: chatterer
-Version: 0.1.2
-Summary: The highest-level interface for various LLM APIs.
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Requires-Dist: openai>=1.63.2
-Provides-Extra: all
-Requires-Dist: anthropic>=0.49.0; extra == "all"
-Requires-Dist: google-generativeai>=0.8.4; extra == "all"
-Requires-Dist: instructor>=1.7.2; extra == "all"
-Requires-Dist: jsonref>=1.1.0; extra == "all"
-Requires-Dist: langchain-community>=0.3.18; extra == "all"
-Requires-Dist: ollama>=0.4.7; extra == "all"
-
-# chatterer
-
-`chatterer` is a Python library that provides a unified interface for interacting with various Language Model (LLM) backends. It abstracts over different providers such as OpenAI, Anthropic, DeepSeek, Ollama, and Langchain, allowing you to generate completions, stream responses, and even validate outputs using Pydantic models.
-
----
-
-## Features
-
-- **Unified LLM Interface**  
-  Define a common interface (`LLM`) for generating completions and streaming responses regardless of the underlying provider.
-
-- **Multiple Backend Support**  
-  Built-in support for:
-  - **InstructorLLM**: Integrates with OpenAI, Anthropic, and DeepSeek.
-  - **OllamaLLM**: Supports the Ollama model with optional streaming and formatting.
-  - **LangchainLLM**: Leverages Langchain’s chat models with conversion utilities.
-
-- **Pydantic Integration**  
-  Easily validate and structure LLM responses by leveraging Pydantic models with methods like `generate_pydantic` and `generate_pydantic_stream`.
-
----
-
-## Installation
-
-Assuming `chatterer` is published on PyPI, install it via pip:
-
-```bash
-pip install chatterer
-```
-
-Alternatively, clone the repository and install manually:
-
-```bash
-git clone https://github.com/yourusername/chatterer.git
-cd chatterer
-pip install -r requirements.txt
-```
-
----
-
-## Usage
-
-### Importing the Library
-
-You can import the core components directly from `chatterer`:
-
-```python
-from chatterer import LLM, InstructorLLM, OllamaLLM, LangchainLLM
-```
-
----
-
-### Example 1: Using InstructorLLM with OpenAI
-
-```python
-from chatterer import InstructorLLM
-from openai.types.chat import ChatCompletionMessageParam
-
-# Create an instance for OpenAI using the InstructorLLM wrapper
-llm = InstructorLLM.openai(call_kwargs={"model": "o3-mini"})
-
-# Define a conversation message list
-messages: list[ChatCompletionMessageParam] = [
-    {"role": "user", "content": "Hello, how can I help you?"}
-]
-
-# Generate a completion
-response = llm.generate(messages)
-print("Response:", response)
-
-# Stream the response incrementally
-print("Streaming response:")
-for chunk in llm.generate_stream(messages):
-    print(chunk, end="")
-```
-
----
-
-### Example 2: Using OllamaLLM
-
-```python
-from chatterer import OllamaLLM
-from openai.types.chat import ChatCompletionMessageParam
-
-# Initialize an OllamaLLM instance with streaming enabled
-llm = OllamaLLM(model="ollama-model", stream=True)
-
-messages: list[ChatCompletionMessageParam] = [
-    {"role": "user", "content": "Tell me a joke."}
-]
-
-# Generate and print the full response
-print("Response:", llm.generate(messages))
-
-# Stream the response chunk by chunk
-print("Streaming response:")
-for chunk in llm.generate_stream(messages):
-    print(chunk, end="")
-```
-
----
-
-### Example 3: Using LangchainLLM
-
-```python
-from chatterer import LangchainLLM
-from openai.types.chat import ChatCompletionMessageParam
-# Ensure you have a Langchain chat model instance; for example:
-from langchain_core.language_models.chat_models import BaseChatModel
-
-client: BaseChatModel = ...  # Initialize your Langchain chat model here
-llm = LangchainLLM(client=client)
-
-messages: list[ChatCompletionMessageParam] = [
-    {"role": "user", "content": "What is the weather like today?"}
-]
-
-# Generate a complete response
-response = llm.generate(messages)
-print("Response:", response)
-
-# Stream the response
-print("Streaming response:")
-for chunk in llm.generate_stream(messages):
-    print(chunk, end="")
-```
-
----
-
-### Example 4: Using Pydantic for Structured Outputs
-
-```python
-from pydantic import BaseModel
-from chatterer import InstructorLLM
-from openai.types.chat import ChatCompletionMessageParam
-
-# Define a response model
-class MyResponse(BaseModel):
-    response: str
-
-# Initialize the InstructorLLM instance
-llm = InstructorLLM.openai()
-
-messages: list[ChatCompletionMessageParam] = [
-    {"role": "user", "content": "Summarize this text."}
-]
-
-# Generate a structured response using a Pydantic model
-structured_response = llm.generate_pydantic(MyResponse, messages)
-print("Structured Response:", structured_response.response)
-```
-
----
-
-## API Overview
-
-### `LLM` (Abstract Base Class)
-
-- **Methods:**
-  - `generate(messages: Sequence[ChatCompletionMessageParam]) -> str`  
-    Generate a complete text response from a list of messages.
-  
-  - `generate_stream(messages: Sequence[ChatCompletionMessageParam]) -> Iterator[str]`  
-    Stream the response incrementally.
-  
-  - `generate_pydantic(response_model: Type[P], messages: Sequence[ChatCompletionMessageParam]) -> P`  
-    Generate and validate the response using a Pydantic model.
-  
-  - `generate_pydantic_stream(response_model: Type[P], messages: Sequence[ChatCompletionMessageParam]) -> Iterator[P]`  
-    (Optional) Stream validated responses as Pydantic models.
-
-### `InstructorLLM`
-
-- Factory methods to create instances with various backends:
-  - `openai()`
-  - `anthropic()`
-  - `deepseek()`
-
-### `OllamaLLM`
-
-- Supports additional options such as:
-  - `model`, `stream`, `format`, `tools`, `options`, `keep_alive`
-
-### `LangchainLLM`
-
-- Integrates with Langchain's BaseChatModel and converts messages to a compatible format.
-
----
-
-## Contributing
-
-Contributions are highly encouraged! If you find a bug or have a feature request, please open an issue or submit a pull request on the repository. When contributing, please ensure your code adheres to the existing style and passes all tests.
-
----
-
-## License
-
-This project is licensed under the MIT License.

chatterer-0.1.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-chatterer/__init__.py,sha256=zi6zoXdpdWL35p-BYAKrsNWcqi_T3RqpflugLy_93mg,370
-chatterer/llms/__init__.py,sha256=3vUVxkeyBz9xi6nAYg2D7ZtSeuZumTMS5pdJHj3JDpI,435
-chatterer/llms/base.py,sha256=rdYJgpNeDoR-1Cmuea5rBYTJ8Jmtof3U6rFzcUcnG_Y,1196
-chatterer/llms/instructor.py,sha256=QP7rbyENN-4m7kNXGnP1r0kb6ioF0ozkEG0qe5BjQnc,3936
-chatterer/llms/langchain.py,sha256=cuKYWtunCNLNs15P_mlOIbxjvmClrYphSKqAqg3b05k,1723
-chatterer/llms/ollama.py,sha256=amhcGB-xK5ooDAlFzl0aln76x5e13NRKaUkzZ7rcEm0,2304
-chatterer-0.1.2.dist-info/METADATA,sha256=FRpuLBBieJbmIHcSM17V4DU3lw92JonmLCYU8gPYxFk,6192
-chatterer-0.1.2.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
-chatterer-0.1.2.dist-info/top_level.txt,sha256=7nSQKP0bHxPRc7HyzdbKsJdkvPgYD0214o6slRizv9s,10
-chatterer-0.1.2.dist-info/RECORD,,