diff --git a/docs/framework/ai-module.mdx b/docs/framework/ai-module.mdx index 3a74f48d3..b156bb340 100644 --- a/docs/framework/ai-module.mdx +++ b/docs/framework/ai-module.mdx @@ -20,7 +20,7 @@ You can manage your environment variables using methods that best suit your setu Furthermore, when deploying an application with `writer deploy`, the `WRITER_API_KEY` environment variable is automatically configured with the API key specified during the deployment process. -## Conversation class +## Chat completion with the Conversation class The `Conversation` class manages LLM communications within a chat framework, storing the conversation history and handling the interactions. ```python @@ -74,13 +74,7 @@ conversation += {"role": "user", "content": "Can you break down the assets secti conversation.add(role="user", content="How should I interpret the equity section?") ``` -Addition to `Conversation` only works against `dict` objects that contain `"role"` and `"content"` items. Providing a `"chunk": True` flag into the object will merge it against the last message - appending `"content"` and replacing other values. - ### Completing and streaming Conversations - -When utilizing the `stream_complete` feature, the initial chunk of data returned by the stream is not specifically marked as a "chunk." This is intentional, allowing for the seamless integration of this first piece into the conversation history when appended using the + operator. - - The `complete` and `stream_complete` methods facilitate interaction with the LLM based on the accumulated messages and configuration. These methods execute calls to generate responses and return them in the form of a message object, but do not alter the conversation's `messages` list, allowing you to validate or modify the output before deciding to add it to the history. @@ -105,8 +99,8 @@ Instance-wide configuration parameters can be complemented or overriden on indiv response = conversation.complete(config={'max_tokens': 200, 'temperature': 0.5}) ``` -## Text completions without a conversation state -These `complete` and `stream_complete` methods are designed for one-off text completions without the need to manage a conversation state. They return the model's response as a string. Each function accepts a `config` dictionary allowing call-specific configurations. +## Text generation without a conversation state +These `complete` and `stream_complete` methods are designed for one-off text generation without the need to manage a conversation state. They return the model's response as a string. Each function accepts a `config` dictionary allowing call-specific configurations. ```python complete diff --git a/docs/framework/backend-driven-ui.mdx b/docs/framework/backend-driven-ui.mdx index c058baa2c..a1d94328b 100644 --- a/docs/framework/backend-driven-ui.mdx +++ b/docs/framework/backend-driven-ui.mdx @@ -147,7 +147,7 @@ In addition to `content`, a set of fields which is specific to the component typ - **`position: int`**: Determines the display order of the component in relation to its siblings. Position `0` means that the component is the first child of its parent. - Position `-2` is used for components – such as [sidebars](https://dev.writer.com/components/sidebar) – that have a specific reserved position not related to their siblings. + Position `-2` is used for components – such as [sidebars](https://dev.writer.com/components/sidebar) – that have a specific reserved position not related to their siblings. ```python ui.Text( {"text": "Hello Parent, I'm your first child!"}, @@ -170,7 +170,7 @@ In addition to `content`, a set of fields which is specific to the component typ ui.Text({"text": "My visibility depends on the @{my_var}!"}, visible="my_var") ``` -- **`handlers: dict[str, callable]`**: Attaches [event handlers](https://dev.writer.com/framework/event-handlersl) to the component. Each dictionary key represents an event, and its value is the corresponding handler.: +- **`handlers: dict[str, callable]`**: Attaches [event handlers](https://dev.writer.com/framework/event-handlers) to the component. Each dictionary key represents an event, and its value is the corresponding handler.: ```python def increment(state): state["counter"] += 1 diff --git a/docs/framework/cloud-deploy.mdx b/docs/framework/cloud-deploy.mdx index b9452ba91..c4825d14a 100644 --- a/docs/framework/cloud-deploy.mdx +++ b/docs/framework/cloud-deploy.mdx @@ -1,28 +1,15 @@ --- -title: "Cloud Deployment Using CLI" +title: "Deploy to Writer Cloud" --- -## Table of Contents - -2. [Basic Usage](#basic-usage) -3. [Common Options](#common-options) -4. [Commands](#commands) - - [Deploy](#writer-cloud-deploy) - - [Undeploy](#writer-cloud-undeploy) - - [Logs](#writer-cloud-logs) -5. [Environment Variables](#environment-variables) -6. [API Key](#api-key) -7. [Deployment Process](#deployment-process) -8. [Example Workflow](#example-workflow) - -## Basic Usage +## Basic usage The `writer cloud` command group includes the following commands: - `deploy` - `undeploy` - `logs` -## Common Options +## Common options These options are common across multiple commands: - `--api-key`: The Writer API key used for authentication. If not provided, you will be prompted to enter it. @@ -30,138 +17,157 @@ These options are common across multiple commands: ## Commands -### `writer cloud deploy` - -Deploys an app from the specified path to the Writer cloud. - -**Usage:** -``` -writer cloud deploy [OPTIONS] PATH -``` - -**Arguments:** -- `PATH`: The path to the folder containing the app to deploy. - -**Options:** -- `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. -- `--env, -e`: Environment variables to set in the deployed app. Use the format `VAR=value`. Multiple environment variables can be specified by repeating the `--env` option. -- `--verbose, -v`: Enable verbose output. - -**Example:** -``` -writer cloud deploy hello --env VAR1=value1 --env VAR2=value2 -``` - -**Description:** -- Deploys the app located in the `PATH` folder. -- Creates a deployment package, ignoring `.git` directories, `Dockerfile`s and all files specified in `.gitignore` file. -- Uploads the package to the deployment server. -- The deployed app will have access to specified environment variables. -- By default, the `WRITER_API_KEY` environment variable will be added to enable AI features. - -**Output Example** - -``` -Creating deployment package from path: /path/to/your/app -[WARNING] Dockerfile found in project root. This will be ignored in the deployment package. -Packing file: pyproject.toml -Packing file: README.md -... -Uploading package to deployment server -Package uploaded. Building... -... -Deployment successful -URL: https://your_app_url -``` - -### `writer cloud undeploy` - -Stops the deployed app and makes it unavailable. - -**Usage:** -``` -writer cloud undeploy [OPTIONS] -``` - -**Options:** -- `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. -- `--verbose, -v`: Enable verbose output. - -**Example:** -``` -writer cloud undeploy -``` - -**Description:** -- Stops and removes the deployed app from the Writer cloud. - -### `writer cloud logs` - -Fetches logs from the deployed app. - -**Usage:** -``` -writer cloud logs [OPTIONS] -``` - -**Options:** -- `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. -- `--verbose, -v`: Enable verbose output. - -**Example:** -``` -writer cloud logs -``` - -**Description:** -- Continuously fetches and displays logs from the deployed app. -- Logs are ordered by date and time. - -**Output Example** - -``` -2024-06-11 09:27:02.190646+00:00 [INFO] Starting container entrypoint... -2024-06-11 09:27:03.798148+00:00 [INFO] BuildService - Downloading build files... -... -``` - -## Environment Variables + + + Deploys an app from the specified path to the Writer cloud. + + **Usage:** + ``` + writer cloud deploy [OPTIONS] PATH + ``` + + **Arguments:** + - `PATH`: The path to the folder containing the app to deploy. + + **Options:** + - `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. + - `--env, -e`: Environment variables to set in the deployed app. Use the format `VAR=value`. Multiple environment variables can be specified by repeating the `--env` option. + - `--verbose, -v`: Enable verbose output. + + **Example:** + ``` + writer cloud deploy hello --env VAR1=value1 --env VAR2=value2 + ``` + + **Description:** + - Deploys the app located in the `PATH` folder. + - Creates a deployment package, ignoring `.git` directories, `Dockerfile`s and all files specified in `.gitignore` file. + - Uploads the package to the deployment server. + - The deployed app will have access to specified environment variables. + - By default, the `WRITER_API_KEY` environment variable will be added to enable AI features. + + **Output Example** + + ``` + Creating deployment package from path: /path/to/your/app + [WARNING] Dockerfile found in project root. This will be ignored in the deployment package. + Packing file: pyproject.toml + Packing file: README.md + ... + Uploading package to deployment server + Package uploaded. Building... + ... + Deployment successful + URL: https://your_app_url + ``` + + + + Stops the deployed app and makes it unavailable. + + **Usage:** + ``` + writer cloud undeploy [OPTIONS] + ``` + + **Options:** + - `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. + - `--verbose, -v`: Enable verbose output. + + **Example:** + ``` + writer cloud undeploy + ``` + + **Description:** + - Stops and removes the deployed app from the Writer cloud. + + + + Fetches logs from the deployed app. + + **Usage:** + ``` + writer cloud logs [OPTIONS] + ``` + + **Options:** + - `--api-key`: Writer API key for authentication. If not provided, you will be prompted to enter it. + - `--verbose, -v`: Enable verbose output. + + **Example:** + ``` + writer cloud logs + ``` + + **Description:** + - Continuously fetches and displays logs from the deployed app. + - Logs are ordered by date and time. + + **Output Example** + + ``` + 2024-06-11 09:27:02.190646+00:00 [INFO] Starting container entrypoint... + 2024-06-11 09:27:03.798148+00:00 [INFO] BuildService - Downloading build files... + ... + ``` + + + +## Environment variables When deploying an app, you can specify environment variables that will be available to the app during runtime. Use the `--env` option to pass these variables. -**Example:** ``` writer cloud deploy hello --env DB_HOST=db.example.com --env DB_PORT=5432 ``` In this example, `DB_HOST` and `DB_PORT` will be available to the app as environment variables. -## API Key +## API key The `WRITER_API_KEY` is crucial for deploying and managing apps. It is used for authenticating requests to the Writer cloud. If not provided as an option, the CLI will prompt you to enter it. The `WRITER_API_KEY` will also be added to the deployed app's environment to enable AI features of the Writer framework. -## Deployment Process - -1. **Package Creation:** The CLI packages the app, excluding certain files (e.g., Dockerfile, `service_entrypoint.py`). -2. **Upload Package:** The package is uploaded to the Writer deployment server. -3. **Build and Deploy:** The server builds and deploys the app, making it accessible via a URL. -4. **Environment Variables:** Specified environment variables are set, and `WRITER_API_KEY` is added by default. - -## Example Workflow - -1. **Deploying an App:** - ``` - writer cloud deploy /path/to/app --env DB_HOST=db.example.com --env DB_PORT=5432 - ``` - -2. **Fetching Logs:** - ``` - writer cloud logs - ``` - -3. **Undeploying an App:** - ``` - writer cloud undeploy - ``` +## Deployment process + + + + The CLI packages the app, excluding certain files (e.g., Dockerfile, `service_entrypoint.py`). + + + + The package is uploaded to the Writer deployment server. + + + + The server builds and deploys the app, making it accessible via a URL. + + + + Specified environment variables are set, and `WRITER_API_KEY` is added by default. + + + +## Example workflow + + + + ```bash + writer cloud deploy /path/to/app --env DB_HOST=db.example.com --env DB_PORT=5432 + ``` + + + + ```bash + writer cloud logs + ``` + + + + ```bash + writer cloud undeploy + ``` + + By following this documentation, you should be able to effectively deploy and manage your Writer apps using the Writer Framework CLI. diff --git a/docs/framework/custom-server.mdx b/docs/framework/custom-server.mdx index 6129a62dd..a912d971b 100644 --- a/docs/framework/custom-server.mdx +++ b/docs/framework/custom-server.mdx @@ -29,7 +29,7 @@ def hello(): return "1" ``` -Use `server_setup.py` in `edit` mode. If you want to use in `edit` mode, you can launch `writer edit --enable-server-setup `. +`server_setup.py` is disabled by default on edit mode. If you want to use in `edit` mode, you can launch `writer edit --enable-server-setup `. ## Implement custom server diff --git a/docs/framework/deploy-with-docker.mdx b/docs/framework/deploy-with-docker.mdx index 8cdd92b7a..01358def5 100644 --- a/docs/framework/deploy-with-docker.mdx +++ b/docs/framework/deploy-with-docker.mdx @@ -47,7 +47,7 @@ If you're a Docker expert, feel free to work on your own `Dockerfile`. Framework To build the image, use `docker build . -t ` followed by an image tag, which you're free to choose and will locally identify your image. ```sh -docker build . -t my_writer_app +docker build . -t my_framework_app ``` @@ -76,7 +76,7 @@ docker push my_user/my_writer_app:latest If your image is public, anyone can now run the following command and start the app. It's important to bind the port to a port in the host machine. The command below binds port 8080 in the Docker image to port 8080 in the host. ```sh -docker run -p 8080:8080 my_user/my_writer_app +docker run -p 8080:8080 my_user/my_framework_app ``` Go on your browser to [http://localhost:8080](http://localhost:8080) to check everything is working as expected. diff --git a/docs/framework/frontend-scripts.mdx b/docs/framework/frontend-scripts.mdx index 7a6002a31..91ac3525f 100644 --- a/docs/framework/frontend-scripts.mdx +++ b/docs/framework/frontend-scripts.mdx @@ -90,7 +90,6 @@ initial_state.import_script("lodash", "https://cdnjs.cloudflare.com/ajax/libs/lo Effectively using Framework's core can be challenging and will likely entail reading its [source code](https://github.com/writer/writer-framework/blob/master/ui/src/core/index.ts). Furthermore, it's considered an internal capability rather than a public API, so it may unexpectedly change between releases. - You can access Framework's front-end core via `globalThis.core`, unlocking all sorts of functionality. Notably, you can use `getUserState()` to get values from state. ```js diff --git a/docs/framework/images/429.png b/docs/framework/images/429.png new file mode 100644 index 000000000..9f95669d1 Binary files /dev/null and b/docs/framework/images/429.png differ diff --git a/docs/framework/quickstart.mdx b/docs/framework/quickstart.mdx index 4ff4193ed..d309e2ec6 100644 --- a/docs/framework/quickstart.mdx +++ b/docs/framework/quickstart.mdx @@ -83,8 +83,8 @@ If you need to run Framework as a module, you can use the `writer.command_line` python -m writer.command_line run my_app ``` -## Deploying on Writer cloud -Writer provides a quick and fast way to deploy your apps via the Writer cloud. +## Deploying to Writer cloud +Writer provides a quick and fast way to deploy your apps via the [Writer cloud](/framework/cloud-deploy). ```sh writer deploy diff --git a/docs/mint.json b/docs/mint.json index 06d072fa3..00ef24ca7 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -31,7 +31,8 @@ "pages": [ "framework/introduction", "framework/quickstart", - "framework/ai-module" + "framework/ai-module", + "framework/cloud-deploy" ] }, {