⬆️v0.2 - new features + docs

.github/workflows/code-check.yml

@@ -6,21 +6,21 @@ jobs:
   pre-commit:
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ["3.10", "3.11"]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: eifinger/setup-rye@v1
-      with:
-        enable-cache: true
-        cache-prefix: 'venv-funcchain'
-    - name: pin version
-      run: rye pin ${{ matrix.python-version }}
-    - name: Sync rye
-      run: rye sync
-    - name: Run pre-commit
-      run: rye run pre-commit run --all-files
-    - name: Run tests
-      env:
-        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-      run: rye run pytest -m "not skip_on_actions"
+      - uses: actions/checkout@v2
+      - uses: eifinger/setup-rye@v1
+        with:
+          enable-cache: true
+          cache-prefix: "venv-funcchain"
+      - name: pin version
+        run: rye pin ${{ matrix.python-version }}
+      - name: Sync rye
+        run: rye sync
+      - name: Run pre-commit
+        run: rye run pre-commit run --all-files
+      - name: Run tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: rye run pytest -m "not skip_on_actions"

.gitignore

@@ -165,3 +165,4 @@ cython_debug/
 
 vscext
 .models
+.python-version

.pre-commit-config.yaml

@@ -1,23 +1,14 @@
 repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.5.0
+      hooks:
+          - id: end-of-file-fixer
+          - id: trailing-whitespace
 
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
-    hooks:
-    -   id: check-yaml
-    -   id: end-of-file-fixer
-    -   id: trailing-whitespace
-
--   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.7.1
-    hooks:
-    -   id: mypy
-        args: [--ignore-missing-imports, --follow-imports=skip]
-        additional_dependencies: [types-requests]
-
--   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.7
-    hooks:
-    -   id: ruff
-        args: [ --fix ]
-    -   id: ruff-format
-        types_or: [ python, pyi, jupyter ]
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.1.7
+      hooks:
+          - id: ruff
+            args: [--fix]
+          - id: ruff-format
+            types_or: [python, pyi, jupyter]

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+To contribute, clone the repo and run:
+
+```bash
+./dev_setup.sh
+```
+
+You should not run unstrusted scripts so ask ChatGPT to explain what the contents of this script do!
+
+This will install and setup your development environment using [rye](https://rye-up.com) or pip.

MODELS.md

@@ -2,10 +2,10 @@
 
 ## LangChain Chat Models
 
-You can set the `settings.llm` with any ChatModel the LangChain library.
+You can set the `settings.llm` with any LangChain ChatModel.
 
 ```python
-from langchain.chat_models import AzureChatOpenAI
+from langchain_openai.chat_models import AzureChatOpenAI
 
 settings.llm = AzureChatOpenAI(...)
 ```
@@ -16,23 +16,28 @@ You can also set the `settings.llm` with a string identifier of a ChatModel incl
 
 ### Schema
 
-`<provider>/<name>:<optional_label>`
+`<provider>/<model_name>:<optional_label>`
 
 ### Providers
 
 - `openai`: OpenAI Chat Models
-- `gguf`: Huggingface GGUF Models from TheBloke using LlamaCpp
-- `local` | `thebloke` | `huggingface`: alias for `gguf`
+- `llamacpp`: Run local models directly using llamacpp (alias: `thebloke`, `gguf`)
+- `ollama`: Run local models through Ollama (wrapper for llamacpp)
+- `azure`: Azure Chat Models
+- `anthropic`: Anthropic Chat Models
+- `google`: Google Chat Models
 
 ### Examples
 
-- `openai/gpt-3.5-turbo`: Classic ChatGPT
-- `gguf/deepseek-llm-7b-chat`: DeepSeek LLM 7B Chat
-- `gguf/OpenHermes-2.5-7B`: OpenHermes 2.5
-- `TheBloke/deepseek-llm-7B-chat-GGUF:Q3_K_M`: (eg thebloke huggingface identifier)
-- `local/neural-chat-7B-v3-1`: Neural Chat 7B (local as alias for gguf)
+- `openai/gpt-3.5-turbo`: ChatGPT Classic
+- `openai/gpt-4-1106-preview`: GPT-4-Turbo
+- `ollama/openchat`: OpenChat3.5-1210
+- `ollama/openhermes2.5-mistral`: OpenHermes 2.5
+- `llamacpp/openchat-3.5-1210`: OpenChat3.5-1210
+- `TheBloke/Nous-Hermes-2-SOLAR-10.7B-GGUF`: alias for `llamacpp/...`
+- `TheBloke/openchat-3.5-0106-GGUF:Q3_K_L`: with Q label
 
 ### additional notes
 
-Checkout the file `src/funcchain/utils/model_defaults.py` for the code that parses the string identifier.
+Checkout the file `src/funcchain/model/defaults.py` for the code that parses the string identifier.
 Feel free to create a PR to add more models to the defaults. Or tell me how wrong I am and create a better system.

README.md

@@ -8,13 +8,14 @@
 [![Twitter Follow](https://img.shields.io/twitter/follow/shroominic?style=social)](https://x.com/shroominic)
 
 ```bash
-> pip install "funcchain[all]"
+pip install funcchain
 ```
 
 ## Introduction
 
 `funcchain` is the *most pythonic* way of writing cognitive systems. Leveraging pydantic models as output schemas combined with langchain in the backend allows for a seamless integration of llms into your apps.
-It works perfect with OpenAI Functions or LlamaCpp grammars (json-schema-mode).
+It utilizes perfect with OpenAI Functions or LlamaCpp grammars (json-schema-mode) for efficient structured output.
+In the backend it compiles the funcchain syntax into langchain runnables so you can easily invoke, stream or batch process your pipelines.
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/ricklamers/funcchain-demo)
 
@@ -94,7 +95,7 @@ match lst:
 ## Vision Models
 
 ```python
-from PIL import Image
+from funcchain import Image
 from pydantic import BaseModel, Field
 from funcchain import chain, settings
 
@@ -132,7 +133,7 @@ from pydantic import BaseModel, Field
 from funcchain import chain, settings
 
 # auto-download the model from huggingface
-settings.llm = "gguf/openhermes-2.5-mistral-7b"
+settings.llm = "ollama/openchat"
 
 class SentimentAnalysis(BaseModel):
     analysis: str
@@ -153,32 +154,38 @@ print(poem.analysis)
 
 ## Features
 
-- minimalistic and easy to use
-- easy swap between openai and local models
-- write prompts as python functions
-- pydantic models for output schemas
-- langchain core in the backend
-- fstrings or jinja templates for prompts
-- fully utilises OpenAI Functions or LlamaCpp Grammars
+- pythonic
+- easy swap between openai or local models
+- dynamic output types (pydantic models, or primitives)
+- vision llm support
+- langchain_core as backend
+- jinja templating for prompts
+- reliable structured output
+- auto retry parsing
 - langsmith support
-- async and pythonic
-- auto gguf model download from huggingface
-- streaming support
+- sync, async, streaming, parallel, fallbacks
+- gguf download from huggingface
+- type hints for all functions and mypy support
+- chat router component
+- composable with langchain LCEL
+- easy error handling
+- enums and literal support
+- custom parsing types
 
 ## Documentation
 
-Highly recommend to try out the examples in the `./examples` folder.
+[Checkout the docs here](https://shroominic.github.io/funcchain/) 👈
 
-Coming soon... feel free to add helpful .md files :)
+Also highly recommend to try and run the examples in the `./examples` folder.
 
 ## Contribution
 
-You want to contribute? That's great! Please run the dev setup to get started:
+You want to contribute? Thanks, that's great!
+For more information checkout the [Contributing Guide](docs/contributing/dev-setup.md).
+Please run the dev setup to get started:
 
 ```bash
-> git clone https://github.com/shroominic/funcchain.git && cd funcchain
+git clone https://github.com/shroominic/funcchain.git && cd funcchain
 
-> ./dev_setup.sh
+./dev_setup.sh
 ```
-
-Thanks!

dev-setup.sh

@@ -3,16 +3,42 @@
 # check if rye is installed
 if ! command -v rye &> /dev/null
 then
-    echo "rye could not be found: installing now ..."
-    curl -sSf https://rye-up.com/get | bash
-    echo "Check the rye docs for more info: https://rye-up.com/"
+    echo "rye could not be found"
+    echo "Would you like to install via rye or pip? Enter 'rye' or 'pip':"
+    read install_method
+    clear
+
+    if [ "$install_method" = "rye" ]
+    then
+        echo "Installing via rye now ..."
+        curl -sSf https://rye-up.com/get | bash
+        echo "Check the rye docs for more info: https://rye-up.com/"
+
+    elif [ "$install_method" = "pip" ]
+    then
+        echo "Installing via pip now ..."
+        python3 -m venv .venv
+        source .venv/bin/activate
+        pip install -r requirements.lock
+
+    else
+        echo "Invalid option. Please run the script again and enter 'rye' or 'pip'."
+        exit 1
+    fi
+
+    clear
 fi
 
-echo "SYNC: setup .venv"
-rye sync
+if [ "$install_method" = "rye" ]
+then
+    echo "SYNC: setup .venv"
+    rye sync
+
+    echo "ACTIVATE: activate .venv"
+    rye shell
 
-echo "ACTIVATE: activate .venv"
-rye shell
+    clear
+fi
 
 echo "SETUP: install pre-commit hooks"
 pre-commit install

docs/advanced/async.md

@@ -0,0 +1,39 @@
+# Async
+
+## Why and how to use using async?
+
+Asyncronous promgramming is a way to easily parallelize processes in python.
+This is very useful when dealing with LLMs because every request takes a long time and the python interpreter should do alot of other things in the meantime instead of waiting for the request.
+
+Checkout [this brillian async tutorial](https://fastapi.tiangolo.com/async/) if you never coded in an asyncronous way.
+
+## Async in FuncChain
+
+You can use async in funcchain by creating your functions using `achain()` instead of the normal `chain()`.
+It would then look like this:
+
+```python
+from funcchain import achain
+
+async def generate_poem(topic: str) -> str:
+    """
+    Generate a poem inspired by the given topic.
+    """
+    return await achain()
+```
+
+You can then `await` the async `generate_poem` function inside another async funtion or directly call it using `asyncio.run(generate_poem("birds"))`.
+
+## Async in LangChain
+
+When converting your funcchains into a langchain runnable you can use the native langchain way of async.
+This would be `.ainvoke(...)`, `.astream(...)` or `.abatch(...)` .
+
+## Async Streaming
+
+You can use langchains async streaming interface but also use the `stream_to(...)` wrapper (explained [here](../concepts/streaming.md#strem_to-wrapper)) as an async context manager.
+
+```python
+async with stream_to(...):
+    await ...
+```

docs/advanced/codebase-scaling.md

@@ -0,0 +1,9 @@
+# Codebase Scaling
+
+## Multi file projects
+
+### TODO
+
+## Structure
+
+### TODO

docs/advanced/custom-parser-types.md

@@ -0,0 +1,21 @@
+# Custom Parsers
+
+## Example
+
+### TODO
+
+## Grammars
+
+### TODO
+
+## Format Instructions
+
+### TODO
+
+## parse() Function
+
+### TODO
+
+## Write your own Parser
+
+### TODO

docs/advanced/customization.md

@@ -0,0 +1,17 @@
+# Customization
+
+## extra args inside chain
+
+### TODO
+
+## low level langchain
+
+### TODO
+
+## extra args inside @runnable
+
+### TODO
+
+## custom ll models
+
+### TODO

docs/advanced/runnables.md

@@ -0,0 +1,9 @@
+# runnables
+
+## LangChain Expression Language (LCEL)
+
+### TODO
+
+## Streaming, Parallel, Async and
+
+### TODO

docs/advanced/signature.md

@@ -0,0 +1,9 @@
+# Signature
+
+## Compilation
+
+### TODO
+
+## Schema
+
+### TODO