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

@@ -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"

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).

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) }
-```
+```

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.