Add examples, improve docs, refactor cache/cacheKey (#5)

Co-authored-by: Riley Tomasek <[email protected]>

.env.example

@@ -7,5 +7,9 @@
 
 OPENAI_API_KEY=
 
-# Optional; only needed if using a hybrid datastore with sparse Splade vectors.
+# Most examples will work with a free-tier index, but you'll need a paid hybrid-compatible index to run the chatbot example
+PINECONE_API_KEY=
+PINECONE_BASE_URL=
+
+# Optional; only needed if using a hybrid datastore
 #SPLADE_SERVICE_URL=

.github/workflows/main.yml

@@ -19,6 +19,30 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm install
-      - run: npm test
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        id: pnpm-install
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v3
+        name: Setup pnpm cache
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run test
+        run: pnpm run test

.npmrc

@@ -0,0 +1 @@
+enable-pre-post-scripts=true

contributing.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Suggestions and pull requests are very welcome. 😊
+
+## Development
+
+To develop the project locally, you'll need `node >= 18` and `pnpm >= 8`.
+
+```bash
+git clone https://github.com/dexaai/dexter
+cd dexter
+pnpm i
+```
+
+You can now run the `tsc` dev server to automatically recompile the project whenever you make changes:
+
+```bash
+pnpm dev
+```
+
+## Testing
+
+You can run the test suite via:
+
+```bash
+pnpm test
+```
+
+Or just the [Vitest](https://vitest.dev) unit tests via:
+
+```bash
+pnpm test:unit
+```
+
+## Examples
+
+To run the included examples, clone this repo, run `pnpm install`, set up your `.env` file, and then run an example file using `tsx`.
+
+For example:
+
+```bash
+npx tsx examples/basic.ts
+```
+
+## Docs
+
+The `./docs/pages/docs` directory is autogenerated via [typedoc](https://typedoc.org) and [typedoc-plugin-markdown](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/next/packages/typedoc-plugin-markdown).
+
+To rebuild the docs, run:
+
+```bash
+pnpm run docs
+```
+
+Please don't run this command when submitting PRs to keep them uncluttered, unless you're making changes to the docs themselves.
+
+The docs folder is a normal [Next.js](https://nextjs.org) pages app built using [Nextra](https://nextra.site/).
+
+You can run the docs dev server to preview your changes via:
+
+```bash
+cd docs
+pnpm dev
+```
+
+The docs are automatically deployed to [Vercel](https://vercel.com).

docs/bin/transform-docs.ts

@@ -54,7 +54,7 @@ async function main() {
   {
     // top-level nextra _meta.json file
     const docsMeta = {
-      exports: 'Contents',
+      exports: 'API Reference',
       namespaces: 'Namespaces',
       classes: 'Classes',
       interfaces: 'Interfaces',