diff --git a/README.md b/README.md index 6558e7f..d0ada5f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AI API Server -A Node.js/Express.js backend server that proxies requests to Ollama and provides logging and monitoring capabilities. +A Node.js/Express.js backend server that proxies requests to Ollama and provides logging, monitoring, and cost analysis capabilities. ## Features @@ -8,6 +8,8 @@ A Node.js/Express.js backend server that proxies requests to Ollama and provides - Supports both chat and generate endpoints - Streaming responses for real-time AI interactions - PostgreSQL database for logging prompts and errors +- Token tracking and cost analysis per model +- Time-based expense summaries (daily/monthly/yearly) - API key authentication - Modular, maintainable codebase @@ -16,14 +18,21 @@ A Node.js/Express.js backend server that proxies requests to Ollama and provides - Node.js 14+ and npm - PostgreSQL 12+ - Ollama running locally (http://localhost:11434) +- Git for version control ## Setup -1. Clone the repository +1. Clone the repository: + ```bash + git clone + cd apiAi + ``` + 2. Install dependencies: ```bash npm install ``` + 3. Create a `.env` file with the following variables: ``` PORT=5000 @@ -35,16 +44,23 @@ A Node.js/Express.js backend server that proxies requests to Ollama and provides DB_USER=your_db_user DB_PASSWORD=your_db_password ``` + 4. Create the database: ```bash createdb ai_db ``` + 5. Run the database migrations: ```bash psql -d ai_db -f src/database/schema.sql ``` + 6. Start the server: ```bash + # Development mode with auto-reload + npm run dev + + # Production mode npm start ``` @@ -65,52 +81,169 @@ A Node.js/Express.js backend server that proxies requests to Ollama and provides "stream": true } ``` + - Multi-file support: + ```json + { + "model": "codellama:7b", + "content": "path/to/file.js\nconst x = 1;path/to/other.js\nconst y = 2;", + "stream": true + } + ``` -### Logs +### Logs and Statistics -- `GET /api/errors/prompts` - - Returns latest 100 prompts +- `GET /api/logs/prompts` + - Returns latest prompts with token usage and cost data + - Query parameters: + - `limit` (default: 100) + - `model` (optional, filter by model) + - Requires API key + +- `GET /api/logs/errors` + - Returns latest error logs - Query parameter: `limit` (default: 100) - Requires API key -- `GET /api/errors/logs` - - Returns latest 100 error logs - - Query parameter: `limit` (default: 100) - - Requires API key +- `GET /api/stats/expenses` + - Returns expense summaries per model + - Query parameters: + - `granularity` (optional): 'daily', 'monthly', 'yearly' (default: 'monthly') + - `start_date` (optional): YYYY-MM-DD format + - `end_date` (optional): YYYY-MM-DD format + - Example response: + ```json + { + "success": true, + "data": { + "granularity": "monthly", + "periods": [ + { + "time_period": "2024-03", + "models": [ + { + "model": "codellama:7b", + "total_requests": 50, + "total_tokens": 25000, + "total_cost": "0.050000", + "avg_cost_per_request": "0.001000" + } + ], + "totals": { + "total_requests": 50, + "total_tokens": 25000, + "total_cost": "0.050000" + } + } + ] + } + } + ``` ## Project Structure ``` src/ +├── api/ # API layer (controllers, network handlers) ├── config/ # Configuration files -├── controllers/ # Request handlers ├── database/ # Database schema and migrations ├── middleware/ # Express middleware ├── models/ # Database models -├── network/ # External service communication ├── routes/ # API routes -└── server.js # Application entry point +├── utils/ # Utility functions +└── app.js # Application entry point ``` +## Development Workflow + +1. Create a new branch for your feature/fix: + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/issue-description + ``` + +2. Make your changes following the code style: + - Use ES6+ syntax + - Follow the existing modular structure + - Add JSDoc comments for public functions + - Write clear commit messages + +3. Test your changes: + ```bash + # Run the server in development mode + npm run dev + + # Test the endpoints + curl -X POST http://localhost:5000/api/generate \ + -H "api-key: your_api_key" \ + -H "Content-Type: application/json" \ + -d '{"model":"codellama:7b","messages":[{"role":"user","content":"test"}]}' + ``` + +4. Commit your changes: + ```bash + git add . + git commit -m "feat: add new feature" + # or + git commit -m "fix: resolve issue" + ``` + +5. Push your branch: + ```bash + git push origin feature/your-feature-name + ``` + +6. Create a Pull Request: + - Go to the repository's web interface + - Click "New Pull Request" + - Select your branch + - Fill in the PR template: + - Description of changes + - Related issues + - Testing performed + - Screenshots (if applicable) + +## Code Style Guidelines + +- Use ES6+ features (async/await, destructuring, etc.) +- Follow the existing modular structure +- Keep functions pure and focused +- Use descriptive variable names +- Add JSDoc comments for public functions +- Handle errors appropriately +- Write clear commit messages + ## Error Handling - All errors are logged to the database - API errors return appropriate HTTP status codes - Streaming errors are handled gracefully +- Use the centralized error handler ## Security - API key authentication required for all endpoints - Environment variables for sensitive data - Input validation and sanitization -- Secure headers with Helmet (TODO) - -## Development - -- Use `npm run dev` for development with auto-reload -- Use `npm test` to run tests (TODO) -- Follow the existing code style and structure +- Secure headers with Helmet +- Rate limiting (TODO) +- CORS configuration (TODO) ## License -MIT \ No newline at end of file +MIT + +## Contributing + +1. Fork the repository +2. Create your feature branch +3. Commit your changes +4. Push to the branch +5. Create a Pull Request + +Please ensure your PR: +- Follows the code style +- Includes tests (if applicable) +- Updates documentation +- Has a clear description +- References any related issues \ No newline at end of file