From 7051d6565df8015bdde0ed53d37f262aaf0dd2ca Mon Sep 17 00:00:00 2001
From: flakey5 <73616808+flakey5@users.noreply.github.com>
Date: Wed, 10 Apr 2024 21:42:58 -0700
Subject: [PATCH] Add docs

---
 docs/add-ai-provider.md | 33 ++++++++++++++++++++
 docs/api.md             | 69 +++++++++++++++++++++++++++++++++++++++++
 docs/dev-setup.md       | 47 ++++++++++++++++++++++++++++
 3 files changed, 149 insertions(+)
 create mode 100644 docs/add-ai-provider.md
 create mode 100644 docs/api.md
 create mode 100644 docs/dev-setup.md

diff --git a/docs/add-ai-provider.md b/docs/add-ai-provider.md
new file mode 100644
index 0000000..94bf3ab
--- /dev/null
+++ b/docs/add-ai-provider.md
@@ -0,0 +1,33 @@
+# Adding a new AI Provider
+Documentation on how to support a new AI provider.
+
+## Steps
+
+### Add it to the Config Schema
+The `aiProvider` property in the config schema ([lib/schema.ts](../lib/schema.ts)) needs to be updated to allow for inputting any necessary information for this AI provider (e.g. model name, api key). Don't forget to rebuild the config!
+
+### Creating the Provider class
+
+Implement the `Provider` interface ([ai-providers/provider.ts](../ai-providers/provider.ts)) in a file also under [ai-providers/](../ai-providers/) (e.g. [ai-providers/open-ai.ts](../ai-providers/open-ai.ts))
+
+Ensure that the `askStream` response returns a ReadableStream that outputs the expected format defined in the [api docs](./api.md).
+
+### Add the provider to the `build` function in the `warp` plugin
+
+See [plugins/warp.ts](https://github.com/platformatic/ai-warp/blob/b9cddeedf8609d1c2ce3efcfdd84a739150a1e91/plugins/warp.ts#L12) `build()`
+
+### Add the provider to the generator code
+
+See [lib/generator.ts](https://github.com/platformatic/ai-warp/blob/b9cddeedf8609d1c2ce3efcfdd84a739150a1e91/lib/generator.ts#L64-L88)
+
+### Unit Tests
+
+Add provider to [tests/unit/ai-providers.test.ts](https://github.com/platformatic/ai-warp/blob/b9cddeedf8609d1c2ce3efcfdd84a739150a1e91/tests/unit/ai-providers.test.ts#L11)
+
+### E2E Tests
+
+Add provider config to [tests/e2e/api.test.ts](https://github.com/platformatic/ai-warp/blob/b9cddeedf8609d1c2ce3efcfdd84a739150a1e91/tests/e2e/api.test.ts#L17-L36)
+
+### Type Tests
+
+Add the provider config to the schema tests [tests/types/schema.test-d.ts](https://github.com/platformatic/ai-warp/blob/main/tests/types/schema.test-d.ts)
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..52c9c91
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,69 @@
+# API Endpoints
+
+Documentation on AI Warp's REST API.
+
+For information on authentication, see [./auth.md](./auth.md).
+
+For information on rate limiting, see [./rate-limiting.md](./rate-limiting.md)
+
+## Endpoints
+
+### POST `/api/v1/prompt`
+
+Prompt the AI Provider and receive the full response.
+
+<details>
+    <summary>Body</summary>
+
+```json
+{ "prompt": "What's 1+1?" }
+```
+</details>
+
+<details>
+    <summary>Response</summary>
+
+```json
+{ "response": "..." }
+```
+</details>
+
+### POST `/api/v1/stream`
+
+Prompt the AI Provider and receive a streamed response. This endpoint supports [Server Side Events](https://html.spec.whatwg.org/multipage/server-sent-events.html).
+
+Event types:
+
+ * `content` - Response chunk
+ * `error` - An error has occured and the stream is closed.
+
+<details>
+    <summary>Body</summary>
+
+```json
+{ "prompt": "What's 1+1?" }
+```
+</details>
+
+<details>
+    <summary>Success response</summary>
+
+```
+event: content
+data: {"response": "..."}
+
+event: content
+data: {"response": "..."}
+```
+</details>
+
+<details>
+    <summary>Error response</summary>
+
+```
+event: error
+data: {"code":"...","message":"..."}
+```
+</details>
+
+When there is no more chunks to return or an error occurs, the stream is closed.
diff --git a/docs/dev-setup.md b/docs/dev-setup.md
new file mode 100644
index 0000000..397df6a
--- /dev/null
+++ b/docs/dev-setup.md
@@ -0,0 +1,47 @@
+# Development Setup
+
+Steps for downloading and setting up AI Warp for local development.
+
+## Steps
+
+ 1. Fork the repository.
+ 
+ 2. Clone your fork using SSH, Github CLI, or HTTPS.
+
+    ```bash
+    git clone git@github.com:<YOUR_GITHUB_USERNAME>/ai-warp.git # SSH
+    git clone https://github.com/<YOUR_GITHUB_USERNAME>/ai-warp.git # HTTPS
+    gh repo clone <YOUR_GITHUB_USERNAME>/ai-warp # GitHub CLI
+    ```
+
+ 3. Install [Node.js](https://nodejs.org/).
+
+ 4. Install dependencies.
+
+    ```bash
+    npm install
+    ```
+
+ 5. Build.
+
+    ```bash
+    npm run build
+    ```
+
+ 6. Generate the test app.
+
+    ```bash
+    ./dist/cli/create.js
+    ```
+
+ 7. Configure the test app's `platformatic.json` to your liking. By default, it is located at `ai-warp-app/platformatic.json`. **Note: this will be overwrited every time you generate the test app.**
+
+ 8. Start the test app.
+
+    ```bash
+    ./dist/cli/start.js
+    ```
+
+## Additional Resources
+
+ * [Use Stackables to build Platformatic applications](https://docs.platformatic.dev/docs/guides/applications-with-stackables)