neural-nexus/readme.md

A comprehensive toolkit for AI model deployment, sharing, and marketplace integration

# 🚀 Neural Nexus Package

A modern, TypeScript-first toolkit for connecting with AI models on the Neural Nexus platform. Effortlessly deploy, manage, and share models, integrate with a marketplace, and handle authentication and payments—all with a single, powerful npm package.

---


## 📚 Table of Contents

- [API Overview](#-api-overview)
- [Installation](#-installation)
- [API Key Management & Authentication](#-api-key-management--authentication)
  - [API Key Types & Limits](#api-key-types--limits)
  - [Creating, Listing, and Revoking API Keys](#creating-listing-and-revoking-api-keys)
  - [Security Best Practices & FAQ](#security-best-practices--faq)
- [Error Handling & Troubleshooting](#-error-handling--troubleshooting)
- [Quick Start Example](#-quick-start-example)
- [API Reference](#-api-reference)
  - [Model Management](#modelmanager)
  - [Authentication](#auth)
  - [Marketplace](#marketplace)
  - [Payments](#payments)
  - [SDK Generation](#sdk-manager)
- [Real-World Usage Examples](#-real-world-usage-examples)
- [Pricing & Rate Limits](#-pricing--rate-limits)
- [Development](#-development)
- [Contributing](#-contributing)
- [License](#-license)
- [Need Help?](#-need-help)

---


## 🌐 API Overview

The Neural Nexus API allows you to integrate AI models directly into your applications. Our RESTful API endpoints provide access to model information, inference capabilities, fine-tuning, and more.

- **Base URL:** `https://api.neuralnexus.biz/v1`
- **Full API docs:** [https://www.neuralnexus.biz/api](https://www.neuralnexus.biz/api)

Ready to start building? Get your API key now and start integrating Neural Nexus models into your applications. Our pay-as-you-go pricing ensures you only pay for what you use, starting at just $0.001 per 1000 tokens.

- **Ultra-low pricing with no minimums**
- **Free tier:** 5,000 API calls per month
- **Transparent usage monitoring**

---


## 📦 Installation

```bash
npm install neural-nexus
# or
yarn add neural-nexus
```

---


## 🔑 API Key Management & Authentication

All API requests require authentication using an API key. You can generate and manage your API keys from your Neural Nexus dashboard.

### Step-by-Step Onboarding

1. **Sign up or log in** at [Neural Nexus Dashboard](https://neuralnexus.biz/dashboard)
2. **Navigate to API Keys** in your account settings
3. **Click Generate New Key** and select the key type (test, development, production, etc.)
4. **Copy your key** (it will only be shown once!)
5. **Store your key securely** (use environment variables, never commit to code)

### API Key Types & Limits

| Key Type     | Prefix | Use Case                | Monthly Quota   | Rate Limit      |
|--------------|--------|-------------------------|-----------------|-----------------|
| Test         | nxt_   | Testing during dev      | 1,000 requests  | 10 req/min      |
| Development  | nnd_   | Development environments| 5,000 requests  | 60 req/min      |
| Training     | ntr_   | Fine-tuning models      | 10,000 requests | 120 req/min     |
| Deployment   | ndp_   | UAT/pre-production      | 50,000 requests | 300 req/min     |
| Production   | npr_   | Production applications | 100,000 requests| 600 req/min     |

- **Pro Plan:** 60 req/min, 10,000 daily quota
- **Enterprise:** 600 req/min, unlimited daily quota
- **Free Tier:** 5,000 API calls/month

#### Rate Limits & Quotas
- Exceeding your rate limit returns **429 Too Many Requests**
- Exceeding your monthly quota returns **403 Forbidden** with upgrade details
- Burst limits allow for temporary spikes (2x standard rate limit)
- For higher limits, upgrade to Enterprise or contact sales

### Authenticating Requests

Include your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

#### Example: curl

```bash
curl -X GET \
  https://api.neuralnexus.biz/v1/models \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### Example: JavaScript (fetch)

```js
const response = await fetch('https://api.neuralnexus.biz/v1/models', {
  headers: {
    'Authorization': `Bearer ${process.env.NEURAL_NEXUS_API_KEY}`
  }
});
const data = await response.json();
```

#### Example: Using the SDK

```typescript
import { NeuralNexus } from 'neural-nexus';
const nexus = new NeuralNexus({
  apiKey: process.env.NEURAL_NEXUS_API_KEY,
  environment: 'production'
});
```

### Creating, Listing, and Revoking API Keys

#### List API Keys

```bash
curl -X GET \
  https://api.neuralnexus.biz/v1/api-keys \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### Create a New API Key

```bash
curl -X POST \
  https://api.neuralnexus.biz/v1/api-keys \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Production Key",
    "type": "production"
  }'
```

#### Revoke (Delete) an API Key

```bash
curl -X DELETE \
  https://api.neuralnexus.biz/v1/api-keys/key_123456 \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### Example: Managing API Keys in JavaScript

```js
async function createApiKey() {
  const API_KEY = process.env.NEURAL_NEXUS_API_KEY;
  const response = await fetch('https://api.neuralnexus.biz/v1/api-keys', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'My Development Key',
      type: 'development'
    })
  });
  const data = await response.json();
  console.log('New API key created:', data);
  console.log('IMPORTANT: Save this key now as it won\'t be shown again!');
  return data;
}
```

### Security Best Practices & FAQ

- **Never share your API keys or expose them in client-side code**
- **Store keys in environment variables, not in your code repository**
- **Create different keys for different environments (development, staging, production)**
- **Rotate keys regularly for enhanced security**
- **Delete unused keys to minimize security exposure**
- **Monitor key usage to detect any unauthorized access**
- **Use least privilege principle—only enable permissions your application needs**

**Q: What happens if I lose my API key?**
A: You must generate a new one. Keys are only shown once for security.

**Q: Can I restrict a key to certain models or endpoints?**
A: Yes, when creating a key, you can specify scopes and permissions in the dashboard.

**Q: How do I rotate keys without downtime?**
A: Create a new key, update your environment, then revoke the old key.

---


## 🛑 Error Handling & Troubleshooting

API responses use standard HTTP status codes and include detailed error messages.

| Status Code | Description                                      |
|-------------|--------------------------------------------------|
| 400         | Bad Request (malformed request/invalid params)   |
| 401         | Unauthorized (missing/invalid API key)           |
| 403         | Forbidden (valid key, insufficient permissions)  |
| 404         | Not Found (resource doesn't exist)               |
| 429         | Too Many Requests (rate limit exceeded)          |
| 500         | Internal Server Error                            |

#### Authentication Error Example
```json
{
  "error": {
    "message": "Authentication failed. Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "status": 401,
    "request_id": "req_12345"
  }
}
```

#### Handling Errors in Code
```typescript
try {
  const models = await modelManager.searchModels({ tag: 'vision' });
} catch (error) {
  if (error.response) {
    // API returned an error response
    console.error('API Error:', error.response.data);
    if (error.response.status === 401) {
      console.error('Check your API key!');
    } else if (error.response.status === 429) {
      console.error('Rate limit exceeded. Please wait and try again.');
    }
  } else if (error.request) {
    // No response received
    console.error('Network Error:', error.message);
  } else {
    // Other error
    console.error('Error:', error.message);
  }
}
```

**Common Issues:**
- **Invalid API Key:** Ensure your API key is correct and not expired. Get a new one from your [dashboard](https://neuralnexus.biz/dashboard).
- **Network Issues:** Check your internet connection and firewall settings.
- **Permission Denied:** Make sure your API key has the required permissions for the action.
- **File Upload Errors:** Ensure files exist and are accessible by your Node.js process.
- **Rate Limiting:** If you hit rate limits, wait and retry after some time.
- **API Changes:** Always check the [API documentation](https://www.neuralnexus.biz/api) for the latest endpoints and parameters.

---


## ⚡ Quick Start Example

```typescript
import { NeuralNexus, ModelManager } from 'neural-nexus';

const nexus = new NeuralNexus({
  apiKey: process.env.NEURAL_NEXUS_API_KEY, // 🔑 Required
  environment: 'production' // or 'development'
});

const modelManager = new ModelManager(nexus);

async function uploadModel() {
  try {
    const result = await modelManager.uploadModel({
      name: 'My Model',
      description: 'Description',
      files: [/* model files */],
      tags: ['vision', 'classification'],
      isPublic: true
    });
    console.log(`Model uploaded! ID: ${result.modelId}`);
  } catch (error) {
    if (error.response) {
      // API error
      console.error('API Error:', error.response.data);
    } else {
      // Network or other error
      console.error('Error:', error.message);
    }
  }
}

uploadModel();
```

---


## 📚 API Reference

### ModelManager

Upload, download, and search models.

```typescript
const modelManager = new ModelManager(nexus);

// Upload a model
await modelManager.uploadModel({
  name: 'My Model',
  description: 'Description',
  files: [/* model files */],
  tags: ['vision'],
  isPublic: true
});

// Search models
const models = await modelManager.searchModels({ tag: 'vision' });

// Download a model
await modelManager.downloadModel({ modelId: 'abc123', destination: './models' });
```

### Auth

Authentication operations.

```typescript
const auth = new Auth(nexus);
await auth.login('user@example.com', 'password123');
await auth.logout();
```

### Marketplace

Marketplace operations.

```typescript
const marketplace = new Marketplace(nexus);
const trending = await marketplace.getTrendingModels();
const details = await marketplace.getModelDetails('modelId');
```

### Payments

Process payments and handle transactions.

```typescript
const payments = new Payments(nexus);
await payments.purchaseModel('modelId', { method: 'stripe' });
```

### SDK Manager

Generate SDK code for different languages.

```typescript
const pythonSdk = nexus.sdk.generateSdk({
  language: 'python',
  includeExamples: true,
  prettyPrint: true
});
```

---


## 🧑‍💻 Real-World Usage Examples

### List All Models

```typescript
const models = await modelManager.searchModels({});
console.log('Available models:', models);
```

### Get Model Details

```typescript
const details = await modelManager.getModelDetails('gpt-nexus');
console.log('Model details:', details);
```

### Generate Text

```typescript
const response = await nexus.inference.generateText({
  modelId: 'gpt-nexus',
  prompt: 'Write a short poem about artificial intelligence',
  max_tokens: 256,
  temperature: 0.7
});
console.log('Generated text:', response.text);
```

### Generate Images

```typescript
const response = await nexus.inference.generateImage({
  modelId: 'stability-xl-1024',
  prompt: 'A futuristic city with flying cars and neon lights',
  n: 1,
  size: '1024x1024'
});
console.log('Image URLs:', response.images.map(img => img.url));
```

### Fine-Tune a Model

```typescript
const job = await nexus.training.createFineTuningJob({
  model: 'gpt-nexus-base',
  training_file: 'file_abc123',
  hyperparameters: { epochs: 3 }
});
console.log('Fine-tuning job created:', job);
```

### Usage Statistics

```typescript
const usage = await nexus.account.getUsageStats({
  start_date: '2023-05-01',
  end_date: '2023-05-31'
});
console.log('Usage stats:', usage);
```

---


## 💸 Pricing & Rate Limits

- **Pay-as-you-go:** $0.001 per 1,000 tokens
- **Free tier:** 5,000 API calls/month
- **Pro plan:** 60 req/min, 10,000 daily quota
- **Enterprise:** 600 req/min, unlimited daily quota
- **Transparent usage monitoring** in your dashboard

For full details, see the [pricing page](https://neuralnexus.biz/pricing).

---


## 🛠️ Development

- `npm run lint` — Check code style
- `npm test` — Run tests
- `npm run build` — Build the package

---


## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

---


## 📄 License

This project is licensed under the MIT or Boost Software License (see [LICENSE](./LICENSE)).

---


## 💬 Need Help?

- [Neural Nexus Docs](https://neuralnexus.biz/docs)
- [Open an Issue](https://github.com/Drago-03/neural-nexus-pkg/issues)
- [Contact Support](https://neuralnexus.biz/contact)

---


> _Built with ❤️ for the AI community. Secure, scalable, and ready for production._