chatlas 0.2.0__tar.gz

chatlas-0.2.0/.github/workflows/check-update-types.yml

@@ -0,0 +1,42 @@
+name: Test - Python
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main", "rc-*"]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  release:
+    types: [published]
+
+env:
+  UV_VERSION: "0.4.x"
+  PYTHON_VERSION: 3.13
+
+jobs:
+  check-types-updated:
+    name: Check provider types
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 🚀 Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
+        run: uv python install ${{ env.PYTHON_VERSION }}
+
+      - name: 📦 Install the project
+        run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras
+
+      - name: Run type update
+        run: make update-types
+
+      # Fail if there are changes under chatlas/types and throw a useful error message
+      - name: Check for changes
+        run: |
+          if [[ -n $(git diff chatlas/types) ]]; then
+            echo "::error::Types are out of date. Please run 'make update-types' and commit the changes."
+            exit 1
+          fi

chatlas-0.2.0/.github/workflows/docs-publish.yml

@@ -0,0 +1,65 @@
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**/*"
+      - .github/workflows/docs-publish.yml
+  workflow_dispatch:
+
+name: Docs - Publish
+
+env:
+  UV_VERSION: "0.4.x"
+  PYTHON_VERSION: 3.12
+
+permissions: 
+    contents: write
+    pages: write
+
+jobs:
+  docs-publish:
+    runs-on: ubuntu-latest
+
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # full history needed for correct versioning of py pkg
+
+    - name: 🔵 Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        version: 1.6.26
+
+    - name: 🚀 Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: ${{ env.UV_VERSION }}
+
+    - name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
+      run: uv python install ${{ env.PYTHON_VERSION }}
+
+    - name: 📦 Install chatlas and dependencies
+      run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras
+
+    - name: 🔌 Activate venv
+      run: |
+        source .venv/bin/activate
+        echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+        echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+    - name: Run quartodoc
+      run: make quartodoc
+
+    - name: 🚢 Publish to GitHub Pages (and render)
+      uses: quarto-dev/quarto-actions/publish@v2
+      with:
+        target: gh-pages
+        path: docs
+      env:
+        GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

chatlas-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Python - Release
+
+on:
+  release:
+    types: [published]
+
+env:
+  UV_VERSION: "0.4.x"
+  PYTHON_VERSION: 3.13
+
+jobs:
+  pypi-release:
+    name: Build and release Python package
+    runs-on: ubuntu-latest
+
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/chatlas/
+
+    permissions:  # for trusted publishing
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 🚀 Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
+        run: uv python install ${{ env.PYTHON_VERSION }}
+
+      - name: 📦 Install the project
+        run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras
+
+      # Tests require API keys, and can be flaky at times due to quota limits, 
+      # we skip them for release
+      #- name: 🧪 Check tests
+      #  run: make check-tests
+
+      - name: 📝 Check types
+        run: make check-types
+
+      - name: 📐 Check formatting
+        run: make check-format
+
+      - name: 🧳 Build package
+        run: uv build
+
+      - name: 🚢 Publish release on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

chatlas-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: Test - Python
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main", "rc-*"]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        config:
+          - { python-version: "3.9", test_google: false, test_azure: false }
+          - { python-version: "3.10", test_google: false, test_azure: false }
+          - { python-version: "3.11", test_google: false, test_azure: false }
+          - { python-version: "3.12", test_google: true, test_azure: true }
+          - { python-version: "3.13", test_google: false, test_azure: false }
+
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+      AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
+      # Free tier of Google is rate limited, so we only test on 3.12
+      TEST_GOOGLE: ${{ matrix.config.test_google }}
+      # Free tier of Azure is rate limited, so we only test on 3.12
+      TEST_AZURE: ${{ matrix.config.test_azure }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 🚀 Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: 🐍 Set up Python ${{ matrix.config.python-version }}
+        run: uv python install ${{matrix.config.python-version }}
+
+      - name: 📦 Install the project
+        run: uv sync --python ${{ matrix.config.python-version }} --all-extras
+
+      - name: 🧪 Check tests
+        run: make check-tests
+
+      - name: 📝 Check types
+        run: make check-types
+
+      - name: 📐 Check formatting
+        run: make check-format

chatlas-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__
+
+.ipynb_checkpoints/
+Untitled*.ipynb
+
+.venv
+uv.lock
+
+sandbox/
+
+/.luarc.json
+
+# Automatically generated by docs/index.py
+docs/index.qmd

chatlas-0.2.0/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff"
+    ]
+}

chatlas-0.2.0/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff",
+    },
+    "flake8.args": ["--max-line-length=120"]
+}

chatlas-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+<!--
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+-->
+
+## [0.2.0] - 2024-12-11
+
+First stable release of `chatlas`, see the website to learn more <https://posit-dev.github.io/chatlas/> 

chatlas-0.2.0/Makefile

@@ -0,0 +1,89 @@
+.PHONY: setup
+setup:  ## [py] Setup python environment
+	uv sync --all-extras
+
+.PHONY: build
+build:   ## [py] Build python package
+	@echo "🧳 Building python package"
+	@[ -d dist ] && rm -r dist || true
+	uv build
+
+.PHONY: check
+check:  check-tests check-format check-types ## [py] Run python checks
+
+.PHONY: check-tests
+check-tests:  ## [py] Run python tests
+	@echo ""
+	@echo "🧪 Running tests with pytest"
+	uv run pytest
+
+.PHONY: check-types
+check-types:  ## [py] Run python type checks
+	@echo ""
+	@echo "📝 Checking types with pyright"
+	uv run pyright
+
+.PHONY: check-format
+check-format:
+	@echo ""
+	@echo "📐 Checking format with ruff"
+	uv run ruff check chatlas --config pyproject.toml
+
+.PHONY: format
+format: ## [py] Format python code
+	uv run ruff check --fix chatlas --config pyproject.toml
+	uv run ruff format chatlas --config pyproject.toml
+
+.PHONY: check-tox
+check-tox:  ## [py] Run python 3.9 - 3.12 checks with tox
+	@echo ""
+	@echo "🔄 Running tests and type checking with tox for Python 3.9--3.12"
+	uv run tox run-parallel
+
+.PHONY: docs
+docs: quartodoc
+	quarto render docs
+
+.PHONY: docs-preview
+docs-preview: quartodoc
+	quarto preview docs
+
+.PHONY: quartodoc
+quartodoc: 
+	@echo "📖 Generating python docs with quartodoc"
+	@$(eval export IN_QUARTODOC=true)
+	cd docs && uv run quartodoc build
+	cd docs && uv run quartodoc interlinks
+
+.PHONY: quartodoc-watch
+quartodoc-watch:
+	@echo "📖 Generating python docs with quartodoc"
+	@$(eval export IN_QUARTODOC=true)
+	uv run quartodoc build --config docs/_quarto.yml --watch
+
+.PHONY: update-snaps
+update-snaps:
+	@echo "📸 Updating pytest snapshots"
+	uv run pytest --snapshot-update
+
+.PHONY: update-types
+update-types:
+	@echo "📝 Updating chat provider types"
+	uv run python scripts/main.py
+
+.PHONY: help
+help:  ## Show help messages for make targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; { \
+		printf "\033[32m%-18s\033[0m", $$1; \
+		if ($$2 ~ /^\[docs\]/) { \
+			printf "\033[34m[docs]\033[0m%s\n", substr($$2, 7); \
+		} else if ($$2 ~ /^\[py\]/) { \
+			printf "  \033[33m[py]\033[0m%s\n", substr($$2, 5); \
+		} else if ($$2 ~ /^\[r\]/) { \
+			printf "   \033[31m[r]\033[0m%s\n", substr($$2, 4); \
+		} else { \
+			printf "       %s\n", $$2; \
+		} \
+	}'
+
+.DEFAULT_GOAL := help

chatlas-0.2.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.3
+Name: chatlas
+Version: 0.2.0
+Summary: A simple and consistent interface for chatting with LLMs
+Project-URL: Homepage, https://posit-dev.github.io/chatlas
+Project-URL: Documentation, https://posit-dev.github.io/chatlas
+Project-URL: Repository, https://github.com/posit-dev/chatlas
+Project-URL: Issues, https://github.com/posit-dev/chatlas/issues/
+Project-URL: Changelog, https://github.com/posit-dev/chatlas/blob/main/CHANGELOG.md
+Author-email: Carson Sievert <carson@posit.co>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: jinja2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: anthropic[bedrock]; extra == 'dev'
+Requires-Dist: google-generativeai>=0.8.3; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: numpy>1.24.4; extra == 'dev'
+Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: python-dotenv; extra == 'dev'
+Requires-Dist: ruff>=0.6.5; extra == 'dev'
+Requires-Dist: shiny; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: griffe>=1; extra == 'docs'
+Requires-Dist: ipykernel; extra == 'docs'
+Requires-Dist: ipywidgets; extra == 'docs'
+Requires-Dist: nbclient; extra == 'docs'
+Requires-Dist: nbformat; extra == 'docs'
+Requires-Dist: pandas; extra == 'docs'
+Requires-Dist: pyyaml; extra == 'docs'
+Requires-Dist: quartodoc>=0.7; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pyright>=1.1.379; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest>=8.3.2; extra == 'test'
+Requires-Dist: syrupy>=4; extra == 'test'
+Description-Content-Type: text/markdown
+
+# chatlas
+
+chatlas provides a simple and unified interface across large language model (llm) providers in Python. 
+It abstracts away complexity from common tasks like streaming chat interfaces, tool calling, structured output, and much more.
+chatlas helps you prototype faster without painting you into a corner; for example, switching providers is as easy as changing one line of code, but provider specific features are still accessible when needed.
+Developer experience is also a key focus of chatlas: typing support, rich console output, and built-in tooling are all included.
+
+(Looking for something similar to chatlas, but in R? Check out [elmer](https://elmer.tidyverse.org/)!)
+
+## Install
+
+Install the latest stable release from PyPI:
+
+```bash
+pip install -U chatlas
+```
+
+Or, install the latest development version from GitHub:
+
+```bash
+pip install -U git+https://github.com/posit-dev/chatlas
+```
+
+## Model providers
+
+`chatlas` supports a variety of model providers. See the [API reference](https://posit-dev.github.io/chatlas/reference/index.html) for more details (like managing credentials) on each provider.
+
+* Anthropic (Claude): [`ChatAnthropic()`](https://posit-dev.github.io/chatlas/reference/ChatAnthropic.html).
+* GitHub model marketplace: [`ChatGithub()`](https://posit-dev.github.io/chatlas/reference/ChatGithub.html).
+* Google (Gemini): [`ChatGoogle()`](https://posit-dev.github.io/chatlas/reference/ChatGoogle.html).
+* Groq: [`ChatGroq()`](https://posit-dev.github.io/chatlas/reference/ChatGroq.html).
+* Ollama local models: [`ChatOllama()`](https://posit-dev.github.io/chatlas/reference/ChatOllama.html).
+* OpenAI: [`ChatOpenAI()`](https://posit-dev.github.io/chatlas/reference/ChatOpenAI.html).
+* perplexity.ai: [`ChatPerplexity()`](https://posit-dev.github.io/chatlas/reference/ChatPerplexity.html).
+
+It also supports the following enterprise cloud providers:
+
+* AWS Bedrock: [`ChatBedrockAnthropic()`](https://posit-dev.github.io/chatlas/reference/ChatBedrockAnthropic.html).
+* Azure OpenAI: [`ChatAzureOpenAI()`](https://posit-dev.github.io/chatlas/reference/ChatAzureOpenAI.html).
+
+To use a model provider that isn't listed here, you have two options:
+
+1. If the model is OpenAI compatible, use `ChatOpenAI()` with the appropriate `base_url` and `api_key` (see [`ChatGithub`](https://github.com/posit-dev/chatlas/blob/main/chatlas/_github.py) for a reference).
+2. If you're motivated, implement a new provider by subclassing [`Provider`](https://github.com/posit-dev/chatlas/blob/main/chatlas/_provider.py) and implementing the required methods.
+
+
+## Model choice
+
+If you're using chatlas inside your organisation, you'll be limited to what your org allows, which is likely to be one provided by a big cloud provider (e.g. `ChatAzureOpenAI()` and `ChatBedrockAnthropic()`). If you're using chatlas for your own personal exploration, you have a lot more freedom so we have a few recommendations to help you get started:
+
+- `ChatOpenAI()` or `ChatAnthropic()` are both good places to start. `ChatOpenAI()` defaults to **GPT-4o**, but you can use `model = "gpt-4o-mini"` for a cheaper lower-quality model, or `model = "o1-mini"` for more complex reasoning.  `ChatAnthropic()` is similarly good; it defaults to **Claude 3.5 Sonnet** which we have found to be particularly good at writing code.
+
+- `ChatGoogle()` is great for large prompts, because it has a much larger context window than other models. It allows up to 1 million tokens, compared to Claude 3.5 Sonnet's 200k and GPT-4o's 128k.
+
+- `ChatOllama()`, which uses [Ollama](https://ollama.com), allows you to run models on your own computer. The biggest models you can run locally aren't as good as the state of the art hosted models, but they also don't share your data and and are effectively free.
+
+## Using chatlas
+
+You can chat via `chatlas` in several different ways, depending on whether you are working interactively or programmatically. They all start with creating a new chat object:
+
+```python
+from chatlas import ChatOpenAI
+
+chat = ChatOpenAI(
+  model = "gpt-4o",
+  system_prompt = "You are a friendly but terse assistant.",
+)
+```
+
+### Interactive console
+
+From a `chat` instance, it's simple to start a web-based or terminal-based chat console, which is great for testing the capabilities of the model. In either case, responses stream in real-time, and context is preserved across turns.
+
+```python
+chat.app()
+```
+
+<div style="display:flex;justify-content:center;">
+<img width="500" alt="A web app for chatting with an LLM via chatlas" src="https://github.com/user-attachments/assets/e43f60cb-3686-435a-bd11-8215cb024d2e" class="border rounded">
+</div>
+
+
+Or, if you prefer to work from the terminal:
+
+```python
+chat.console()
+```
+
+```
+Entering chat console. Press Ctrl+C to quit.
+
+?> Who created Python?
+
+Python was created by Guido van Rossum. He began development in the late 1980s and released the first version in 1991. 
+
+?> Where did he develop it?
+
+Guido van Rossum developed Python while working at Centrum Wiskunde & Informatica (CWI) in the Netherlands.     
+```
+
+
+### The `.chat()` method
+
+For a more programmatic approach, you can use the `.chat()` method to ask a question and get a response. By default, the response prints to a [rich](https://github.com/Textualize/rich) console as it streams in:
+
+```python
+chat.chat("What preceding languages most influenced Python?")
+```
+
+```
+Python was primarily influenced by ABC, with additional inspiration from C,
+Modula-3, and various other languages.
+```
+
+To ask a question about an image, pass one or more additional input arguments using `content_image_file()` and/or `content_image_url()`:
+
+```python
+from chatlas import content_image_url
+
+chat.chat(
+    content_image_url("https://www.python.org/static/img/python-logo.png"),
+    "Can you explain this logo?"
+)
+```
+
+```
+The Python logo features two intertwined snakes in yellow and blue,
+representing the Python programming language. The design symbolizes...
+```
+
+To get the full response as a string, use the built-in `str()` function. Optionally, you can also suppress the rich console output by setting `echo="none"`:
+
+```python
+response = chat.chat("Who is Posit?", echo="none")
+print(str(response))
+```
+
+As we'll see in later articles, `echo="all"` can also be useful for debugging, as it shows additional information, such as tool calls.
+
+### The `.stream()` method
+
+If you want to do something with the response in real-time (i.e., as it arrives in chunks), use the `.stream()` method. This method returns an iterator that yields each chunk of the response as it arrives:
+
+```python
+response = chat.stream("Who is Posit?")
+for chunk in response:
+    print(chunk, end="")
+```
+
+The `.stream()` method can also be useful if you're [building a chatbot](https://posit-dev.github.io/chatlas/web-apps.html) or other programs that needs to display responses as they arrive.
+
+
+### Tool calling 
+
+Tool calling is as simple as passing a function with type hints and docstring to `.register_tool()`.
+
+```python
+import sys
+
+def get_current_python_version() -> str:
+    """Get the current version of Python."""
+    return sys.version
+
+chat.register_tool(get_current_python_version)
+chat.chat("What's the current version of Python?")
+```
+
+```
+The current version of Python is 3.13.
+```
+
+Learn more in the [tool calling article](https://posit-dev.github.io/chatlas/tool-calling.html)
+
+### Structured data
+
+Structured data (i.e., structured output) is as simple as passing a [pydantic](https://docs.pydantic.dev/latest/) model to `.extract_data()`.
+
+```python
+from pydantic import BaseModel
+
+class Person(BaseModel):
+    name: str
+    age: int
+
+chat.extract_data(
+    "My name is Susan and I'm 13 years old", 
+    data_model=Person,
+)
+```
+
+```
+{'name': 'Susan', 'age': 13}
+```
+
+Learn more in the [structured data article](https://posit-dev.github.io/chatlas/structured-data.html)
+
+### Export chat
+
+Easily get a full markdown or HTML export of a conversation:
+
+```python
+chat.export("index.html", title="Python Q&A")
+```
+
+If the export doesn't have all the information you need, you can also access the full conversation history via the `.get_turns()` method:
+
+```python
+chat.get_turns()
+```
+
+And, if the conversation is too long, you can specify which turns to include:
+
+```python
+chat.export("index.html", turns=chat.get_turns()[-5:])
+```
+
+### Async
+
+`chat` methods tend to be synchronous by default, but you can use the async flavor by appending `_async` to the method name:
+
+```python
+import asyncio
+
+async def main():
+    await chat.chat_async("What is the capital of France?")
+
+asyncio.run(main())
+```
+
+### Typing support
+
+`chatlas` has full typing support, meaning that, among other things, autocompletion just works in your favorite editor:
+
+<div style="display:flex;justify-content:center;">
+<img width="500" alt="Autocompleting model options in ChatOpenAI" src="https://github.com/user-attachments/assets/163d6d8a-7d58-422d-b3af-cc9f2adee759" class="rounded">
+</div>
+
+
+
+### Troubleshooting
+
+Sometimes things like token limits, tool errors, or other issues can cause problems that are hard to diagnose. 
+In these cases, the `echo="all"` option is helpful for getting more information about what's going on under the hood.
+
+```python
+chat.chat("What is the capital of France?", echo="all")
+```
+
+This shows important information like tool call results, finish reasons, and more.
+
+If the problem isn't self-evident, you can also reach into the `.get_last_turn()`, which contains the full response object, with full details about the completion.
+
+
+<div style="display:flex;justify-content:center;">
+  <img width="500" alt="Turn completion details with typing support" src="https://github.com/user-attachments/assets/eaea338d-e44a-4e23-84a7-2e998d8af3ba" class="rounded">
+</div>
+
+
+For monitoring issues in a production (or otherwise non-interactive) environment, you may want to enabling logging. Also, since `chatlas` builds on top of packages like `anthropic` and `openai`, you can also enable their debug logging to get lower-level information, like HTTP requests and response codes.
+
+```shell
+$ export CHATLAS_LOG=info
+$ export OPENAI_LOG=info
+$ export ANTHROPIC_LOG=info
+```
+
+### Next steps
+
+If you're new to world LLMs, you might want to read the [Get Started](https://posit-dev.github.io/chatlas/get-started.html) guide, which covers some basic concepts and terminology.
+
+Once you're comfortable with the basics, you can explore more in-depth topics like [prompt design](https://posit-dev.github.io/chatlas/prompt-design.html) or the [API reference](https://posit-dev.github.io/chatlas/reference/index.html).