cargdev/apiAi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with comprehensive documentation

Browse Source
This commit is contained in:
Carlos
2025-05-24 16:39:29 -04:00
parent 3c0956b518
commit ee1796ee47
1 changed files with 153 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@ -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 <repository-url>
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": "<file>path/to/file.js\nconst x = 1;</file><file>path/to/other.js\nconst y = 2;</file>",
"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
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