Skip to content

Commit

Permalink
Merge pull request #546 from anant-writer/dev
Browse files Browse the repository at this point in the history 
Improving quality of Framework pages and adding mintlify components to Cloud deploy page
  • Loading branch information
@anant-writer
anant-writer authored Aug 30, 2024
2 parents 45c0ba9 + aa6edd4 commit 9191a57
Show file tree
Hide file tree
Showing 9 changed files with 155 additions and 155 deletions.
12 changes: 3 additions & 9 deletions docs/framework/ai-module.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
<Tip>
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.
</Tip>

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.

<CodeGroup>
Expand All @@ -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.

<CodeGroup>
```python complete
Expand Down
4 changes: 2 additions & 2 deletions docs/framework/backend-driven-ui.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ In addition to `content`, a set of fields which is specific to the component typ
</Note>
- **`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!"},
Expand All @@ -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
Expand Down
280 changes: 143 additions & 137 deletions docs/framework/cloud-deploy.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,167 +1,173 @@
---
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.
- `--verbose, -v`: Enable verbose output.

## 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
<AccordionGroup>
<Accordion title="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
```
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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...
...
```
</Accordion>
</AccordionGroup>

## 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

<Steps>
<Step title="Package Creation">
The CLI packages the app, excluding certain files (e.g., Dockerfile, `service_entrypoint.py`).
</Step>

<Step title="Upload Package">
The package is uploaded to the Writer deployment server.
</Step>

<Step title="Build and Deploy">
The server builds and deploys the app, making it accessible via a URL.
</Step>

<Step title="Environment Variables">
Specified environment variables are set, and `WRITER_API_KEY` is added by default.
</Step>
</Steps>

## Example workflow

<Steps>
<Step title="Deploying an App">
```bash
writer cloud deploy /path/to/app --env DB_HOST=db.example.com --env DB_PORT=5432
```
</Step>

<Step title="Fetching Logs">
```bash
writer cloud logs
```
</Step>

<Step title="Undeploying an App">
```bash
writer cloud undeploy
```
</Step>
</Steps>

By following this documentation, you should be able to effectively deploy and manage your Writer apps using the Writer Framework CLI.
2 changes: 1 addition & 1 deletion docs/framework/custom-server.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ def hello():
return "1"
```
<Warning>
Use `server_setup.py` in `edit` mode. If you want to use in `edit` mode, you can launch `writer edit --enable-server-setup <app>`.
`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 <app>`.
</Warning>

## Implement custom server
Expand Down
4 changes: 2 additions & 2 deletions docs/framework/deploy-with-docker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

<Warning>
Expand Down Expand Up @@ -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.
Expand Down
1 change: 0 additions & 1 deletion docs/framework/frontend-scripts.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,6 @@ initial_state.import_script("lodash", "https://cdnjs.cloudflare.com/ajax/libs/lo
<Warning>
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.
</Warning>

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
Expand Down
Binary file added docs/framework/images/429.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 9191a57

Please sign in to comment.