Add user guide (#179)

* wip

* test fixed

* wip

* wip

* User guide added

* version bumped to 0.1.0b0

---------

Co-authored-by: Kumaran Rajendhiran <kumaran@airt.ai>

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-> **_NOTE:_**  This is an auto-generated file. Please edit docs/docs/en/getting-started/contributing/CONTRIBUTING.md instead.
+> **_NOTE:_**  This is an auto-generated file. Please edit docs/docs/en/contributing/CONTRIBUTING.md instead.
 
 # Development
 

README.md

@@ -61,8 +61,8 @@ With FastAgency, you can create interactive applications using various interface
 
 FastAgency currently supports workflows defined using AutoGen and provides options for different types of applications:
 
-- **Console**: Use the [ConsoleIO](https://fastagency.ai/latest/api/fastagency/core/io/console/ConsoleIO/) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.
-- **Mesop**: Utilize [Mesop](https://google.github.io/mesop/) with [MesopIO](https://fastagency.ai/latest/api/fastagency/core/io/mesop/MesopIO/) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.
+- **Console**: Use the [ConsoleUI](https://fastagency.ai/latest/api/fastagency/io/console/ConsoleUI/) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.
+- **Mesop**: Utilize [Mesop](https://google.github.io/mesop/) with [MesopUI](https://fastagency.ai/latest/api/fastagency/io/mesop/MesopUI/) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.
 
 We are also working on adding support for other frameworks, such as [CrewAI](https://www.crewai.com/), to broaden the scope and capabilities of FastAgency. Stay tuned for updates on these integrations.
 
@@ -92,14 +92,14 @@ import os
 
 from autogen.agentchat import ConversableAgent
 
-from fastagency.core import Chatable
-from fastagency.core.runtimes.autogen.base import AutoGenWorkflows
-from fastagency.core.io.console import ConsoleIO
+from fastagency import UI
+from fastagency.runtimes.autogen.base import AutoGenWorkflows
+from fastagency.ui.console import ConsoleUI
 
 from fastagency import FastAgency
 ```
 
-For Console applications, import `ConsoleIO` to handle command-line input and output.
+For Console applications, import `ConsoleUI` to handle command-line input and output.
 
 
 ### Define Workflow
@@ -120,7 +120,7 @@ llm_config = {
 wf = AutoGenWorkflows()
 
 @wf.register(name="simple_learning", description="Student and teacher learning chat")
-def simple_workflow(io: Chatable, initial_message: str, session_id: str) -> str:
+def simple_workflow(ui: UI, initial_message: str, session_id: str) -> str:
     student_agent = ConversableAgent(
         name="Student_Agent",
         system_message="You are a student willing to learn.",
@@ -149,9 +149,9 @@ This code snippet sets up a simple learning chat between a student and a teacher
 Next, define your FastAgency application. This ties together your workflow and the interface you chose:
 
 ```python
-from fastagency.core.io.console import ConsoleIO
+from fastagency.ui.console import ConsoleUI
 
-app = FastAgency(wf=wf, io=ConsoleIO())
+app = FastAgency(wf=wf, io=ConsoleUI())
 ```
 
 ## Run Application

docs/docs.py

@@ -28,9 +28,7 @@
 EN_DOCS_DIR = DOCS_DIR / "en"
 EN_INDEX_PATH = EN_DOCS_DIR / "index.md"
 README_PATH = BASE_DIR.parent / "README.md"
-EN_CONTRIBUTING_PATH = (
-    EN_DOCS_DIR / "getting-started" / "contributing" / "CONTRIBUTING.md"
-)
+EN_CONTRIBUTING_PATH = EN_DOCS_DIR / "contributing" / "CONTRIBUTING.md"
 CONTRIBUTING_PATH = BASE_DIR.parent / "CONTRIBUTING.md"
 
 

docs/docs/SUMMARY.md

@@ -4,11 +4,20 @@ search:
 ---
 - Getting Started
     - [Getting Started](getting-started/index.md)
-- Tutorial
-    - [Getting Started](tutorial/index.md)
-    - [Using External REST APIs](tutorial/external-rest-apis/index.md)
-    - [Using External REST APIs with security](tutorial/external-rest-apis/security.md)
-    - [Custom User Interactions](tutorial/custom-user-interactions/index.md)
+- [User guide](user-guide/index.md)
+    - [Runtimes](user-guide/runtime/index.md)
+        - [AutoGen](user-guide/runtime/autogen/index.md)
+            - [User interaction](user-guide/runtime/autogen/interactions.md)
+        - [CrewAI](user-guide/runtime/crewai/basics.md)
+    - [UI](user-guide/ui/index.md)
+        - [Console](user-guide/ui/console/basics.md)
+        - [Mesop](user-guide/ui/mesop/basics.md)
+        - [FastAPI](user-guide/ui/fastapi/basics.md)
+    - [API-s](user-guide/api/index.md)
+        - [OpenAPI](user-guide/api/openapi/index.md)
+        - [Security](user-guide/api/security.md)
+    - [Testing](user-guide/testing/index.md)
+    - [CLI](user-guide/cli/index.md)
 - Reference
     - fastagency
         - [FastAgency](api/fastagency/FastAgency.md)
@@ -76,14 +85,14 @@ search:
                 - [setup_logging](api/fastagency/cli/logging/setup_logging.md)
         - logging
             - [get_logger](api/fastagency/logging/get_logger.md)
-        - runtimes
+        - runtime
             - autogen
-                - [AutoGenWorkflows](api/fastagency/runtimes/autogen/AutoGenWorkflows.md)
-                - [IOStreamAdapter](api/fastagency/runtimes/autogen/IOStreamAdapter.md)
+                - [AutoGenWorkflows](api/fastagency/runtime/autogen/AutoGenWorkflows.md)
+                - [IOStreamAdapter](api/fastagency/runtime/autogen/IOStreamAdapter.md)
                 - base
-                    - [AutoGenWorkflows](api/fastagency/runtimes/autogen/base/AutoGenWorkflows.md)
-                    - [CurrentMessage](api/fastagency/runtimes/autogen/base/CurrentMessage.md)
-                    - [IOStreamAdapter](api/fastagency/runtimes/autogen/base/IOStreamAdapter.md)
+                    - [AutoGenWorkflows](api/fastagency/runtime/autogen/base/AutoGenWorkflows.md)
+                    - [CurrentMessage](api/fastagency/runtime/autogen/base/CurrentMessage.md)
+                    - [IOStreamAdapter](api/fastagency/runtime/autogen/base/IOStreamAdapter.md)
         - studio
             - app
                 - [ChatRequest](api/fastagency/studio/app/ChatRequest.md)
@@ -262,7 +271,7 @@ search:
                 - send_prompt
                     - [send_prompt_to_autogen](api/fastagency/ui/mesop/send_prompt/send_prompt_to_autogen.md)
                     - [send_user_feedback_to_autogen](api/fastagency/ui/mesop/send_prompt/send_user_feedback_to_autogen.md)
-- Contributing
-    - [Development](getting-started/contributing/CONTRIBUTING.md)
-    - [Documentation](getting-started/contributing/docs.md)
+- [Contributing](contributing/index.md)
+    - [Development](contributing/CONTRIBUTING.md)
+    - [Documentation](contributing/docs.md)
 - [Release Notes](release.md)

docs/docs/en/api/fastagency/runtimes/autogen/AutoGenWorkflows.md → docs/docs/en/api/fastagency/runtime/autogen/AutoGenWorkflows.md

@@ -8,4 +8,4 @@ search:
   boost: 0.5
 ---
 
-::: fastagency.runtimes.autogen.AutoGenWorkflows
+::: fastagency.runtime.autogen.AutoGenWorkflows

docs/docs/en/api/fastagency/runtimes/autogen/IOStreamAdapter.md → docs/docs/en/api/fastagency/runtime/autogen/IOStreamAdapter.md

@@ -8,4 +8,4 @@ search:
   boost: 0.5
 ---
 
-::: fastagency.runtimes.autogen.IOStreamAdapter
+::: fastagency.runtime.autogen.IOStreamAdapter

docs/docs/en/api/fastagency/runtime/autogen/base/AutoGenWorkflows.md

@@ -0,0 +1,11 @@
+---
+# 0.5 - API
+# 2 - Release
+# 3 - Contributing
+# 5 - Template Page
+# 10 - Default
+search:
+  boost: 0.5
+---
+
+::: fastagency.runtime.autogen.base.AutoGenWorkflows

docs/docs/en/api/fastagency/runtimes/autogen/base/CurrentMessage.md → docs/docs/en/api/fastagency/runtime/autogen/base/CurrentMessage.md

@@ -8,4 +8,4 @@ search:
   boost: 0.5
 ---
 
-::: fastagency.runtimes.autogen.base.CurrentMessage
+::: fastagency.runtime.autogen.base.CurrentMessage

docs/docs/en/api/fastagency/runtimes/autogen/base/IOStreamAdapter.md → docs/docs/en/api/fastagency/runtime/autogen/base/IOStreamAdapter.md

@@ -8,4 +8,4 @@ search:
   boost: 0.5
 ---
 
-::: fastagency.runtimes.autogen.base.IOStreamAdapter
+::: fastagency.runtime.autogen.base.IOStreamAdapter

docs/docs/en/contributing/index.md

@@ -0,0 +1 @@
+# Contributing

docs/docs/en/getting-started/index.md

@@ -73,8 +73,8 @@ With FastAgency, you can create interactive applications using various interface
 
 FastAgency currently supports workflows defined using AutoGen and provides options for different types of applications:
 
-- **Console**: Use the [ConsoleIO](../api/fastagency/core/io/console/ConsoleIO.md) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.
-- **Mesop**: Utilize [Mesop](https://google.github.io/mesop/){target="_blank"} with [MesopIO](../api/fastagency/core/io/mesop/MesopIO.md) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.
+- **Console**: Use the [ConsoleUI](../api/fastagency/io/console/ConsoleUI.md) interface for command-line based interaction. This is ideal for developing and testing workflows in a text-based environment.
+- **Mesop**: Utilize [Mesop](https://google.github.io/mesop/){target="_blank"} with [MesopUI](../api/fastagency/io/mesop/MesopUI.md) for web-based applications. This interface is suitable for creating web applications with a user-friendly interface.
 
 We are also working on adding support for other frameworks, such as [CrewAI](https://www.crewai.com/){target="_blank"}, to broaden the scope and capabilities of FastAgency. Stay tuned for updates on these integrations.
 
@@ -119,33 +119,25 @@ To get started, you need to install FastAgency. You can do this using `pip`, Pyt
 Depending on the interface you choose, you'll need to import different modules. These imports set up the necessary components for your application:
 
 === "Console"
-    ```python
-    {!> docs_src/tutorial/getting_started/main.py [ln:1-8] !}
+    ```python hl_lines="7"
+    {!> docs_src/getting_started/main_console.py [ln:1-8] !}
     ```
 
-    For Console applications, import `ConsoleIO` to handle command-line input and output.
+    For Console applications, import `ConsoleUI` to handle command-line input and output.
 
 === "Mesop"
-    ```python
-    import os
-
-    from autogen.agentchat import ConversableAgent
-
-    from fastagency.core import Chatable
-    from fastagency.core.runtimes.autogen.base import AutoGenWorkflows
-    from fastagency.core.io.mesop import MesopIO
-
-    from fastagency import FastAgency
+    ```python hl_lines="7"
+    {!> docs_src/getting_started/main_mesop.py [ln:1-8] !}
     ```
 
-    For Mesop applications, import `MesopIO` to integrate with the Mesop web interface.
+    For Mesop applications, import `MesopUI` to integrate with the Mesop web interface.
 
 ### Define Workflow
 
 You need to define the workflow that your application will use. This is where you specify how the agents interact and what they do. Here's a simple example of a workflow definition:
 
 ```python
-{! docs_src/tutorial/getting_started/main.py [ln:10-43] !}
+{! docs_src/getting_started/main_console.py [ln:10-43] !}
 ```
 
 This code snippet sets up a simple learning chat between a student and a teacher. You define the agents and how they should interact, specifying how the conversation should be summarized.
@@ -155,20 +147,18 @@ This code snippet sets up a simple learning chat between a student and a teacher
 Next, define your FastAgency application. This ties together your workflow and the interface you chose:
 
 === "Console"
-    ```python
-    {!> docs_src/tutorial/getting_started/main.py [ln:7,46,47] !}
+    ```python hl_lines="1"
+    {!> docs_src/getting_started/main_console.py [ln:47] !}
     ```
 
-    For Console applications, use `ConsoleIO` to handle user interaction via the command line.
+    For Console applications, use `ConsoleUI` to handle user interaction via the command line.
 
 === "Mesop"
-    ```python
-    from fastagency.core.io.mesop import MesopIO
-
-    app = FastAgency(wf=wf, io=MesopIO())
+    ```python hl_lines="1"
+    {!> docs_src/getting_started/main_mesop.py [ln:47] !}
     ```
 
-    For Mesop applications, use `MesopIO` to enable web-based interactions.
+    For Mesop applications, use `MesopUI` to enable web-based interactions.
 
 ### Run Application
 

docs/docs/en/user-guide/api/index.md

@@ -0,0 +1,23 @@
+# API Integration
+
+FastAgency makes it easy to integrate external APIs into your multi-agent workflows, allowing agents to access and interact with real-time data. By leveraging FastAgency's API support, developers can automatically create functions properly annotated for use with large language models (LLMs). This functionality allows agents to fetch and process external information seamlessly.
+
+Currently, FastAgency supports importing API functionality from [**OpenAPI**](https://swagger.io/specification/) specifications, enabling developers to connect their agents with RESTful APIs effortlessly. In addition, we support various types of security for accessing APIs, ensuring your integrations are both functional and secure.
+
+## API Features in FastAgency
+
+### 1. **[OpenAPI Import](./openapi/)**
+FastAgency can automatically generate API functions from OpenAPI specifications, streamlining the process of connecting agents to external services. With just a few lines of code, you can import an API specification, and FastAgency will handle the function generation and LLM integration, making it simple for agents to call external APIs.
+
+[Learn more about OpenAPI Import →](./openapi/)
+
+### 2. **[API Security](./security/)**
+FastAgency supports different types of security for REST APIs, including OAuth, API keys, and more. This ensures that your API integrations are secure and can handle sensitive data. Our API security mechanisms are flexible, allowing you to configure and manage secure communication between your agents and external APIs.
+
+[Learn more about API Security →](./security/)
+
+---
+
+FastAgency’s API integration capabilities allow your multi-agent systems to interact with the real world in meaningful ways. Whether you’re pulling data from an external service or managing secure connections, FastAgency provides the tools you need to build powerful, connected applications.
+
+For more updates and discussions, join our [**Discord channel**](https://discord.gg/kJjSGWrknU).

docs/docs/en/tutorial/external-rest-apis/index.md → docs/docs/en/user-guide/api/openapi/index.md

@@ -1,4 +1,4 @@
-# Using External REST APIs
+# OpenAPI
 
 FastAgency can automatically create functions properly annotated for use with LLM-s from [OpenAPI](https://swagger.io/specification/) specification.
 
@@ -21,15 +21,15 @@ pip install "fastagency[autogen,openapi]"
 These imports are similar to the imports section we have already covered, with the only difference being the additional imports of the `OpenAPI` Client and `UserProxyAgent`:
 
 ```python
-{! docs_src/tutorial/external_rest_apis/main.py [ln:1-10] !}
+{! docs_src/user_guide/external_rest_apis/main.py [ln:1-10] !}
 ```
 
 ## Define Workflow
 
 In this workflow, the only difference is that we create a Python client for the external REST API by passing the URL of the `openapi.json` to the `Client.create` method. Then, we register the generated client with the agent using the methods `register_for_llm` and `register_for_execution`. Here's a simple example of a workflow definition:
 
 ```python
-{! docs_src/tutorial/external_rest_apis/main.py [ln:12-55] !}
+{! docs_src/user_guide/external_rest_apis/main.py [ln:12-55] !}
 ```
 
 This code snippet sets up a simple weather agent that calls an external weather API using the registered functions generated from the `openapi.json` URL.
@@ -39,15 +39,15 @@ This code snippet sets up a simple weather agent that calls an external weather
 Next, define your FastAgency application.
 
 ```python
-{! docs_src/tutorial/external_rest_apis/main.py [ln:58] !}
+{! docs_src/user_guide/external_rest_apis/main.py [ln:58] !}
 ```
 
 ## Run Application
 
 You can run this chapter's FastAgency application using the following command:
 
 ```console
-fastagency run docs/docs_src/tutorial/external_rest_apis/main.py
+fastagency run docs/docs_src/user_guide/external_rest_apis/main.py
 ```
 
 ## Output

docs/docs/en/tutorial/external-rest-apis/security.md → docs/docs/en/user-guide/api/security.md

@@ -1,4 +1,4 @@
-# Using External REST APIs with security
+# Security
 
 In the [previous chapter](./index.md){.internal-link}, we learned how to integrate external REST APIs into `AutoGen` agents using `FastAgency`, and we used a weather API route which had no security. However, not all external REST APIs are open to the public; some are behind a paywall and require security parameters for access. This section of the documentation explains how to create an agent that accesses an external REST API with security.
 
@@ -19,7 +19,7 @@ pip install "fastagency[autogen,openapi]"
 The imports are the same as in the [previous chapter](./index.md){.internal-link}, except here we also import `APIKeyHeader` to set the security value in the header:
 
 ```python hl_lines="11"
-{! docs_src/tutorial/external_rest_apis/security.py [ln:1-11] !}
+{! docs_src/user_guide/external_rest_apis/security.py [ln:1-11] !}
 ```
 
 ## Define Workflow
@@ -29,13 +29,13 @@ In this workflow, we create a Python client for the external REST API by passing
 Additionally, we set the API key for the API using the `set_security_params` method:
 
 ```python hl_lines="2"
-{! docs_src/tutorial/external_rest_apis/security.py [ln:33.5,34.5] !}
+{! docs_src/user_guide/external_rest_apis/security.py [ln:33.5,34.5] !}
 ```
 
 Here's a simple example of a workflow definition:
 
 ```python hl_lines="22"
-{! docs_src/tutorial/external_rest_apis/security.py [ln:13-65] !}
+{! docs_src/user_guide/external_rest_apis/security.py [ln:13-65] !}
 ```
 
 This code snippet sets up a simple weather agent that calls an external weather API with security, using the registered functions generated from the `openapi.json` URL.
@@ -45,15 +45,15 @@ This code snippet sets up a simple weather agent that calls an external weather
 Next, define your FastAgency application.
 
 ```python
-{! docs_src/tutorial/external_rest_apis/security.py [ln:68] !}
+{! docs_src/user_guide/external_rest_apis/security.py [ln:68] !}
 ```
 
 ## Run Application
 
 You can run this chapter's FastAgency application using the following command::
 
 ```console
-fastagency run docs/docs_src/tutorial/external_rest_apis/security.py
+fastagency run docs/docs_src/user_guide/external_rest_apis/security.py
 ```
 
 ## Output