Add docs

.github/workflows/ci.yml

@@ -43,6 +43,25 @@ jobs:
       - name: Run Linting
         run: npm run lint
 
+  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
+
   unit-tests:
     name: Unit Tests
     runs-on: ubuntu-latest

README.md

@@ -1,2 +1,3 @@
 # ai-warp
+
 Platformatic Stackable to interact with AI services

docs/README.md

@@ -1 +1,10 @@
 # Documentation
+
+## Table of Contents
+
+ * [REST API](./rest-api.md)
+ * [Authentication](./auth.md)
+ * [Rate Limiting](./rate-limiting.md)
+ * [Plugin API](./plugin-api.md)
+ * [Dev Setup](./dev-setup.md)
+   * [Adding a AI Provider](./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/dev-setup.md

@@ -0,0 +1,58 @@
+# 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 [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.
+ * `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)