Merge pull request #7 from goudete/docs

adding docs

docs/concepts.md

@@ -0,0 +1,118 @@
+# Concepts
+
+## Concepts Overview
+
+| name | description |
+|-|-|
+| chain | Main funcchain to get responses from the assistant |
+| achain | Async version of chain |
+| settings | Global settings object |
+| BaseModel | Pydantic model base class |
+
+
+## chain
+
+The `chain` function is the main interface to get responses from the assistant. It handles creating the prompt, querying the model, and parsing the response.
+
+Key things:
+
+- Takes instruction and system prompt strings to create the prompt
+- Automatically extracts docstring of calling function as instruction
+- Gets output parser based on return type annotation
+- Supports OpenAI Functions under the hood
+- Retries on parser failure
+- Logs tokens usage
+
+Usage:
+
+```python
+from funcchain import chain
+
+
+def get_weather(city: str) -> str:
+    """
+    Get the weather for {city}.
+    """
+    return chain()
+
+print(get_weather("Barcelona"))
+```
+
+## achain
+
+The `achain` function is an async version of `chain` that can be awaited.
+
+Usage:
+
+```python
+from funcchain import achain
+import asyncio
+
+
+async def get_weather(city: str) -> str:
+    """
+    Get the weather for {city}.
+    """
+    return await achain()
+
+
+print(asyncio.run(get_weather("Barcelona")))
+```
+
+## settings
+
+The `settings` object contains global settings for funcchain.
+
+Key attributes:
+
+- `LLM`: Configures the default LLM
+- `MAX_TOKENS`: Max tokens per request
+- `DEFAULT_SYSTEM_PROMPT`: Default system prompt
+- `OPENAI_API_KEY`: OpenAI API key
+- `model_kwargs()`: kwargs for model like temperature
+
+Usage:
+
+```python
+from funcchain import settings
+
+settings.LLM = MyCustomLLM()
+settings.MAX_TOKENS = 2048
+```
+
+## BaseModel
+
+`BaseModel` is the Pydantic model base class used to define output schemas.
+
+Funcchain can automatically parse responses to Pydantic models.
+
+Usage:
+
+```python
+from funcchain import chain
+from langchain.pydantic_v1 import BaseModel, Field
+
+
+class Article(BaseModel):
+    title: str = Field(..., description="Title of the article")
+    description: str = Field(
+        ..., description="Description of the content of the article"
+    )
+
+
+def summarize(text: str) -> Article:
+    """
+    Summarize the text into an Article:
+    {text}
+    """
+    return chain()
+
+
+print(
+    summarize(
+        """
+        AI has the potential to revolutionize education, offering personalized and individualized teaching, and improved learning outcomes. AI can analyze student data and provide real-time feedback to teachers and students, allowing them to adjust their teaching and learning strategies accordingly. One of the biggest benefits of AI in education is the ability to provide personalized and individualized teaching. AI can analyze student data and create a personalized learning plan for each individual student, taking into account their strengths, weaknesses, and learning styles. This approach has the potential to dramatically improve learning outcomes and engagement. The potential of AI in education is enormous, and it is expected to revolutionize the way we approach degree and diploma programs in the future. AI-powered technologies can provide students with real-time feedback, help them to stay on track with their studies, and offer a more personalized and engaging learning experience.
+        """
+    )
+)
+```

docs/examples.md

@@ -0,0 +1,66 @@
+# Examples
+
+## Basic Usage
+
+The `chain()` function allows you to call a prompt like a regular Python function. The docstring serves as the instructions and the return type annotation determines the output parsing.
+
+```python
+from funcchain import chain
+
+def hello_world() -> str:
+    """
+    Generate a friendly hello world message.
+    """
+    return chain()
+
+print(hello_world())
+```
+
+This will send the docstring to the AI assistant and parse the response as a string.
+
+## Pydantic Models
+
+You can use Pydantic models to validate the response.
+
+```python
+from funcchain import chain
+from langchain.pydantic_v1 import BaseModel
+
+
+class Message(BaseModel):
+    text: str
+
+
+def hello_message() -> Message:
+    """
+    Generate a message object that says hello.
+    """
+    return chain()
+
+
+print(hello_message())
+```
+
+Now the response will be parsed as a Message object.
+
+## Asynchronous Support
+
+Async functions are also supported with `achain()`:
+
+```python
+import asyncio
+from funcchain import achain
+
+async def async_hello() -> str:
+    """Say hello asynchronously"""
+    return await achain()
+
+print(asyncio.run(async_hello()))
+```
+
+This allows you to easily call AI functions from async code.
+
+The funcchain project makes it really simple to leverage large language models in your Python code! Check out the source code for more examples.
+
+## Advanced Examples
+For advanced examples, checkout the examples directory [here](https://github.com/shroominic/funcchain/tree/main/examples)

docs/getting_started.md

@@ -0,0 +1,61 @@
+# Getting Started
+
+## Welcome
+
+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 and soon with other models using JSONFormer.
+
+Key features:
+
+- increased productivity
+- prompts as Python functions
+- pydantic models as output schemas
+- langchain schemas in the backend
+- fstrings or jinja templates for prompts
+- fully utilises OpenAI Functions
+- minimalistic and easy to use
+
+## Installation
+
+funcchain requires python 3.10+
+```bash
+pip install funcchain
+```
+
+Make sure to have an OpenAI API key in your environment variables. For example,
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+## Usage
+
+```python
+from funcchain import chain
+
+def hello() -> str:
+    """Say hello in 3 languages"""
+    return chain()
+
+print(hello())
+```
+
+This will call the OpenAI API and return the response.
+
+The `chain` function extracts the docstring as the prompt and the return type for parsing the response.
+
+## Contributing
+
+To contribute, clone the repo and run:
+
+```
+./dev_setup.sh
+```
+
+This will install pre-commit hooks, dependencies and set up the environment.
+
+To activate the virtual environment managed by poetry, you can use the following command:
+
+```bash
+poetry shell
+```