Add docs

.github/workflows/lint-md.yml

@@ -0,0 +1,47 @@
+name: Lint Markdown
+
+on:
+  push:
+    branches-ignore:
+      - main
+    paths:
+      - "**/*.md"
+  pull_request:
+    paths:
+      - "**/*.md"
+
+jobs:
+  setup-node-modules:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm install
+
+  lint-md:
+    name: Linting Markdown
+    runs-on: ubuntu-latest
+    needs: setup-node-modulessteps:
+      - name: Git Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Run Markdown Linting
+        run: npm run lint-md

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+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 [email protected]:<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
+    node ./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
+    node ./dist/cli/start.js -c <path to test app platformatic.json>
+    ```
+
+## Important Notes
+
+* AI Warp needs to be rebuilt for any code change to take affect in your test
+app. This includes schema changes.
+
+## Noteable Commands
+
+* `npm run build` - Build the app.
+* `npm run build:config` - Rebuild the config. **Make sure to build first.**
+* `npm run lint:fix` - Fix all formatting issues and console log any linting
+issues that need to be fixed in code.
+* `npm run test` - Run Unit, E2E, and Type tests.
+
+## Additional Resources
+
+* [Use Stackables to build Platformatic applications](https://docs.platformatic.dev/docs/guides/applications-with-stackables)

README.md

@@ -1,2 +1,37 @@
 # ai-warp
-Platformatic Stackable to interact with AI services
+
+Platformatic Stackable to interact with AI services.
+
+## Usage
+
+To get started using AI Warp, all you need to do is three steps:
+
+ 1. Generate an AI Warp app. As of now, this can only be done through this repository.
+
+    ```bash
+    npm install
+    npm run build
+    node ./dist/cli/create.js
+    ```
+
+ 2. Configure the app's Platformatic config file. By default, this is located
+ at `ai-warp-app/platformatic.json`. For a full list of available configuration
+ options, see [docs/config.md](./docs/config.md).
+
+ 3. Start the app!
+
+    ```bash
+    node ./dist/cli/start.js
+    ```
+
+For more information, see [CONTRIBUTING.md](./CONTRIBUTING.md) and [Documentation](#documentation).
+
+## Documentation
+
+* [REST API](./docs/rest-api.md)
+* [Config](./docs/config.md)
+  * [Authentication](./docs/auth.md)
+  * [Rate Limiting](./docs/rate-limiting.md)
+* [Plugin API](./docs/plugin-api.md)
+* [Contributing](./CONTRIBUTING.md)
+  * [Adding a AI Provider](./docs/add-ai-provider.md)

docs/add-ai-provider.md

@@ -0,0 +1,38 @@
+# Adding a new AI Provider
+Documentation on how to support a new AI provider.
+
+## Steps
+
+### 1. Setup your developer environment
+
+See [Dev Setup](./dev-setup.md).
+
+### 2. 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!
+
+### 3. 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 Node.js-builtin `ReadableStream` that outputs the expected format defined in the [REST API docs](./rest-api.md).
+
+### 4. 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()`.
+
+### 5. Add the provider to the generator code
+
+See [lib/generator.ts](https://github.com/platformatic/ai-warp/blob/b9cddeedf8609d1c2ce3efcfdd84a739150a1e91/lib/generator.ts#L64-L88).
+
+### 6. 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).
+
+### 7. 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).
+
+### 8. 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).

docs/auth.md

@@ -0,0 +1,57 @@
+# Authentication
+
+Documentation on how to configure and use AI Warp's authentication.
+
+## Configuring
+
+Configuring authentication can be done via your Platformatic config file under the `auth` object. E.g.
+
+```json
+// platformatic.json
+{
+  "auth": {
+    // ...
+  }
+}
+```
+
+We utilize [fastify-user](https://github.com/platformatic/fastify-user) to do authentication, so you
+can pass in any configuration options for it in the `auth` object.
+
+AI Warp-specific options:
+
+ * `required` (`boolean`) - If true, any unauthenticated users will receive a 401 status code and body.
+
+### Example
+
+This makes authentication required and accepts JWTs signed with the secret `abc123`:
+
+```json
+{
+  "auth": {
+    "required": true,
+    "jwt": {
+      "secret": "abc123"
+    }
+  }
+}
+```
+
+## Using
+
+By default, [fastify-user](https://github.com/platformatic/fastify-user) reads the `Authorization` header.
+
+You can configure AI Warp to read the token from cookies in your Platformatic config:
+
+```json
+{
+  "auth": {
+    "jwt": {
+      "cookie": {
+        "cookieName": "token",
+        "signed": false
+      }
+    }
+  }
+}
+```

docs/config.md

@@ -0,0 +1,60 @@
+# AI Warp Configuration
+
+Documentation on AI Warp's configuration options.
+
+## How to Configure AI Warp
+
+AI Warp can be configured in your applications's Platformatic config.
+
+## Config Options
+
+### `aiProvider`
+
+ * `object`
+
+> \[!NOTE]\
+> This is a required configuration option.
+
+This configuration option tells AI Warp what AI provider to use.
+
+```json
+{
+  "aiProvider": {
+    "openai": {
+      "model": "gpt-3.5-turbo",
+      "apiKey": "{PLT_OPENAI_API_KEY}" // reads from environment variables
+    }
+  }
+}
+```
+
+### `promptDecorators`
+
+ * `object`
+
+Tells AI Warp to append a prefix and/or a suffix to a prompt. 
+
+<details>
+    <summary>Example usage</summary>
+
+```json
+{
+  "promptDecorators": {
+    "prefix": "Hello AI! Your prompt is as follows: \n",
+    "suffix": "\nThank you!"
+  }
+}
+```
+</details>
+
+### `auth`
+
+ * `object`
+
+Configure authentication for AI Warp. See [auth.md](./auth.md) for more information.
+
+### `rateLimiting`
+
+ * `object`
+
+Configure rate limiting for AI Warp. See [rate-limiting.md](./rate-limiting.md) for more information.