From c683b812bc48e1d5f304bc662493e463910dc5df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eric=20Dub=C3=A9?= Date: Mon, 24 Mar 2025 17:52:00 -0400 Subject: [PATCH] doc: Improve PuterAI module documentation structure (#1216) * docs: improve PuterAI module documentation structure - Update docmeta.md to describe top-level doc structure\n- Create README.md for PuterAI module documentation\n- Move requests.md content to api_examples.md\n- Add ai_usage_testing.md in contributors directory\n\nCloses #1215\n\nai: true * docs: remove original requests.md after content migration Content has been migrated to api_examples.md with improved organization and structure.\n\nai: true --- doc/docmeta.md | 14 ++++++ src/backend/src/modules/puterai/doc/README.md | 24 ++++++++++ .../doc/{requests.md => api_examples.md} | 31 +++++++++++-- .../doc/contributors/ai_usage_testing.md | 44 +++++++++++++++++++ 4 files changed, 109 insertions(+), 4 deletions(-) create mode 100644 src/backend/src/modules/puterai/doc/README.md rename src/backend/src/modules/puterai/doc/{requests.md => api_examples.md} (91%) create mode 100644 src/backend/src/modules/puterai/doc/contributors/ai_usage_testing.md diff --git a/doc/docmeta.md b/doc/docmeta.md index d23def46..495bfbc7 100644 --- a/doc/docmeta.md +++ b/doc/docmeta.md @@ -18,6 +18,20 @@ From [./contributors/structure.md](./contributors/structure.md): > the index file for the documentation. All documentation under a `doc` > directory should be accessible via a path of links starting from `README.md`. +### Documentation Structure + +The top-level `doc` directory contains the following subdirectories: + +- `api/` - API documentation for Puter services +- `contributors/` - Documentation for contributors to the Puter project +- `devmeta/` - Meta documentation for developers +- `i18n/` - Internationalization documentation +- `planning/` - Project planning documentation +- `self-hosters/` - Documentation for self-hosting Puter +- `uncategorized/` - Miscellaneous documentation + +Module-specific documentation follows a similar structure, with each module having its own `doc` directory. For contributor-specific documentation within a module, use a `contributors` subdirectory within the module's `doc` directory. + ## Docs Styleguide ### "is" and "is not" diff --git a/src/backend/src/modules/puterai/doc/README.md b/src/backend/src/modules/puterai/doc/README.md new file mode 100644 index 00000000..c18f2f20 --- /dev/null +++ b/src/backend/src/modules/puterai/doc/README.md @@ -0,0 +1,24 @@ +# PuterAI Documentation + +This directory contains documentation for the PuterAI module, which provides AI services integration for the Puter platform. + +## Contents + +### General Documentation + +- [Configuration](./config.md) - General configuration for PuterAI +- [AI Services Configuration](./ai-services-config.md) - Configuration for specific AI services + +### API Examples + +- [API Request Examples](./api_examples.md) - Examples of API requests to PuterAI services + +### For Contributors + +Documentation for contributors can be found in the [contributors](./contributors/) directory: + +- [AI Usage Testing](./contributors/ai_usage_testing.md) - Guide for testing and reporting AI usage + +## Related Documentation + +For more information about the overall Puter documentation structure, see the [documentation meta guide](../../../../../doc/docmeta.md). \ No newline at end of file diff --git a/src/backend/src/modules/puterai/doc/requests.md b/src/backend/src/modules/puterai/doc/api_examples.md similarity index 91% rename from src/backend/src/modules/puterai/doc/requests.md rename to src/backend/src/modules/puterai/doc/api_examples.md index 56063285..c10ae070 100644 --- a/src/backend/src/modules/puterai/doc/requests.md +++ b/src/backend/src/modules/puterai/doc/api_examples.md @@ -1,3 +1,11 @@ +# PuterAI API Request Examples + +This document provides examples of API requests to the PuterAI services. These examples demonstrate how to interact with various AI capabilities of the Puter platform. + +## OCR (Optical Character Recognition) + +Example of using AWS Textract for OCR: + ```javascript await (await fetch("http://api.puter.localhost:4100/drivers/call", { "headers": { @@ -16,6 +24,10 @@ await (await fetch("http://api.puter.localhost:4100/drivers/call", { })).json(); ``` +## Chat Completion + +Example of using OpenAI for chat completion: + ```javascript await (await fetch("http://api.puter.localhost:4100/drivers/call", { "headers": { @@ -43,6 +55,10 @@ await (await fetch("http://api.puter.localhost:4100/drivers/call", { })).json(); ``` +## Image Generation + +Example of using OpenAI for image generation: + ```javascript URL.createObjectURL(await (await fetch("http://api.puter.localhost:4100/drivers/call", { "headers": { @@ -61,7 +77,9 @@ URL.createObjectURL(await (await fetch("http://api.puter.localhost:4100/drivers/ })).blob()); ``` -### Tool Use +## Tool Use + +Example of using tool functions with AI: ```javascript await puter.ai.chat('What\'s the weather like in Vancouver?', { @@ -89,6 +107,8 @@ await puter.ai.chat('What\'s the weather like in Vancouver?', { }) ``` +Example with tool response: + ```javascript await puter.ai.chat([ { content: `What's the weather like in Vancouver?` }, @@ -137,7 +157,9 @@ await puter.ai.chat([ }) ``` -### Claude Tool Use with Streaming +## Claude Tool Use with Streaming + +Example of using Claude with streaming: ```javascript gen = await puter.ai.chat('What\'s the weather like in Vancouver?', { @@ -182,7 +204,8 @@ Last item in the stream looks like this: } ``` -Respond like this: +Responding to tool use: + ```javascript gen = await puter.ai.chat([ { role: 'user', content: `What's the weather like in Vancouver?` }, @@ -229,4 +252,4 @@ gen = await puter.ai.chat([ ] }) for await ( const item of gen ) { console.log(item) } -``` +``` \ No newline at end of file diff --git a/src/backend/src/modules/puterai/doc/contributors/ai_usage_testing.md b/src/backend/src/modules/puterai/doc/contributors/ai_usage_testing.md new file mode 100644 index 00000000..4abb0261 --- /dev/null +++ b/src/backend/src/modules/puterai/doc/contributors/ai_usage_testing.md @@ -0,0 +1,44 @@ +# AI Usage Testing and Reporting + +This document provides guidance for testing and reporting AI usage in the Puter platform. + +## Manual Testing for AI Usage Reporting + +When testing AI usage reporting and tracking, it's sometimes necessary to manipulate the timestamps of usage records for testing purposes. This can be useful for validating reporting over specific time periods or for troubleshooting issues with usage limits. + +### Backdating AI Usage Records + +To move all records in the `ai_usage` table back by one week, you can use the following SQL query for SQLite: + +```sql +UPDATE ai_usage +SET created_at = datetime(created_at, '-7 days'); +``` + +This query updates the `created_at` timestamp for all records in the table, shifting them back by 7 days. + +### Common Testing Scenarios + +1. **Testing daily usage limits**: Backdate some records to earlier in the current day to test daily usage limit calculations. + +2. **Testing monthly reports**: Distribute usage records across a month to validate monthly usage reports. + +3. **Testing billing cycles**: Adjust record timestamps to span multiple billing cycles to ensure proper attribution. + +## Usage Table Structure + +The `ai_usage` table tracks all AI service usage with the following key fields: + +- `user_id`: The user who made the request +- `service_name`: The AI service that was used (e.g., 'openai', 'claude') +- `model_name`: The specific model that was used +- `cost`: Expected cost in microcents (ยตยข) +- `value_uint_1`: Input tokens +- `value_uint_2`: Output tokens +- `created_at`: When the usage occurred + +For the complete table definition, see the [ai_usage table schema](../../../../services/database/sqlite_setup/0033_ai-usage.sql). + +## Resetting Test Data + +After testing, you may want to reset the timestamps to their original values. This is only possible if you've kept a backup of the original data or timestamps. \ No newline at end of file