Refactor LoggingConfig methods for enabling and disabling logging

Add default kwargs logic to Groq, OpenAI, XAI, and Ollama providers

.envrc.template

@@ -1,4 +1,6 @@
-export OPENAI_API_KEY=""
 export ANTHROPIC_API_KEY=""
+export GEMINI_API_KEY=""
+export GROQ_API_KEY=""
+export OLLAMA_HOST_URL=""
+export OPENAI_API_KEY=""
 export XAI_API_KEY=""
-export GROQ_API_KEY=""

.gitignore

@@ -166,3 +166,5 @@ cython_debug/
 .env
 
 src/**
+requirements.txt
+Pipfile

CHANGELOG.md

@@ -0,0 +1,40 @@
+Release History
+===============
+
+## 0.1.6 (2024-10-31)
+
+- Add `sm.Plugin` syntax sugar.
+- Improvements to Anthropic provider, related to max tokens.
+- General improvements.
+- Add tests for structured response.
+- Add `llm_model` to `structured_response`.
+
+## 0.1.5 (2024-10-31)
+
+- Add Gemini provider.
+- Add structured response to Gemini provider.
+- Support for Python 3.10.
+
+## 0.1.4 (2024-10-30)
+
+- Introduce `Session` class to manage repeatability.
+- General improvements.
+
+## 0.1.3 (2024-10-30)
+
+- Make Conversation a context manager.
+- Add more robust conversation plugin hooks — replace `send_hook` with `pre_send_hook` and `post_send_hook`.
+- Change plugin hooks to try/except NotImplementedError.
+- Implement 'did you mean' with provider names. Can do this eventually with model names, as well.
+
+## 0.1.2 (2024-10-29)
+
+- Add ollama provider.
+
+## 0.1.1 (2024-10-29)
+
+- Fix Groq provider.
+
+## 0.1.0 (2024-10-29)
+
+- Initial release.

Dockerfile

@@ -1,12 +0,0 @@
-FROM python:3.12.0
-
-RUN apt-get update -y && apt-get upgrade -y
-RUN pip install --upgrade pip
-
-COPY requirements.txt /src/requirements.txt
-
-WORKDIR /src
-
-RUN pip install -r requirements.txt
-
-ENTRYPOINT ["python", "build.py"]

README.md

@@ -1,59 +1,65 @@
-# SimpleMind: AI for Humans™
+# Simplemind: AI for Humans™
 
-[![Auto Wiki](https://img.shields.io/badge/Auto_Wiki-Mutable.ai-blue)](https://mutable.ai/kennethreitz/simplemind)
+**Keep it simple, keep it human.**
 
-SimpleMind is an AI library designed to simplify your experience with AI APIs in Python. Inspired by a "for humans" philosophy, it abstracts away complexity, giving developers an intuitive and human-friendly way to interact with powerful AI capabilities. With SimpleMind, tapping into AI is as easy as a friendly conversation.
+Simplemind is AI library designed to simplify your experience with AI APIs in Python. Inspired by a "for humans" philosophy, it abstracts away complexity, giving developers an intuitive and human-friendly way to interact with powerful AI capabilities.
+
+![simplemind](https://github.com/user-attachments/assets/36df2103-2583-4958-ad5e-19cda7740256)
 
 ## Features
+
+With Simplemind, tapping into AI is as easy as a friendly conversation.
+
 - **Easy-to-use AI tools**: SimpleMind provides simple interfaces to popular AI services.
 - **Human-centered design**: The library prioritizes readability and usability—no need to be an expert to start experimenting.
 - **Minimal configuration**: Get started quickly, without worrying about configuration headaches.
 
 ## Supported APIs
 
-- **OpenAI's GPT**
-- **Anthropic's Claude**
-- **xAI's Grok**
-- **Groq's Groq**
-- **Ollama's Ollama**
+To specify a specific provider or model, you can use the `llm_provider` and `llm_model` parameters when calling: `generate_text`, `generate_data`, or `create_conversation`. The APIs remain identital between all supported providers/models.
 
-To specify a specific provider or model, you can use the `llm_provider` and `llm_model` parameters when calling: `generate_text`, `generate_data`, or `create_conversation`.
+- [**Anthropic's Claude**](https://www.anthropic.com/claude)
+- [**Google's Gemini**](https://gemini.google/)
+- [**Groq's Groq**](https://groq.com/)
+- [**Ollama**](https://ollama.com)
+- [**OpenAI's GPT**](https://openai.com/gpt)
+- [**xAI's Grok**](https://x.ai/)
+
+If you want to see Simplemind support, additional providers or models, please send a pull request!
 
 ## Why SimpleMind?
 - **Intuitive**: Built with Pythonic simplicity and readability in mind.
 - **For Humans**: Emphasizes a human-friendly interface, just like `requests` for HTTP.
-- **Open Source**: SimpleMind is open source, and contributions are always welcome!
+- **Open Source**: Simplemind is open source, and contributions are always welcome!
 
-## Installation
+Also, why not? :)
 
-Coming soon!
+## Quickstart
+
+Simplemind takes care of the complex API calls so you can focus on what matters—building, experimenting, and creating.
 
 ```bash
 $ pip install simplemind
 ```
 
-## Quickstart
-
-SimpleMind takes care of the complex API calls so you can focus on what matters—building, experimenting, and creating.
-
-```python
-import simplemind as sm
-```
-
-Authenticate your API keys by setting them in the environment variables:
+First, authenticate your API keys by setting them in the environment variables:
 
 ```bash
 $ export OPENAI_API_KEY="sk-..."
 ```
 
-Other supported environment variables: `ANTHROPIC_API_KEY`, `GROK_API_KEY`, `XAI_API_KEY`, and `GROQ_API_KEY`.
+This pattern allows you to keep your API keys private and out of your codebase. Other supported environment variables: `ANTHROPIC_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, and `GEMINI_API_KEY`.
 
+Next, import Simplemind and start using it:
 
+```python
+import simplemind as sm
+```
 
 
 ## Examples
 
-Here are some examples of how to use SimpleMind:
+Here are some examples of how to use Simplemind:
 
 ### Text Completion
 
@@ -64,7 +70,7 @@ Generate a response from an AI model based on a given prompt:
 "The meaning of life is a profound philosophical question that has been explored by cultures, religions, and philosophers for centuries. Different people and belief systems offer varying interpretations:\n\n1. **Religious Perspectives:** Many religions propose that the meaning of life is to fulfill a divine purpose, serve God, or reach an afterlife. For example, Christianity often emphasizes love, faith, and service to God and others as central to life’s meaning.\n\n2. **Philosophical Views:** Philosophers offer diverse answers. Existentialists like Jean-Paul Sartre argue that life has no inherent meaning, and it is up to individuals to create their own purpose. Others, like Aristotle, suggest that achieving eudaimonia (flourishing or happiness) through virtuous living is the key to a meaningful life.\n\n3. **Scientific and Secular Approaches:** Some people find meaning through understanding the natural world, contributing to human knowledge, or through personal accomplishments and happiness. They may view life's meaning as a product of connection, legacy, or the pursuit of knowledge and creativity.\n\n4. **Personal Perspective:** For many, the meaning of life is deeply personal, involving their relationships, passions, and goals. These individuals define life's purpose through experiences, connections, and the impact they have on others and the world.\n\nUltimately, the meaning of life is a subjective question, with each person finding their own answers based on their beliefs, experiences, and reflections."
 ```
 
-### Structured Response
+### Structured Data with Pydantic
 
 You can use Pydantic models to structure the response from the LLM, if the LLM supports it.
 
@@ -106,15 +112,34 @@ To continue the conversation, you can call `conversation.send()` again, which re
 <Message role=assistant text="The meaning of life is a profound philosophical question that has been explored by cultures, religions, and philosophers for centuries. Different people and belief systems offer varying interpretations:\n\n1. **Religious Perspectives:** Many religions propose that the meaning of life is to fulfill a divine purpose, serve God, or reach an afterlife. For example, Christianity often emphasizes love, faith, and service to God and others as central to life’s meaning.\n\n2. **Philosophical Views:** Philosophers offer diverse answers. Existentialists like Jean-Paul Sartre argue that life has no inherent meaning, and it is up to individuals to create their own purpose. Others, like Aristotle, suggest that achieving eudaimonia (flourishing or happiness) through virtuous living is the key to a meaningful life.\n\n3. **Scientific and Secular Approaches:** Some people find meaning through understanding the natural world, contributing to human knowledge, or through personal accomplishments and happiness. They may view life’s meaning as a product of connection, legacy, or the pursuit of knowledge and creativity.\n\n4. **Personal Perspective:** For many, the meaning of life is deeply personal, involving their relationships, passions, and goals. These individuals define life’s purpose through experiences, connections, and the impact they have on others and the world.\n\nUltimately, the meaning of life is a subjective question, with each person finding their own answers based on their beliefs, experiences, and reflections.">
 ```
 
+### Stop Repeating Yourself
+
+You can use the `Session` class to set default parameters for all calls:
+
+```python
+# Create a session with defaults
+gpt_4o_mini = sm.Session(llm_provider="openai", llm_model="gpt-4o-mini")
+
+# Now all calls use these defaults
+response = gpt_4o_mini.generate_text("Hello!")
+conversation = gpt_4o_mini.create_conversation()
+```
+
+This maintains the simplicity of the original API while reducing repetition. The session object also supports overriding defaults on a per-call basis:
+
+```python
+response = gpt_4o_mini.generate_text(
+    "Complex task here",
+    llm_model="gpt-4"
+)
+```
+
 ### Basic Memory Plugin
 
 Harnessing the power of Python, you can easily create your own plugins to add additional functionality to your conversations:
 
 ```python
-import simplemind as sm
-
-
-class SimpleMemoryPlugin:
+class SimpleMemoryPlugin(sm.BasePlugin):
     def __init__(self):
         self.memories = [
             "the earth has fictionally beeen destroyed.",
@@ -124,7 +149,7 @@ class SimpleMemoryPlugin:
     def yield_memories(self):
         return (m for m in self.memories)
 
-    def send_hook(self, conversation: sm.Conversation):
+    def pre_send_hook(self, conversation: sm.Conversation):
         for m in self.yield_memories():
             conversation.add_message(role="system", text=m)
 
@@ -135,7 +160,7 @@ conversation.add_plugin(SimpleMemoryPlugin())
 
 conversation.add_message(
     role="user",
-    text="Write a poem about the moon",
+    text="Please write a poem about the moon",
 )
 ```
 ```pycon
@@ -171,8 +196,12 @@ A reminder that in tales and fun,
 The universe is never done.
 ```
 
+Simple, yet effective.
+
 Please see the [examples](examples) directory for executable examples.
 
+-------------------
+
 ## Contributing
 We welcome contributions of all kinds. Feel free to open issues for bug reports or feature requests, and submit pull requests to make SimpleMind even better.
 
@@ -183,17 +212,9 @@ To get started:
 3. Make your changes.
 4. Submit a pull request.
 
-## Building
-1. Clone the repository.
-2. `cd` to the root directory.
-3. Run `docker-compose up --build`
-
 ## License
-SimpleMind is licensed under the Apache 2.0 License.
+Simplemind is licensed under the Apache 2.0 License.
 
 ## Acknowledgements
-SimpleMind is inspired by the philosophy of "code for humans" and aims to make working with AI models accessible to all. Special thanks to the open-source community for their contributions and inspiration.
+Simplemind is inspired by the philosophy of "code for humans" and aims to make working with AI models accessible to all. Special thanks to the open-source community for their contributions and inspiration.
 
----------------
-
-SimpleMind: Keep it simple, keep it human.

docker-compose.yaml

@@ -1,10 +0,0 @@
-services:
-  simplemind:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    volumes:
-      - ./simplemind:/src/simplemind
-      - ./build.py:/src/build.py
-    env_file:
-      - .env

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import simplemind
+
+project = "simplemind"
+copyright = "2024 Kenneth Reitz"
+author = "Kenneth Reitz"
+release = "v0.1.6"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,236 @@
+.. simplemind documentation master file, created by
+   sphinx-quickstart on Wed Oct 30 08:08:14 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+SimpleMind: AI for Humans™
+==========================
+
+**SimpleMind** is a versatile Python library designed to simplify interactions with various AI models. It provides a consistent and user-friendly interface to numerous AI providers, enabling developers to seamlessly integrate powerful AI capabilities into their applications without the overhead of managing multiple APIs and configurations.
+
+Features
+--------
+
+- **Unified Interface**: Interact with multiple AI providers using a single, consistent API
+- **Plugin Architecture**: Extend functionality with custom plugins for tasks like memory management and sentiment analysis
+- **Structured Data Support**: Generate and manipulate structured data using Pydantic models
+- **Human-Centered Design**: Prioritizes readability and ease of use, making AI integration accessible to all developers
+- **Minimal Configuration**: Quickly get started without extensive setup or configuration
+
+Supported Providers
+------------------
+
+SimpleMind supports a variety of AI providers:
+
+- `OpenAI's GPT <https://openai.com/gpt>`_
+- `Anthropic's Claude <https://www.anthropic.com/claude>`_
+- `xAI's Grok <https://x.ai/>`_
+- `Groq's Groq <https://groq.com/>`_
+- `Ollama <https://ollama.com>`_
+
+Installation
+-----------
+
+Install SimpleMind using pip:
+
+.. code-block:: shell
+
+    $ pip install simplemind
+
+Quickstart
+----------
+
+1. Set your API keys as environment variables:
+
+   .. code-block:: bash
+
+       $ export OPENAI_API_KEY="sk-..."
+       $ export ANTHROPIC_API_KEY="..."
+       $ export XAI_API_KEY="..."
+       $ export GROQ_API_KEY="..."
+
+This is the only required configuration.
+
+2. Import and use SimpleMind:
+
+   .. code-block:: python
+
+       import simplemind as sm
+
+       # Generate text using the default provider (OpenAI)
+       response = sm.generate_text("Write a poem about the moon.", llm_model="gpt-4o-mini")
+       print(response)
+
+Things to know:
+
+- The primary function for generating text is ``generate_text()``, which is used in the example above.
+- To generate structured data, use ``generate_data()``, which most providers support. This is extremely useful.
+- The third function, ``create_conversation()``, is used to engage in conversations with AI models.
+
+All of these functions accept an ``llm_model`` and ``llm_provider`` parameter, which allows you to specify the AI model to use. If not provided, the default model for the given provider will be used.
+
+
+Usage Examples
+--------------
+
+Here are some examples demonstrating SimpleMind's key features. From generating creative text and structured data to engaging in conversations and extending functionality with plugins, these examples showcase the library's versatility and ease of use.
+
+Feel free to adapt these examples to your specific use cases!
+
+
+Text Generation
+~~~~~~~~~~~~~~~
+
+This example generates a poem about the moon using the ``gpt-4o-mini`` model.
+
+.. code-block:: python
+
+    import simplemind as sm
+
+    poem = sm.generate_text("Write a poem about the moon.", llm_model="gpt-4o-mini")
+    print(poem)
+
+Structured Data Generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example generates a poem about love using the ``gpt-4o-mini`` model.
+
+.. code-block:: python
+
+    from pydantic import BaseModel
+
+    class Poem(BaseModel):
+        title: str
+        content: str
+
+    poem = sm.generate_data(
+        prompt="Write a poem about love",
+        llm_model="gpt-4o-mini",
+        response_model=Poem,
+    )
+    print(poem)
+
+Conversational AI
+~~~~~~~~~~~~~~~~~
+
+This example engages in a conversation with the ``gpt-4o-mini`` model.
+
+
+.. code-block:: python
+
+    conversation = sm.create_conversation(llm_model="gpt-4o-mini")
+    conversation.add_message("user", "Hi there, how are you?")
+    response = conversation.send()
+    print(response.text)
+
+Plugins
+~~~~~~~
+
+This example adds a simple custom memory plugin to the conversation.
+
+.. code-block:: python
+
+    class SimpleMemoryPlugin:
+        def __init__(self):
+            self.memories = ["the moon is made of cheese."]
+
+        def send_hook(self, conversation):
+            for memory in self.memories:
+                conversation.add_message(role="system", text=memory)
+
+    conversation = sm.create_conversation()
+    conversation.add_plugin(SimpleMemoryPlugin())
+    conversation.add_message("user", "Write a poem about the moon")
+    print(conversation.send().text)
+
+Plugin Development
+~~~~~~~~~~~~~~~~~~
+
+Plugins in SimpleMind follow a simple hook-based architecture. The ``send_hook`` method shown above is just one of several hooks available. Here's a more detailed example showing the complete plugin interface:
+
+.. code-block:: python
+
+    from simplemind.plugins import BasePlugin
+
+    class CustomPlugin(BasePlugin):
+        def __init__(self):
+            self.conversation_history = []
+
+        def initialize_hook(self, conversation):
+            """Called when the plugin is first added to a conversation."""
+            print("Plugin initialized!")
+
+        def pre_send_hook(self, conversation):
+            """Called before the conversation is sent to the AI provider."""
+            # Add any system messages or modify the conversation
+            conversation.add_message("system", "Remember to be helpful.")
+
+        def send_hook(self, conversation):
+            """Called during the send process."""
+            # Add messages or modify the conversation
+            self.conversation_history.append(conversation.messages)
+
+        def post_send_hook(self, conversation, response):
+            """Called after receiving a response from the AI provider."""
+            # Process or modify the response
+            return response
+
+        def cleanup_hook(self):
+            """Called when the plugin is removed or the conversation ends."""
+            self.conversation_history.clear()
+
+All plugins should inherit from ``BasePlugin``, which provides default no-op implementations of these hooks. You only need to implement the hooks you want to use. Here's a simpler example:
+
+.. code-block:: python
+
+    from simplemind.plugins import BasePlugin
+
+    class LoggingPlugin(BasePlugin):
+        def pre_send_hook(self, conversation):
+            print(f"Sending conversation with {len(conversation.messages)} messages")
+
+        def post_send_hook(self, conversation, response):
+            print(f"Received response: {response.text[:50]}...")
+            return response
+
+    conversation = sm.create_conversation()
+    conversation.add_plugin(LoggingPlugin())
+    conversation.add_message("user", "Hello!")
+    response = conversation.send()
+
+Plugins can be used to implement features like:
+
+- Conversation logging
+- Memory management
+- Response filtering
+- Token counting
+- Custom prompt engineering
+- Analytics and monitoring
+
+Multiple plugins can be added to a single conversation, and they will be executed in the order they were added.
+
+
+Contributing
+-----------
+
+1. Fork the Repository
+2. Create a New Branch
+3. Make Your Changes
+4. Submit a Pull Request
+
+Please review our `Code of Conduct <LICENSE>`_ before contributing.
+
+License
+-------
+
+SimpleMind is licensed under the `Apache 2.0 License <LICENSE>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   api
+   contributing
+   changelog

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

examples/contextual_memory.py

@@ -1,15 +1,20 @@
-from _context import sm
-
-from pydantic import BaseModel
-import openai
-import faiss
-import numpy as np
 import os
 import pickle
 
+import faiss
+import numpy as np
+import openai
+from _context import sm
+from pydantic import BaseModel
 
-class ContextualMemoryPlugin:
-    def __init__(self, api_key: str, memory_file: str = "memories.pkl", embedding_model: str = "text-embedding-ada-002"):
+
+class ContextualMemoryPlugin(sm.BasePlugin):
+    def __init__(
+        self,
+        api_key: str,
+        memory_file: str = "memories.pkl",
+        embedding_model: str = "text-embedding-ada-002",
+    ):
         openai.api_key = api_key
         self.memory_file = memory_file
         self.embedding_model = embedding_model
@@ -35,29 +40,29 @@ class ContextualMemoryPlugin:
     def build_faiss_index(self):
         if self.embeddings:
             self.index = faiss.IndexFlatL2(len(self.embeddings[0]))
-            self.index.add(np.array(self.embeddings).astype('float32'))
+            self.index.add(np.array(self.embeddings).astype("float32"))
         else:
             self.index = faiss.IndexFlatL2(1536)
 
     def get_embedding(self, text: str) -> list:
         response = openai.Embedding.create(input=text, model=self.embedding_model)
-        return response['data'][0]['embedding']
+        return response["data"][0]["embedding"]
 
     def add_memory(self, memory: str):
         embedding = self.get_embedding(memory)
         self.memories.append(memory)
         self.embeddings.append(embedding)
-        self.index.add(np.array([embedding]).astype('float32'))
+        self.index.add(np.array([embedding]).astype("float32"))
         self.save_memories()
 
     def retrieve_memories(self, query: str, top_k: int = 3) -> list:
         if not self.index or len(self.embeddings) == 0:
             return []
         query_embedding = self.get_embedding(query)
-        D, I = self.index.search(np.array([query_embedding]).astype('float32'), top_k)
+        D, I = self.index.search(np.array([query_embedding]).astype("float32"), top_k)
         return [self.memories[i] for i in I[0] if i < len(self.memories)]
 
-    def send_hook(self, conversation: sm.Conversation):
+    def pre_send_hook(self, conversation: sm.Conversation):
         # Retrieve relevant memories based on the latest user message
         if conversation.messages:
             last_user_message = conversation.messages[-1].text
@@ -69,13 +74,16 @@ class ContextualMemoryPlugin:
         # Optionally, add the AI's response to memories
         self.add_memory(response)
 
+
 # Example Usage
 
+
 # Define a Pydantic model if needed
 class Story(BaseModel):
     title: str
     content: str
 
+
 # Initialize the conversation with the ContextualMemoryPlugin
 memory_plugin = ContextualMemoryPlugin(api_key=sm.settings.OPENAI_API_KEY)
 

examples/generate_data.py

@@ -1,29 +1,43 @@
-from typing import List
-
-from pydantic import BaseModel
+from typing import Iterator, List
 
 from _context import sm
+from pydantic import BaseModel
 
 
 class Movie(BaseModel):
     title: str
     year: int
 
+
 class MovieCharecter(BaseModel):
     name: str
     actor: str
 
+
 class MovieQuote(BaseModel):
     quote: str
     movie: Movie
     charecter: MovieCharecter
 
+
 class QuotesList(BaseModel):
     quotes: List[MovieQuote]
-    theme: str
 
 
-quotes = sm.generate_data(llm_provider="openai", llm_model="gpt-4o-mini", prompt="Generate 20 quotes from famous movies", response_model=QuotesList)
+def gen_quotes(n: int = 10) -> Iterator[MovieQuote]:
+    """Generate a list of quotes from famous movies."""
 
-for quote in quotes.quotes:
-    print(f"{quote.charecter.name} from {quote.movie.title} ({quote.movie.year}): {quote.quote!r}")
+    for q in sm.generate_data(
+        llm_provider="openai",
+        llm_model="gpt-4o-mini",
+        prompt=f"Generate {n} quotes from famous movies",
+        response_model=QuotesList,
+    ).quotes:
+        yield q
+
+
+if __name__ == "__main__":
+    for quote in gen_quotes(n=20):
+        print(
+            f"{quote.charecter.name} from {quote.movie.title} ({quote.movie.year}): {quote.quote!r}"
+        )

examples/math_plugin.py

@@ -1,9 +1,11 @@
 from _context import sm
 
 
-class MathPlugin:
+class MathPlugin(sm.BasePlugin):
     def send_hook(self, conversation: sm.Conversation):
         last_user_message = conversation.get_last_message(role="user")
+        if last_user_message is None:
+            return
         if "calculate" in last_user_message.text.lower():
             expression = last_user_message.text.lower().replace("calculate", "").strip()
             try:
@@ -14,7 +16,7 @@ class MathPlugin:
             except Exception:
                 conversation.add_message(
                     role="assistant",
-                    text="I'm sorry, I couldn't compute that expression.",
+                    text="I'm sorry, I couldn't compute that expression. Please try again.",
                 )
 
 

examples/sentiment_analysis.py

@@ -1,8 +1,8 @@
-from _context import sm
-
-from pydantic import BaseModel
 from typing import Literal
 
+from _context import sm
+from pydantic import BaseModel
+
 
 class SentimentAnalysis(BaseModel):
     sentiment: Literal["positive", "negative", "neutral"]

examples/simple_logging_plugin.py

@@ -0,0 +1,31 @@
+import simplemind as sm
+
+
+class LoggingPlugin(sm.BasePlugin):
+    def pre_send_hook(self, conversation):
+        print(f"Sending conversation with {len(conversation.messages)} messages")
+
+    def add_message_hook(self, conversation, message):
+        print(f"Adding message to conversation: {message.text}")
+
+    def cleanup_hook(self, conversation):
+        print(f"Cleaning up conversation with {len(conversation.messages)} messages")
+
+    def initialize_hook(self, conversation):
+        print("Initializing conversation")
+
+    def post_send_hook(self, conversation, response):
+        print(f"Received response: {response.text}")
+
+
+with sm.create_conversation() as conversation:
+    # Add the logging plugin.
+    conversation.add_plugin(LoggingPlugin())
+
+    # Add a message to the conversation.
+    conversation.add_message("user", "Hello!", meta={})
+
+    # Send the conversation.
+    response = conversation.send()
+
+print(f"Response: {response.text}")

examples/simple_memory.py

@@ -11,9 +11,9 @@ class SimpleMemoryPlugin:
     def yield_memories(self):
         return (m for m in self.memories)
 
-    def send_hook(self, conversation: sm.Conversation):
+    def initialize_hook(self, conversation: sm.Conversation):
         for m in self.yield_memories():
-            conversation.add_message(role="system", text=m)
+            conversation.prepend_system_message(role="system", text=m)
 
 
 conversation = sm.create_conversation(llm_model="grok-beta", llm_provider="xai")
@@ -21,7 +21,7 @@ conversation.add_plugin(SimpleMemoryPlugin())
 
 conversation.add_message(
     role="user",
-    text="Write a poem about the moon",
+    text="Please write a poem about the moon",
 )
 
 r = conversation.send()

examples/translate_text.py

@@ -1,9 +1,13 @@
 from _context import sm
 
-conversation = sm.create_conversation(llm_model="gpt-4o", llm_provider="openai")
 
-conversation.add_message(
-    "user", "Translate the following text to French: 'Hello, world!'"
-)
+def translate_to_french(text: str) -> str:
+    conversation = sm.create_conversation(llm_model="gpt-4o", llm_provider="openai")
 
-print(conversation.send().text)
+    conversation.add_message(
+        "user", f"Translate the following text to French: {text!r}"
+    )
+    return conversation.send().text
+
+
+print(translate_to_french("an omlette with cheese"))

examples/two_llms_talking.py

@@ -0,0 +1,59 @@
+import time
+
+import simplemind as sm
+
+
+class ConversationPlugin(sm.BasePlugin):
+    def post_send_hook(self, conversation, response):
+        # Print the LLM model and the response text.
+        print(f"{conversation.llm_model}:\n{response.text.strip()}\n\n------------\n")
+
+
+def have_conversation(rounds: int = 3):
+    # Create two conversations - one for each AI
+    with (
+        sm.create_conversation(
+            llm_model="claude-3-5-sonnet-20241022", llm_provider="anthropic"
+        ) as claude_conv,
+        sm.create_conversation(
+            llm_model="llama3.2", llm_provider="ollama"
+        ) as llama_conv,
+    ):
+
+        # Add our plugin to both
+        plugin = ConversationPlugin()
+        claude_conv.add_plugin(plugin)
+        llama_conv.add_plugin(plugin)
+
+        # Start the conversation
+        prompt = "What do you think about the future of artificial intelligence? Please keep your response brief."
+        claude_conv.add_message("user", prompt, meta={})
+        claude_response = claude_conv.send()
+
+        # Have them discuss back and forth
+        for _ in range(rounds):
+            # Llama responds to Claude
+            llama_conv.add_message(
+                "user",
+                f"Respond to this statement from another AI: {claude_response.text}",
+                meta={},
+            )
+            llama_response = llama_conv.send()
+
+            time.sleep(1)  # Add a small delay between responses
+
+            # Claude responds to Llama
+            claude_conv.add_message(
+                "user",
+                f"Respond to this statement from another AI: {llama_response.text}",
+                meta={},
+            )
+            claude_response = claude_conv.send()
+
+            time.sleep(1)
+
+
+if __name__ == "__main__":
+    print("Starting AI conversation...\n")
+    have_conversation()
+    print("\nConversation ended.")

pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "simplemind"
-version = "0.1.0"
+version = "0.1.6"
 description = "An experimental client for AI providers that intends to replace LangChain and LangGraph for most common use cases."
 readme = "README.md"
-requires-python = ">=3.11"
-dependencies = ["pydantic", "pydantic-settings", "instructor", "openai", "anthropic", "groq"]
+requires-python = ">=3.10"
+dependencies = ["pydantic", "pydantic-settings", "instructor", "openai", "anthropic", "ollama", "groq", "google-generativeai"]
 
 [build-system]
 requires = ["hatchling"]

simplemind/__init__.py

@@ -1,21 +1,95 @@
-from .models import Conversation
-from .utils import find_provider
+from typing import List, Type
+
+from .models import BaseModel, BasePlugin, Conversation
 from .settings import settings
+from .utils import find_provider
 
 
-def create_conversation(llm_model=None, llm_provider=None):
+class Session:
+    """A session object that maintains configuration across multiple API calls.
+
+    Similar to `requests.Session`, this allows you to specify default settings
+    that will be used for all operations within the session.
+    """
+
+    def __init__(
+        self,
+        *,
+        llm_provider: str = settings.DEFAULT_LLM_PROVIDER,
+        llm_model: str | None = None,
+        **kwargs,
+    ):
+        self.llm_provider = llm_provider
+        self.llm_model = llm_model
+        self.default_kwargs = kwargs
+
+    def generate_text(self, prompt: str, **kwargs) -> str:
+        """Generate text using the session's default provider and model."""
+        merged_kwargs = {**self.default_kwargs, **kwargs}
+        return generate_text(
+            prompt=prompt,
+            llm_provider=self.llm_provider,
+            llm_model=self.llm_model,
+            **merged_kwargs,
+        )
+
+    def generate_data(
+        self, prompt: str, response_model: Type[BaseModel], **kwargs
+    ) -> BaseModel:
+        """Generate structured data using the session's default provider and model."""
+        merged_kwargs = {**self.default_kwargs, **kwargs}
+        return generate_data(
+            prompt=prompt,
+            response_model=response_model,
+            llm_provider=self.llm_provider,
+            llm_model=self.llm_model,
+            **merged_kwargs,
+        )
+
+    def create_conversation(self, **kwargs) -> Conversation:
+        """Create a conversation using the session's default provider and model."""
+        merged_kwargs = {**self.default_kwargs, **kwargs}
+        return create_conversation(
+            llm_provider=self.llm_provider, llm_model=self.llm_model, **merged_kwargs
+        )
+
+
+def create_conversation(
+    *,
+    llm_model: str | None = None,
+    llm_provider: str | None = None,
+    plugins: List[BasePlugin] | None = None,
+    **kwargs,
+) -> Conversation:
     """Create a new conversation."""
 
-    return Conversation(
-        llm_model=llm_model, llm_provider=llm_provider or settings.DEFAULT_LLM_PROVIDER
+    # Create the conversation.
+    conversation = Conversation(
+        llm_model=llm_model,
+        llm_provider=llm_provider or settings.DEFAULT_LLM_PROVIDER,
     )
 
+    # Add plugins to the conversation.
+    for plugin in plugins or []:
+        conversation.add_plugin(plugin)
 
-def generate_data(prompt, *, llm_model=None, llm_provider=None, response_model=None):
+    return conversation
+
+
+def generate_data(
+    prompt: str,
+    *,
+    llm_model: str | None = None,
+    llm_provider: str | None = None,
+    response_model: Type[BaseModel],
+    **kwargs,
+) -> BaseModel:
     """Generate structured data from a given prompt."""
 
+    # Find the provider.
     provider = find_provider(llm_provider or settings.DEFAULT_LLM_PROVIDER)
 
+    # Generate the data.
     return provider.structured_response(
         prompt=prompt,
         llm_model=llm_model,
@@ -23,18 +97,32 @@ def generate_data(prompt, *, llm_model=None, llm_provider=None, response_model=N
     )
 
 
-def generate_text(prompt, *, llm_model=None, llm_provider=None, **kwargs):
+def generate_text(
+    prompt: str,
+    *,
+    llm_model: str | None = None,
+    llm_provider: str | None = None,
+    **kwargs,
+) -> str:
     """Generate text from a given prompt."""
+
+    # Find the provider.
     provider = find_provider(llm_provider or settings.DEFAULT_LLM_PROVIDER)
 
+    # Generate the text.
     return provider.generate_text(prompt=prompt, llm_model=llm_model, **kwargs)
 
 
+# Syntax sugar.
+Plugin = BasePlugin
+
 __all__ = [
-    "Conversation",
     "create_conversation",
     "find_provider",
     "generate_data",
     "generate_text",
     "settings",
+    "BasePlugin",
+    "Session",
+    "Plugin",
 ]

simplemind/logging.py

@@ -0,0 +1,27 @@
+import time
+from typing import Any, Callable
+
+import logfire
+
+from .settings import settings
+
+
+def logger(func: Callable[..., Any]) -> Callable[..., Any]:
+    """A @logger decorator that logs the function parameters, function returns, and exceptions raised if logging is enabled."""
+
+    def wrapper(*args, **kwargs) -> Any:
+        if not settings.logging.enabled:
+            return func(*args, **kwargs)
+        logfire.info(f"Calling {func.__name__} with args: {args}, kwargs: {kwargs}")
+        t1 = time.perf_counter()
+        try:
+            result = func(*args, **kwargs)
+            t2 = time.perf_counter()
+            logfire.info(f"{func.__name__} returned: {result} in {t2-t1} seconds")
+            return result
+        except Exception as e:
+            t2 = time.perf_counter()
+            logfire.error(f"Error in {func.__name__}: {e} in {t2-t1} seconds")
+            raise e
+
+    return wrapper

simplemind/models.py

@@ -1,18 +1,18 @@
 import uuid
-from abc import ABC, abstractmethod
 from datetime import datetime
+from types import TracebackType
 from typing import Any, Dict, List, Literal, Optional
 
-
 from pydantic import BaseModel, Field
 
 from .utils import find_provider
 
-
 MESSAGE_ROLE = Literal["system", "user", "assistant"]
 
 
 class SMBaseModel(BaseModel):
+    """The base SimpleMind model class."""
+
     date_created: datetime = Field(default_factory=datetime.now)
 
     def __str__(self):
@@ -22,16 +22,36 @@ class SMBaseModel(BaseModel):
         return str(self)
 
 
-class BasePlugin(ABC):
+class BasePlugin(SMBaseModel):
     """The base conversation plugin class."""
 
-    @abstractmethod
-    def send_hook(self, conversation: "Conversation"):
-        """Send a hook to the plugin."""
+    # Plugin metadata.
+    meta: Dict[str, Any] = {}
+
+    def initialize_hook(self, conversation: "Conversation") -> Any:
+        """Initialize a hook for the plugin."""
+        raise NotImplementedError
+
+    def cleanup_hook(self, conversation: "Conversation") -> Any:
+        """Cleanup a hook for the plugin."""
+        raise NotImplementedError
+
+    def add_message_hook(self, conversation: "Conversation", message: "Message") -> Any:
+        """Add a message hook for the plugin."""
+        raise NotImplementedError
+
+    def pre_send_hook(self, conversation: "Conversation") -> Any:
+        """Pre-send hook for the plugin."""
+        raise NotImplementedError
+
+    def post_send_hook(self, conversation: "Conversation", response: "Message") -> Any:
+        """Post-send hook for the plugin."""
         raise NotImplementedError
 
 
 class Message(SMBaseModel):
+    """A message in a conversation."""
+
     role: MESSAGE_ROLE
     text: str
     meta: Dict[str, Any] = {}
@@ -43,7 +63,16 @@ class Message(SMBaseModel):
         return f"<Message role={self.role} text={self.text!r}>"
 
     @classmethod
-    def from_raw_response(cls, *, text: str, raw):
+    def from_raw_response(cls, *, text: str, raw: Any) -> "Message":
+        """Create a Message instance from a raw response.
+
+        Args:
+            text (str): The message text.
+            raw (Any): The raw response data.
+
+        Returns:
+            Message: A new Message instance.
+        """
         self = cls()
         self.text = text
         self.raw = raw
@@ -51,40 +80,106 @@ class Message(SMBaseModel):
 
 
 class Conversation(SMBaseModel):
+    """A conversation between a user and an assistant."""
+
     id: str = Field(default_factory=lambda: str(uuid.uuid4()))
     messages: List[Message] = []
     llm_model: Optional[str] = None
     llm_provider: Optional[str] = None
-    plugins: List[Any] = []
+    plugins: List[BasePlugin] = []
 
     def __str__(self):
         return f"<Conversation id={self.id!r}>"
 
+    def __enter__(self):
+        # Execute all initialize hooks.
+        for plugin in self.plugins:
+            if hasattr(plugin, "initialize_hook"):
+                try:
+                    plugin.initialize_hook(self)
+                except NotImplementedError:
+                    pass
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException],
+        exc_value: BaseException,
+        traceback: TracebackType,
+    ) -> None:
+        """Execute all cleanup hooks."""
+        for plugin in self.plugins:
+            if hasattr(plugin, "cleanup_hook"):
+                try:
+                    plugin.cleanup_hook(self)
+                except NotImplementedError:
+                    pass
+
+    def prepend_system_message(
+        self, role: MESSAGE_ROLE, text: str, meta: Dict[str, Any] | None = None
+    ):
+        """Prepend a system message to the conversation."""
+        self.messages = [Message(role=role, text=text, meta=meta or {})] + self.messages
+
     def add_message(
         self, role: MESSAGE_ROLE, text: str, meta: Optional[Dict[str, Any]] = None
     ):
         """Add a new message to the conversation."""
+
+        # Ensure meta is a dict.
         if meta is None:
             meta = {}
+
+        # Execute all add-message hooks.
+        for plugin in self.plugins:
+            if hasattr(plugin, "add_message_hook"):
+                try:
+                    plugin.add_message_hook(
+                        self, Message(role=role, text=text, meta=meta)
+                    )
+                except NotImplementedError:
+                    pass
+
+        # Add the message to the conversation.
         self.messages.append(Message(role=role, text=text, meta=meta))
 
     def send(
-        self, llm_model: Optional[str] = None, llm_provider: Optional[str] = None
+        self,
+        llm_model: str | None = None,
+        llm_provider: str | None = None,
     ) -> Message:
         """Send the conversation to the LLM."""
-        for plugin in self.plugins:
-            plugin.send_hook(self)
 
+        # Execute all pre send hooks.
+        for plugin in self.plugins:
+            if hasattr(plugin, "pre_send_hook"):
+                try:
+                    plugin.pre_send_hook(self)
+                except NotImplementedError:
+                    pass
+
+        # Find the provider and send the conversation.
         provider = find_provider(llm_provider or self.llm_provider)
         response = provider.send_conversation(self)
 
+        # Execute all post-send hooks.
+        for plugin in self.plugins:
+            if hasattr(plugin, "post_send_hook"):
+                try:
+                    plugin.post_send_hook(self, response)
+                except NotImplementedError:
+                    pass
+
+        # Add the response to the conversation.
         self.add_message(role="assistant", text=response.text, meta=response.meta)
+
         return response
 
-    def get_last_message(self, role: MESSAGE_ROLE) -> Optional[Message]:
+    def get_last_message(self, role: MESSAGE_ROLE) -> Message | None:
         """Get the last message with the given role."""
         return next((m for m in reversed(self.messages) if m.role == role), None)
 
-    def add_plugin(self, plugin: Any):
+    def add_plugin(self, plugin: BasePlugin) -> None:
         """Add a plugin to the conversation."""
         self.plugins.append(plugin)

simplemind/providers/__init__.py

@@ -1,9 +1,11 @@
 from typing import List, Type
 
-from simplemind.providers._base import BaseProvider
-from simplemind.providers.anthropic import Anthropic
-from simplemind.providers.groq import Groq
-from simplemind.providers.openai import OpenAI
-from simplemind.providers.xai import XAI
+from ._base import BaseProvider
+from .anthropic import Anthropic
+from .gemini import Gemini
+from .groq import Groq
+from .ollama import Ollama
+from .openai import OpenAI
+from .xai import XAI
 
-providers: List[Type[BaseProvider]] = [Anthropic, Groq, OpenAI, XAI]
+providers: List[Type[BaseProvider]] = [Anthropic, Gemini, Groq, OpenAI, Ollama, XAI]

simplemind/providers/_base.py

@@ -1,6 +1,14 @@
 from abc import ABC, abstractmethod
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Type, TypeVar
 
 from instructor import Instructor
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
 
 
 class BaseProvider(ABC):
@@ -9,13 +17,13 @@ class BaseProvider(ABC):
     NAME: str
     DEFAULT_MODEL: str
 
-    @property
+    @cached_property
     @abstractmethod
-    def client(self):
+    def client(self) -> Any:
         """The instructor client for the provider."""
         raise NotImplementedError
 
-    @property
+    @cached_property
     @abstractmethod
     def structured_client(self) -> Instructor:
         """The structured client for the provider."""
@@ -27,7 +35,7 @@ class BaseProvider(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def structured_response(self, prompt: str, response_model, **kwargs):
+    def structured_response(self, prompt: str, response_model: Type[T], **kwargs) -> T:
         """Get a structured response."""
         raise NotImplementedError
 

simplemind/providers/anthropic.py

@@ -1,36 +1,54 @@
-from typing import Union
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
 
-import anthropic
 import instructor
+from pydantic import BaseModel
 
-from ._base import BaseProvider
+from ..logging import logger
 from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
+
 
 PROVIDER_NAME = "anthropic"
 DEFAULT_MODEL = "claude-3-5-sonnet-20241022"
-DEFAULT_MAX_TOKENS = 1000
+DEFAULT_MAX_TOKENS = 1_000
+DEFAULT_KWARGS = {"max_tokens": DEFAULT_MAX_TOKENS}
 
 
 class Anthropic(BaseProvider):
     NAME = PROVIDER_NAME
     DEFAULT_MODEL = DEFAULT_MODEL
+    DEFAULT_KWARGS = DEFAULT_KWARGS
 
-    def __init__(self, api_key: Union[str, None] = None):
+    def __init__(self, api_key: str | None = None):
         self.api_key = api_key or settings.get_api_key(PROVIDER_NAME)
 
-    @property
+    @cached_property
     def client(self):
         """The raw Anthropic client."""
         if not self.api_key:
             raise ValueError("Anthropic API key is required")
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `anthropic` package: `pip install anthropic`"
+            ) from exc
+
         return anthropic.Anthropic(api_key=self.api_key)
 
-    @property
+    @cached_property
     def structured_client(self):
         """A client patched with Instructor."""
         return instructor.from_anthropic(self.client)
 
-    def send_conversation(self, conversation: "Conversation", **kwargs):
+    @logger
+    def send_conversation(self, conversation: "Conversation", **kwargs) -> "Message":
         """Send a conversation to the Anthropic API."""
         from ..models import Message
 
@@ -39,10 +57,9 @@ class Anthropic(BaseProvider):
         ]
 
         response = self.client.messages.create(
-            model=conversation.llm_model or DEFAULT_MODEL,
+            model=conversation.llm_model or self.DEFAULT_MODEL,
             messages=messages,
-            max_tokens=DEFAULT_MAX_TOKENS,
-            **kwargs,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
         # Get the response content from the Anthropic response
@@ -53,26 +70,40 @@ class Anthropic(BaseProvider):
             role="assistant",
             text=assistant_message,
             raw=response,
-            llm_model=conversation.llm_model or DEFAULT_MODEL,
+            llm_model=conversation.llm_model or self.DEFAULT_MODEL,
             llm_provider=PROVIDER_NAME,
         )
 
-    def structured_response(self, model, response_model, **kwargs):
-        response = self.structured_client.messages.create(
-            model=model, response_model=response_model, **kwargs
-        )
-        return response
+    @logger
+    def structured_response(
+        self, response_model: Type[T], *, llm_model: str | None = None, **kwargs
+    ) -> T:
+        model = llm_model or self.DEFAULT_MODEL
 
-    def generate_text(self, prompt, *, llm_model, **kwargs):
+        # Extract the prompt from kwargs if it exists
+        prompt = kwargs.pop("prompt", kwargs.pop("messages", ""))
+
+        # Format the messages properly
+        messages = [{"role": "user", "content": prompt}]
+
+        response = self.structured_client.messages.create(
+            model=model,
+            messages=messages,  # Add the messages parameter
+            response_model=response_model,
+            **{**self.DEFAULT_KWARGS, **kwargs},
+        )
+        return response_model.model_validate(response)
+
+    @logger
+    def generate_text(self, prompt: str, *, llm_model: str, **kwargs):
         messages = [
             {"role": "user", "content": prompt},
         ]
 
         response = self.client.messages.create(
-            model=llm_model,
+            model=llm_model or self.DEFAULT_MODEL,
             messages=messages,
-            max_tokens=DEFAULT_MAX_TOKENS,
-            **kwargs,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
         return response.content[0].text

simplemind/providers/gemini.py

@@ -0,0 +1,109 @@
+# TODO: this is a placeholder file for the Gemini provider
+# IT is not currently working as desired.
+
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
+
+import instructor
+from pydantic import BaseModel
+
+from ..logging import logger
+from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
+
+
+PROVIDER_NAME = "gemini"
+DEFAULT_MODEL = "models/gemini-1.5-flash-latest"
+
+
+class Gemini(BaseProvider):
+    NAME = PROVIDER_NAME
+    DEFAULT_MODEL = DEFAULT_MODEL
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or settings.get_api_key(PROVIDER_NAME)
+        self.model_name = DEFAULT_MODEL
+
+    def set_model(self, model_name: str):
+        self.model_name = model_name
+
+    @cached_property
+    def client(self):
+        """The raw Gemini client."""
+        if not self.api_key:
+            raise ValueError("Gemini API key is required")
+        try:
+            import google.generativeai as genai
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `google-generativeai` package: `pip install google-generativeai`"
+            ) from exc
+        genai.configure(api_key=self.api_key)
+        return genai.GenerativeModel(model_name=self.model_name)
+
+    @cached_property
+    def structured_client(self):
+        """A Gemini client patched with Instructor."""
+        return instructor.from_gemini(self.client)
+
+    @logger
+    def send_conversation(self, conversation: "Conversation") -> "Message":
+        """Send a conversation to the Gemini API."""
+        from ..models import Message
+
+        # Convert messages to Gemini's format
+        chat = self.client.start_chat()
+
+        # Send all previous messages to establish context
+        for msg in conversation.messages[:-1]:  # All messages except the last one
+            chat.send_message(msg.text)
+
+        # Send the final message and get response
+        try:
+            response = chat.send_message(conversation.messages[-1].text)
+        except Exception as e:
+            raise RuntimeError(f"Failed to send conversation to Gemini API: {e}") from e
+
+        # Create and return a properly formatted Message instance
+        return Message(
+            role="assistant",
+            text=response.text,
+            raw=response,
+            llm_model=self.model_name,
+            llm_provider=PROVIDER_NAME,
+        )
+
+    @logger
+    def structured_response(self, prompt: str, response_model: Type[T], **kwargs) -> T:
+        """Send a structured response to the Gemini API."""
+        # Only try to pop if the key exists
+        kwargs.pop("llm_model", None)  # Add default value of None
+
+        try:
+            response = self.structured_client.chat.completions.create(
+                messages=[{"role": "user", "content": prompt}],
+                response_model=response_model,
+                **kwargs,
+            )
+        except Exception as e:
+            # Handle the exception appropriately, e.g., log the error or raise a custom exception
+            raise RuntimeError(
+                f"Failed to send structured response to Gemini API: {e}"
+            ) from e
+        return response_model.model_validate(response)
+
+    @logger
+    def generate_text(self, prompt: str, **kwargs) -> str:
+        """Generate text using the Gemini API."""
+        kwargs.pop("llm_model")
+        try:
+            response = self.client.generate_content(prompt, **kwargs)
+        except Exception as e:
+            # Handle the exception appropriately, e.g., log the error or raise a custom exception
+            raise RuntimeError(f"Failed to generate text with Gemini API: {e}") from e
+        return response.text

simplemind/providers/groq.py

@@ -1,34 +1,52 @@
-from typing import Union
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
 
-import groq
 import instructor
+from pydantic import BaseModel
 
-from ._base import BaseProvider
+from ..logging import logger
 from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
+
 
 PROVIDER_NAME = "groq"
 DEFAULT_MODEL = "llama3-8b-8192"
+DEFAULT_MAX_TOKENS = 1_000
+DEFAULT_KWARGS = {"max_tokens": DEFAULT_MAX_TOKENS}
 
 
 class Groq(BaseProvider):
     NAME = PROVIDER_NAME
     DEFAULT_MODEL = DEFAULT_MODEL
+    DEFAULT_KWARGS = DEFAULT_KWARGS
 
-    def __init__(self, api_key: Union[str, None] = None):
+    def __init__(self, api_key: str | None = None):
         self.api_key = api_key or settings.get_api_key(PROVIDER_NAME)
 
-    @property
+    @cached_property
     def client(self):
         """The raw Groq client."""
         if not self.api_key:
             raise ValueError("Groq API key is required")
+        try:
+            import groq
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `groq` package: `pip install groq`"
+            ) from exc
         return groq.Groq(api_key=self.api_key)
 
-    @property
+    @cached_property
     def structured_client(self):
         """A client patched with Instructor."""
         return instructor.from_groq(self.client)
 
+    @logger
     def send_conversation(
         self,
         conversation: "Conversation",
@@ -42,9 +60,9 @@ class Groq(BaseProvider):
         ]
 
         response = self.client.chat.completions.create(
-            model=conversation.llm_model or DEFAULT_MODEL,
+            model=conversation.llm_model or self.DEFAULT_MODEL,
             messages=messages,
-            **kwargs,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
         # Get the response content from the Groq response
@@ -55,11 +73,12 @@ class Groq(BaseProvider):
             role="assistant",
             text=assistant_message.content or "",
             raw=response,
-            llm_model=conversation.llm_model or DEFAULT_MODEL,
+            llm_model=conversation.llm_model or self.DEFAULT_MODEL,
             llm_provider=PROVIDER_NAME,
         )
 
-    def structured_response(self, prompt: str, response_model, **kwargs):
+    @logger
+    def structured_response(self, prompt: str, response_model: Type[T], **kwargs) -> T:
         # Ensure messages are provided in kwargs
         messages = [
             {"role": "user", "content": prompt},
@@ -68,25 +87,27 @@ class Groq(BaseProvider):
         response = self.structured_client.chat.completions.create(
             messages=messages,
             response_model=response_model,
-            **kwargs,
+            model=kwargs.pop("llm_model", self.DEFAULT_MODEL),
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
-        return response
+        return response_model.model_validate(response)
 
+    @logger
     def generate_text(
         self,
         prompt: str,
         *,
         llm_model: str,
         **kwargs,
-    ):
+    ) -> str:
         messages = [
             {"role": "user", "content": prompt},
         ]
 
-        response = self.structured_client.chat.completions.create(
+        response = self.client.chat.completions.create(
             messages=messages,
-            model=llm_model,
-            **kwargs,
+            model=llm_model or self.DEFAULT_MODEL,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
-        return response.choices[0].message.content
+        return str(response.choices[0].message.content)

simplemind/providers/ollama.py

@@ -0,0 +1,118 @@
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
+
+import instructor
+from openai import OpenAI
+from pydantic import BaseModel
+
+from ..logging import logger
+from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
+
+
+PROVIDER_NAME = "ollama"
+DEFAULT_MODEL = "llama3.2"
+DEFAULT_TIMEOUT = 60
+DEFAULT_KWARGS = {}
+
+
+class Ollama(BaseProvider):
+    NAME = PROVIDER_NAME
+    DEFAULT_MODEL = DEFAULT_MODEL
+    DEFAULT_KWARGS = DEFAULT_KWARGS
+    TIMEOUT = DEFAULT_TIMEOUT
+
+    def __init__(self, host_url: str | None = None):
+        self.host_url = host_url or settings.OLLAMA_HOST_URL
+
+    @cached_property
+    def client(self):
+        """The raw Ollama client."""
+        if not self.host_url:
+            raise ValueError("No ollama host url provided")
+        try:
+            import ollama as ol
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `ollama` package: `pip install ollama`"
+            ) from exc
+        return ol.Client(timeout=self.TIMEOUT, host=self.host_url)
+
+    @cached_property
+    def structured_client(self) -> instructor.Instructor:
+        """A client patched with Instructor."""
+        return instructor.from_openai(
+            OpenAI(
+                base_url=f"{self.host_url}/v1",
+                api_key="ollama",
+            ),
+            mode=instructor.Mode.JSON,
+        )
+
+    @logger
+    def send_conversation(self, conversation: "Conversation", **kwargs) -> "Message":
+        """Send a conversation to the Ollama API."""
+        from ..models import Message
+
+        messages = [
+            {"role": msg.role, "content": msg.text} for msg in conversation.messages
+        ]
+        response = self.client.chat(
+            model=conversation.llm_model or DEFAULT_MODEL,
+            messages=messages,
+            **{**self.DEFAULT_KWARGS, **kwargs},
+        )
+        assistant_message = response.get("message")
+
+        # Create and return a properly formatted Message instance
+        return Message(
+            role="assistant",
+            text=assistant_message.get("content"),
+            raw=response,
+            llm_model=conversation.llm_model or self.DEFAULT_MODEL,
+            llm_provider=PROVIDER_NAME,
+        )
+
+    @logger
+    def structured_response(
+        self,
+        prompt: str,
+        response_model: Type[T],
+        *,
+        llm_model: str | None = None,
+        **kwargs,
+    ) -> T:
+        """Get a structured response from the Ollama API."""
+        messages = [
+            {"role": "user", "content": prompt},
+        ]
+
+        response = self.structured_client.chat.completions.create(
+            messages=messages,
+            model=llm_model or self.DEFAULT_MODEL,
+            response_model=response_model,
+            **{**self.DEFAULT_KWARGS, **kwargs},
+        )
+        return response_model.model_validate(response)
+
+    @logger
+    def generate_text(
+        self, prompt: str, *, llm_model: str | None = None, **kwargs
+    ) -> str:
+        """Generate text using the Ollama API."""
+        messages = [
+            {"role": "user", "content": prompt},
+        ]
+
+        response = self.client.chat(
+            messages=messages,
+            model=llm_model or self.DEFAULT_MODEL,
+            **{**self.DEFAULT_KWARGS, **kwargs},
+        )
+
+        return response.get("message", {}).get("content", "")

simplemind/providers/openai.py

@@ -1,35 +1,52 @@
-from typing import Union
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
 
 import instructor
-import openai as oa
+from pydantic import BaseModel
 
-from ._base import BaseProvider
+from ..logging import logger
 from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
 
 PROVIDER_NAME = "openai"
 DEFAULT_MODEL = "gpt-4o-mini"
+DEFAULT_MAX_TOKENS = 1_000
+DEFAULT_KWARGS = {"max_tokens": DEFAULT_MAX_TOKENS}
 
 
 class OpenAI(BaseProvider):
     NAME = PROVIDER_NAME
     DEFAULT_MODEL = DEFAULT_MODEL
+    DEFAULT_KWARGS = DEFAULT_KWARGS
 
-    def __init__(self, api_key: Union[str, None] = None):
+    def __init__(self, api_key: str | None = None):
         self.api_key = api_key or settings.get_api_key(PROVIDER_NAME)
 
-    @property
+    @cached_property
     def client(self):
         """The raw OpenAI client."""
         if not self.api_key:
             raise ValueError("OpenAI API key is required")
+        try:
+            import openai as oa
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `openai` package: `pip install openai`"
+            ) from exc
         return oa.OpenAI(api_key=self.api_key)
 
-    @property
+    @cached_property
     def structured_client(self):
         """A OpenAI client with Instructor."""
         return instructor.from_openai(self.client)
 
-    def send_conversation(self, conversation: "Conversation", **kwargs):
+    @logger
+    def send_conversation(self, conversation: "Conversation", **kwargs) -> "Message":
         """Send a conversation to the OpenAI API."""
         from ..models import Message
 
@@ -38,7 +55,9 @@ class OpenAI(BaseProvider):
         ]
 
         response = self.client.chat.completions.create(
-            model=conversation.llm_model or DEFAULT_MODEL, messages=messages, **kwargs
+            model=conversation.llm_model or DEFAULT_MODEL,
+            messages=messages,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
         # Get the response content from the OpenAI response
@@ -53,24 +72,37 @@ class OpenAI(BaseProvider):
             llm_provider=PROVIDER_NAME,
         )
 
-    def structured_response(self, prompt, response_model, *, llm_model: str, **kwargs):
+    @logger
+    def structured_response(
+        self,
+        prompt: str,
+        response_model: Type[T],
+        *,
+        llm_model: str | None = None,
+        **kwargs,
+    ) -> T:
+        """Get a structured response from the OpenAI API."""
         # Ensure messages are provided in kwargs
         messages = [
             {"role": "user", "content": prompt},
         ]
-
         response = self.structured_client.chat.completions.create(
-            messages=messages, model=llm_model, response_model=response_model, **kwargs
+            messages=messages,
+            model=llm_model or self.DEFAULT_MODEL,
+            response_model=response_model,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
-        return response
+        return response_model.model_validate(response)
 
-    def generate_text(self, prompt, *, llm_model, **kwargs):
+    @logger
+    def generate_text(self, prompt: str, *, llm_model: str | None = None, **kwargs):
+        """Generate text using the OpenAI API."""
         messages = [
             {"role": "user", "content": prompt},
         ]
-
         response = self.client.chat.completions.create(
-            messages=messages, model=llm_model, **kwargs
+            messages=messages,
+            model=llm_model or self.DEFAULT_MODEL,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
-
         return response.choices[0].message.content

simplemind/providers/xai.py

@@ -1,40 +1,57 @@
-from typing import Union
+from functools import cached_property
+from typing import TYPE_CHECKING, Type, TypeVar
 
 import instructor
-import openai as oa
+from pydantic import BaseModel
 
-from ._base import BaseProvider
+from ..logging import logger
 from ..settings import settings
+from ._base import BaseProvider
+
+if TYPE_CHECKING:
+    from ..models import Conversation, Message
+
+T = TypeVar("T", bound=BaseModel)
+
 
 PROVIDER_NAME = "xai"
 DEFAULT_MODEL = "grok-beta"
 BASE_URL = "https://api.x.ai/v1"
 DEFAULT_MAX_TOKENS = 1000
+DEFAULT_KWARGS = {"max_tokens": DEFAULT_MAX_TOKENS}
 
 
 class XAI(BaseProvider):
     NAME = PROVIDER_NAME
     DEFAULT_MODEL = DEFAULT_MODEL
+    DEFAULT_KWARGS = DEFAULT_KWARGS
 
-    def __init__(self, api_key: Union[str, None] = None):
+    def __init__(self, api_key: str | None = None):
         self.api_key = api_key or settings.get_api_key(PROVIDER_NAME)
 
-    @property
+    @cached_property
     def client(self):
         """The raw OpenAI client."""
         if not self.api_key:
             raise ValueError("XAI API key is required")
+        try:
+            import openai as oa
+        except ImportError as exc:
+            raise ImportError(
+                "Please install the `openai` package: `pip install openai`"
+            ) from exc
         return oa.OpenAI(
             api_key=self.api_key,
             base_url=BASE_URL,
         )
 
-    @property
+    @cached_property
     def structured_client(self):
         """A client patched with Instructor."""
         return instructor.from_openai(self.client)
 
-    def send_conversation(self, conversation: "Conversation", **kwargs):
+    @logger
+    def send_conversation(self, conversation: "Conversation", **kwargs) -> "Message":
         """Send a conversation to the OpenAI API."""
         from ..models import Message
 
@@ -43,9 +60,9 @@ class XAI(BaseProvider):
         ]
 
         response = self.client.chat.completions.create(
-            model=conversation.llm_model or DEFAULT_MODEL,
+            model=conversation.llm_model or self.DEFAULT_MODEL,
             messages=messages,
-            **kwargs,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
         # Get the response content from the OpenAI response
@@ -56,22 +73,26 @@ class XAI(BaseProvider):
             role="assistant",
             text=assistant_message.content,
             raw=response,
-            llm_model=conversation.llm_model or DEFAULT_MODEL,
+            llm_model=conversation.llm_model or self.DEFAULT_MODEL,
             llm_provider=PROVIDER_NAME,
         )
 
-    def structured_response(self, prompt: str, response_model, *, llm_model):
+    @logger
+    def structured_response(
+        self, prompt: str, response_model: Type[T], *, llm_model: str
+    ) -> T:
         raise NotImplementedError("XAI does not support structured responses")
 
-    def generate_text(self, prompt, *, llm_model, **kwargs):
+    @logger
+    def generate_text(self, prompt: str, *, llm_model: str, **kwargs) -> str:
         messages = [
             {"role": "user", "content": prompt},
         ]
 
         response = self.client.chat.completions.create(
             messages=messages,
-            model=llm_model,
-            **kwargs,
+            model=llm_model or self.DEFAULT_MODEL,
+            **{**self.DEFAULT_KWARGS, **kwargs},
         )
 
-        return response.choices[0].message.content
+        return str(response.choices[0].message.content)

simplemind/settings.py

@@ -4,6 +4,40 @@ from pydantic import Field, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
+class LoggingConfig(BaseSettings):
+    """The class that holds all the logging settings for the application."""
+
+    enabled: bool = Field(False, description="Enable logging")
+
+    model_config = SettingsConfigDict(extra="forbid")
+
+    def enable_logfire(self, **kwargs) -> None:
+        """Enable logging for the application."""
+        # adding imports here to avoid forced dependencies
+        try:
+            import logfire
+            from logging import basicConfig
+        except ImportError as e:
+            raise ImportError(
+                "To enable logging, please install logfire: `pip install logfire`"
+            ) from e
+
+        self.enabled = True
+        logfire.configure(**kwargs)
+        basicConfig(handlers=[logfire.LogfireLoggingHandler()])
+
+        try:
+            logfire.configure(**kwargs)
+            basicConfig(handlers=[logfire.LogfireLoggingHandler()])
+        except Exception as e:
+            self.enabled = False  # Reset flag on failure
+            raise RuntimeError("Failed to configure logging") from e
+
+    def disable_logfire(self) -> None:
+        """Disable logging for the application."""
+        self.enabled = False
+
+
 class Settings(BaseSettings):
     """The class that holds all the API keys for the application."""
 
@@ -11,13 +45,18 @@ class Settings(BaseSettings):
         None, description="API key for Anthropic"
     )
     GROQ_API_KEY: Optional[SecretStr] = Field(None, description="API key for Groq")
+    GEMINI_API_KEY: Optional[SecretStr] = Field(None, description="API key for Gemini")
     OPENAI_API_KEY: Optional[SecretStr] = Field(None, description="API key for OpenAI")
+    OLLAMA_HOST_URL: Optional[str] = Field(
+        "http://127.0.0.1:11434", description="Fully qualified host URL for Ollama"
+    )
     XAI_API_KEY: Optional[SecretStr] = Field(None, description="API key for xAI")
     DEFAULT_LLM_PROVIDER: str = Field("openai", description="The default LLM provider")
 
     model_config = SettingsConfigDict(
         env_file=".env", env_file_encoding="utf-8", case_sensitive=True, extra="ignore"
     )
+    logging: LoggingConfig = LoggingConfig()
 
     @field_validator("*", mode="before")
     @classmethod

simplemind/utils.py

@@ -1,13 +1,38 @@
-from typing import Union
+import difflib
 
-from .providers import providers
+from .providers import BaseProvider, providers
+
+_PROVIDER_NAMES = [provider.NAME.lower() for provider in providers]
 
 
-def find_provider(provider_name: Union[str, None]):
-    """Find a provider by name."""
-    if provider_name:
-        for provider_class in providers:
-            if provider_class.NAME.lower() == provider_name.lower():
-                # Instantiate the provider
-                return provider_class()
-    raise ValueError(f"Provider {provider_name} not found")
+def find_provider(provider_name: str | None) -> BaseProvider:
+    """
+    Find and instantiate a provider by name.
+
+    Parameters:
+        provider_name (Union[str, None]): The name of the provider to find.
+
+    Returns:
+        An instance of the provider class if found.
+
+    Raises:
+        ValueError: If the provider is not specified or is not found, with a suggestion for the closest match.
+    """
+    if provider_name is None:
+        raise ValueError("No provider specified.")
+
+    # Find the provider by name.
+    for provider_class in providers:
+        if provider_class.NAME.lower() == provider_name.lower():
+            # Instantiate the provider
+            return provider_class()
+
+    # Find the closest match
+    provider_found = difflib.get_close_matches(
+        provider_name.lower(), _PROVIDER_NAMES, n=1
+    )
+    if provider_found:
+        raise ValueError(
+            f"Provider {provider_name!r} not found. Did you mean {provider_found[0]!r}?"
+        )
+    raise ValueError(f"Provider {provider_name} not found.")

tests/conftest.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+# Add the project root to the Python path.
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from simplemind import Session
+
+
+@pytest.fixture
+def sm():
+    """Fixture that provides a simplemind Session instance with default settings."""
+    return Session()

tests/test_basics.py

@@ -0,0 +1,2 @@
+def test_basic_math():
+    assert 1 + 1 == 2

tests/test_generate_data.py

@@ -0,0 +1,28 @@
+from pydantic import BaseModel
+
+import pytest
+from simplemind.providers import Anthropic, Gemini, Groq, Ollama, OpenAI
+
+
+class ResponseModel(BaseModel):
+    result: int
+
+
+@pytest.mark.parametrize(
+    "provider_cls",
+    [
+        Anthropic,
+        Gemini,
+        OpenAI,
+        Groq,
+        Ollama,
+    ],
+)
+def test_generate_data(provider_cls):
+    provider = provider_cls()
+    prompt = "What is 2+2?"
+
+    data = provider.structured_response(prompt=prompt, response_model=ResponseModel)
+
+    assert isinstance(data, ResponseModel)
+    assert isinstance(data.result, int)

tests/test_generate_text.py

@@ -0,0 +1,22 @@
+import pytest
+from simplemind.providers import Anthropic, Gemini, Groq, Ollama, OpenAI
+
+
+@pytest.mark.parametrize(
+    "provider_cls",
+    [
+        Anthropic,
+        Gemini,
+        OpenAI,
+        Groq,
+        Ollama,
+    ],
+)
+def test_generate_text(provider_cls):
+    provider = provider_cls()
+    prompt = "What is 2+2?"
+
+    response = provider.generate_text(prompt=prompt, llm_model=provider.DEFAULT_MODEL)
+
+    assert isinstance(response, str)
+    assert len(response) > 0