Merge pull request #10 from dimagi/sk/reorg

Some reorganization and fixes

docs/about.md

@@ -0,0 +1,9 @@
+---
+hide:
+  - navigation
+---
+# About Open Chat Studio
+
+[Dimagi](https://dimagi.com/) is developing Open Chat Studio (OCS) as an easy-to-use, open source platform for rapidly prototyping and testing chatbots created using Large Language Models (LLMs). Open Chat Studio makes it easy to develop and test LLM-based chatbots, and to instill a variety of guardrails to improve the safety and accuracy of these bots.
+
+Open Chat Studio can work with any LLM with an API such as the [OpenAI Chat Completions API](https://platform.openai.com/docs/guides/text-generation).

docs/team-configuration/authentication-providers.md → docs/concepts/authentication-providers.md

@@ -3,7 +3,7 @@
 Authentication Providers are used to authenticate with external services via HTTP API calls. Authentication Providers
 provide a centralized location to manage the credentials and tokens required to authenticate with external services.
 
-These credentials are used by features like [Custom Actions](/conceptual_guide/custom_actions/).
+These credentials are used by features like [Custom Actions](../concepts/custom_actions.md).
 
 ## Authentication Provider Types
 

docs/conceptual_guide/custom_actions.md → docs/concepts/custom_actions.md

@@ -13,7 +13,7 @@ Before you create a Custom Action will need to create an Authentication Provider
 you are using does not require authentication). You can do this by navigating to the [Authentication Providers][auth_providers] section
 in Team Settings and creating a new Authentication Provider.
 
-[auth_providers]: ../team-configuration/authentication-providers.md
+[auth_providers]: ../concepts/authentication-providers.md
 
 ### Base URL
 

docs/conceptual_guide/chatbot_types.md → docs/concepts/experiment/index.md

@@ -1,29 +1,39 @@
-# Chatbot Types
+# Experiments
+
+An 'Experiment' is the current name used in Open Chat Studio to refer to a 'chatbot'. The name may change in the
+future.
+
+An Experiment links all the configuration and data for a chatbot including user sessions, data, actions etc.
+
+## Experiment Types
 
 There are three different types of chatbots that you can build in Open Chat Studio:
 
 - Base language model
 - Assistant
 - Pipeline
 
-## Base language model
+### Base language model
 
-This kind of bot is the most commonly used and simple to configure. It is backed the standard language model APIs such as OpenAI’s [chat completions API][1], Anthropic’s [messages API][2] or Google’s [Gemeni API][3].
+This kind of bot is the most commonly used and simple to configure. It is backed the standard language model APIs such as the OpenAI [chat completions API][1], Anthropic [messages API][2] or Google [Gemini API][3].
 
 Bots configured in this way have all the basic features (memory, source material etc.) and can also use some of the advanced features like Scheduling and Reminders.
 
 
-## Assistant
-Assistant bots make use of OpenAI’s [Assistants][4]. The main advantage of using Assistants is that your bot get’s access to the OpenAI tools:
+### Assistant
+Assistant bots make use of OpenAI [Assistants][4]. The main advantage of using Assistants is that your bot gets access to the OpenAI tools:
 
-### [Code Interpreter][5]
+#### Code Interpreter
 This allows the bot to write and execute code to accomplish tasks.
 
-### [File Search][6]
+For more information see the [OpenAI docs][5].
+
+#### File Search
 This allows the bot to search and reference information provided in uploaded files. Unless your bot needs either of these capabilities, you should use a Base Language Model type bot.
 
+For more information see the [OpenAI docs][6].
 
-## Pipeline
+### Pipeline
 This is a beta feature that has not yet been fully released. Pipelines allow you to create more complex bots by defining a ‘graph’ of nodes. Each message to the bot is processed by the graph to produce a final output.
 
 This can be useful if you want to build a complex bot that performs different tasks depending on the user’s request. Generally, trying to make a single bot prompt do multiple functions doesn’t work well so it is better to create multiple prompts for each task and then combine them using a Pipeline. This is similar to the Multi-bot setup but allows more flexibility and complexity.
@@ -34,4 +44,4 @@ This can be useful if you want to build a complex bot that performs different ta
 [3]: https://ai.google.dev/
 [4]: https://platform.openai.com/docs/assistants/overview
 [5]: https://platform.openai.com/docs/assistants/tools/code-interpreter
-[6]: https://platform.openai.com/docs/assistants/tools/file-search
+[6]: https://platform.openai.com/docs/assistants/tools/file-search

docs/concepts/index.md

@@ -0,0 +1,12 @@
+---
+title: Concepts
+description: Conceptual Guide for Open Chat Studio
+---
+
+# Conceptual Guide
+
+This guide provides explanations of the key concepts behind the Open Chat Studio platform and AI applications more
+broadly.
+
+The conceptual guide does not cover step-by-step instructions or specific examples — those are found in
+the [How-to guides](../how-to/index.md).

docs/conceptual_guide/llm.md → docs/concepts/llm.md

@@ -1,31 +1,55 @@
-# LLMs (Large Language Models)
-An *LLM* is a type of artificial intelligence model trained on vast amounts of text data. It can generate human-like text, answer questions, and perform various language-based tasks. Examples include OpenAI's GPT models.
-When building chatbots, an LLM powers the chatbot's ability to understand and respond to user inputs, effectively acting as the brain behind your chatbot.
-
 ---
+title: Large Language Model
+---
+
+# Large Language Models (LLMs)
+
+!!! note "Definition"
+    A Large Language Model (or LLM) is a type of artificial intelligence software that is trained on a vast amount of text data. Its
+    primary function is to understand, interpret, and generate human language. This training allows it to produce text-based
+    responses, answer questions, translate between languages, and perform various other language-related tasks. 
+
+    The term "large" in its name refers to the extensive volume of data it has been trained on and the complexity of its design, enabling it to handle complex language tasks.
+
+<small>The definition above was authored by the famous LLM that powers ChatGPT: GPT-4 developed by OpenAI.</small>
+
+When building chatbots, an LLM powers the chatbot's ability to understand and respond to user inputs, effectively acting as the brain behind the chatbot.
 
-## Temperature
+## Which Large Language Models are supported by Open Chat Studio?
+
+Open Chat Studio is developed to support a range of LLMs. The platform is designed to be flexible and can work with any
+LLM that has an API. The platform is currently supports all the models provided by the following APIs:
+
+* [OpenAI](https://platform.openai.com/docs/models)
+* [Azure OpenAi](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions)
+* [Anthropic](https://docs.anthropic.com/en/docs/about-claude/models_)
+* [Groq](https://console.groq.com/docs/models)
+* [Perplexity](https://docs.perplexity.ai/guides/model-cards)
+
+## Model Configuration Parameters
+
+### Temperature
 Temperature controls the creativity or randomness of the chatbot's responses.
 
 - A low temperature (e.g., 0.1) makes the chatbot more deterministic, providing straightforward and predictable answers.
 - A high temperature (e.g., 0.9) makes responses more creative, varied, or even surprising.
 
-####Example:
+#### Example:
 - Low temperature: *What's a dog?* → A dog is a domesticated animal.
 - High temperature: *What's a dog?* → A dog is a loyal companion, a furry friend who fills your life with wagging tails and boundless joy.
 
 The default temperature of 0.7 is a balanced choice designed to provide responses that are both varied and  interesting, while still being coherent.
 
 ---
 
-## Prompt
+### Prompt
 A prompt is the input or instructions given to the LLM to guide its response. It sets the context for the chatbot. Prompts can be as simple as a user question or as detailed as a conversation framework or role-play setup.
 
 #### Example:
 You are a helpful assistant. Answer questions clearly and concisely.
 
 
-## Tokens
+### Tokens
 Tokens are the building blocks of text that the LLM processes. A token might be a word, a part of a word, or even just punctuation.
 
 #### Example:
@@ -36,7 +60,7 @@ Tokens are important because they determine the cost and the processing complexi
 
 ---
 
-## Max Token Limit
+### Max Token Limit
 The max token limit is the maximum number of tokens the LLM can handle in a single interaction, including both the input (prompt) and output (response).
 
 #### Example:

docs/conceptual_guide/prompt_variables.md → docs/concepts/prompt_variables.md

@@ -6,7 +6,7 @@ Prompt variables are a great way to make your prompt dynamic or tailored to the
 
 The following variables are currently supported:
 
-- `{source_material}` - The [source material](../how-to/adding_source_material.md) linked to your bot.
+- `{source_material}` - The [source material](../how-to/add_a_knowledge_base.md) linked to your bot.
 - `{participant_data}` - Information specific to this participant. This data is accessible only within the context of this participant and bot, ensuring that only this bot can access it.
 - `{current_datetime}` - This refers to the date and time at which the response is generated.
 
@@ -17,4 +17,4 @@ The following variables are currently supported:
 !!! info "A note on prompt caching"
     Some LLM providers like OpenAI, use a technique called "prompt caching" to reduce latency and costs (See [here][0]). This happens automatically. However, caching is only effective for static data i.e. data that does not change. To take full advantage of this caching mechanism, you should place prompt variables near the end of your prompt whenever possible
 
-[0]: https://platform.openai.com/docs/guides/prompt-caching
+[0]: https://platform.openai.com/docs/guides/prompt-caching

docs/conceptual_guide/source_material.md → docs/concepts/source_material.md

@@ -13,6 +13,5 @@ Source Material is a feature that allows you to provide specific content, inform
 - Organization and Structure: Well-organized Source Materials make it easier for the chatbot to retrieve and use the information. It's useful to structure your content in a clear, concise manner, with appropriate labels for different sections. 
 
 #### See also
-- [prompt variables](./prompt_variables.md)
-- [Add a knowldege base](../how-to/add_a_knowledge_base.md)
-
+- [Prompt variables](./prompt_variables.md)
+- [Add a_knowledge base](../how-to/add_a_knowledge_base.md)

docs/concepts/team/index.md

@@ -0,0 +1,24 @@
+---
+hide:
+  - toc
+---
+# Teams
+
+Open Chat Studio is a [multitenant](https://en.wikipedia.org/wiki/Multitenancy) platform that can support multiple organizations using the same instance at the same time. Each 'tenant' is called a 'team'. Teams are created by an organization and can have multiple members. Each team has its own settings and experiments.
+
+A user can be a member of multiple teams and have a different set of permissions in each team.
+
+A team serves as the root container for all data in Open Chat Studio.
+
+## Team configuration
+
+There is a set of global configuration that can be set at the team level. This includes:
+
+- LLM Service Providers
+- Speech Service Providers
+- Messaging Providers
+- [Authentication Providers](./authentication-providers.md)
+- [Custom Actions](./custom_actions.md)
+- Tracing providers
+
+<!--- TODO: user management -->

docs/conceptual_guide/versioning.md → docs/concepts/versioning.md

@@ -5,13 +5,12 @@ Versioning is now enabled by default for all projects on Open Chat Studio. This
 ## Terms
 OCS uses the following terms:
 
-* **Unreleased Version*. This is the version of the chatbot that exists when you click the edit button on the experiment. It can also be considered a `draft` or that it has "unsaved changes".
+* *Unreleased Version*. This is the version of the chatbot that exists when you click the edit button on the experiment. It can also be considered a "draft" or that it has "unsaved changes".
 
-* **Published Version*. This is the version that users will interact with through the web, WhatsApp or any other configured channel--including the public link.
+* *Published Version*. This is the version that users will interact with through the web, WhatsApp or any other configured channel--including the public link.
 
 !!! info "A note version functionality"
-    Once a version is made, it cannot be edited or modified. This ensures that the users' experience remains stable even if the authors may be changing the unrealeased version.
-
+    Once a version is made, it cannot be edited or modified. This ensures that the users' experience remains stable even if the authors may be changing the unreleased version.
 
 !!! warning "Chatting to the unreleased version"
 
@@ -20,7 +19,9 @@ OCS uses the following terms:
 #### Changing the Published Version
 The published version can be selected from any released version of the experiment. To modify which version is the published version:
 
-- select "View Details" of the version
-- press the "Set as Published Version" button at the button of the modal
+- Select "View Details" of the version
+- Press the "Set as Published Version" button at the button of the dialog box.
+
+Alternatively, when a new version is being created, it can be set as the published version by marking the checkbox "Set as Published Version".
 
-Alternatively, when a new version is being created, it can be set as the published version by marking the checkbox "Set as Published Version." Only one version can be the published verion at a time.
+Only one version can be the published version at a time.

docs/how-to/add_a_knowledge_base.md

@@ -20,7 +20,7 @@ You are a friendly bot. Be sure to reference the source material before answerin
 ```
 
 ## Assistant
-To add knowldege to your assistant, you must upload files to serve as the source material. When creating or editing your assistant, select the *file_search* or *code_interpreter* checkboxes to allow the assistant to read files.
+To add knowledge to your assistant, you must upload files to serve as the source material. When creating or editing your assistant, select the *file_search* or *code_interpreter* checkboxes to allow the assistant to read files.
 
 - [File search][file_search]: This allows the bot to search and reference information provided in uploaded files.
 - [Code Interpreter][code_interpreter]: This allows the bot to write and execute code to accomplish tasks.
@@ -29,8 +29,8 @@ To add knowldege to your assistant, you must upload files to serve as the source
 ### See also
 - [Source Material][source_material_concept]
 
-[source_material_concept]: ../conceptual_guide/source_material.md
-[prompt_variables_concept]: ../conceptual_guide/prompt_variables.md
+[source_material_concept]: ../concepts/source_material.md
+[prompt_variables_concept]: ../concepts/prompt_variables.md
 [assistants]: https://platform.openai.com/docs/assistants/overview
 [file_search]: https://platform.openai.com/docs/assistants/tools/file-search
 [code_interpreter]: https://platform.openai.com/docs/assistants/tools/code-interpreter

docs/how-to/index.md

@@ -0,0 +1,11 @@
+---
+title: How-to Guides
+description: How to accomplish common tasks Open Chat Studio
+---
+
+# How-to Guides
+
+Here you’ll find answers to “How do I...?” types of questions. These guides are **goal-oriented** and concrete; they're
+meant to help you complete a specific task. 
+
+For conceptual explanations see the [Conceptual guide](../concepts/index.md).

docs/how-to/remote_api.md

@@ -2,7 +2,7 @@
 
 Open Chat Studio allows you to connect to external services via HTTP API calls. This feature is useful for extending the functionality of your bot by integrating it with other services. This feature is analogous to OpenAI's [GPT Actions](https://platform.openai.com/docs/actions/introduction) feature.
 
-To do this you will need to create a Custom Action by navigating to the [Authentication Providers](../team-configuration/authentication-providers.md) section in Team Settings. See the [Custom Actions](../conceptual_guide/custom_actions.md) guide for more information on how to create a Custom Action.
+To do this you will need to create an action by navigating to the "Custom Actions" section in Team Settings. See the [Custom Actions](../concepts/custom_actions.md) guide for more information on creating a Custom Action.
 
 ## Using the custom action in your bot
 

docs/index.md

@@ -1,3 +1,9 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
 # Open Chat Studio
 
 This is the home page for all documentation related to [Open Chat Studio](https://github.com/dimagi/open-chat-studio).

mkdocs.yml

@@ -1,9 +1,46 @@
 site_name: Open Chat Studio Documentation
+site_url: https://dimagi.github.io/open-chat-studio-docs/
 theme:
   name: material
+  features:
+    - header.autohide
+    - navigation.expand
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    - navigation.prune
+    - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.tracking
+    - navigation.top
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
 copyright: Copyright © 2024 Dimagi
 
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - How-to Guides:
+      - how-to/index.md
+      - how-to/add_a_knowledge_base.md
+      - how-to/remote_api.md
+  - Concepts:
+      - concepts/index.md
+      - Experiments:
+        - concepts/experiment/index.md
+        - concepts/llm.md
+        - concepts/prompt_variables.md
+        - concepts/source_material.md
+        - concepts/versioning.md
+        - concepts/custom_actions.md
+      - Team:
+          - concepts/team/index.md
+          - concepts/authentication-providers.md
+  - About: about.md