NeuralStack

AI/ML API service with neural network capabilities for intelligent applications - making artificial intelligence accessible through simple REST APIs.

🌐 Live Demo

🚀 The API is live and ready to use!

Base URL: https://neuralstack-gfy2.onrender.com
Health Check: https://neuralstack-gfy2.onrender.com/health
API Info: https://neuralstack-gfy2.onrender.com/api/v1
Models Endpoint: https://neuralstack-gfy2.onrender.com/api/v1/models

Quick Test

# Check if API is running
curl https://neuralstack-gfy2.onrender.com/health

# Get available models
curl https://neuralstack-gfy2.onrender.com/api/v1/models

# Test sentiment analysis
curl -X POST https://neuralstack-gfy2.onrender.com/api/v1/predictions/sentiment \
  -H "Content-Type: application/json" \
  -d '{"text":"This API is amazing!"}'

Status Badges

🧠 About NeuralStack

NeuralStack is a powerful AI/ML API service that provides neural network capabilities through a simple REST API. Perfect for developers who want to add AI features to their applications without managing complex ML infrastructure or understanding the intricacies of machine learning frameworks.

With NeuralStack, you can perform image recognition, natural language processing, predictive analytics, and more through simple HTTP requests. Our pre-trained models are ready to use out of the box, and we support custom model training for specialized use cases.

👥 Who Should Use NeuralStack?

Developers

Integrate AI capabilities into applications quickly without ML expertise
Focus on building features rather than ML infrastructure
Use pre-trained models or train custom ones via API
Scale AI workloads automatically with our infrastructure
Get started with simple REST API calls

Data Scientists

Deploy ML models with simple API endpoints
Version control for trained models
A/B test different model versions in production
Monitor model performance with built-in analytics
Integrate seamlessly with existing data pipelines

Product Teams

Add intelligent features to products rapidly
Experiment with AI capabilities without heavy investment
Get to market faster with pre-built models
Monitor AI feature usage and performance metrics
Scale AI features as your product grows

Startups & Enterprises

Reduce AI infrastructure costs significantly
Enterprise-grade security and compliance built-in
SLA-backed uptime guarantees for production workloads
Dedicated support for mission-critical applications
Custom model training services available

✨ Key Features

Pre-Trained Models

Image Recognition - Classify images into 1000+ categories instantly
Object Detection - Detect and locate multiple objects in images
Face Detection - Identify faces and extract facial landmarks
Text Classification - Categorize text by topic, intent, or sentiment
Sentiment Analysis - Understand emotional tone in customer feedback
Named Entity Recognition - Extract people, places, organizations from text
Language Translation - Translate between 100+ languages accurately
Text Summarization - Generate concise summaries automatically
Question Answering - Extract answers from context documents
Speech Recognition - Convert audio to text with high accuracy

Custom Model Training

Dataset Upload - Upload training data via API or dashboard
Model Training - Train custom models on your specific data
Hyperparameter Tuning - Automatic optimization for best results
Training Monitoring - Track progress in real-time with detailed metrics
Model Versioning - Manage multiple model versions simultaneously
A/B Testing - Compare model performance with live traffic
Transfer Learning - Fine-tune pre-trained models for your use case
Model Export - Download trained models for edge deployment

API Features

RESTful API - Simple, well-documented HTTP interface
WebSocket Streaming - Real-time predictions for live data
Batch Processing - Process thousands of inputs efficiently
Rate Limiting - Flexible rate limits based on your plan
Authentication - Secure API key and OAuth 2.0 support
CORS Support - Cross-origin requests enabled by default
Webhooks - Get notified when training completes
SDK Libraries - Official SDKs for Python, JavaScript, Java, Go

Model Management

Version Control - Track every version of your models
Rollback - Instantly revert to previous versions
Model Registry - Centralized storage for all models
One-Click Deployment - Deploy models to production instantly
Performance Monitoring - Track accuracy, latency, throughput
Alerts - Get notified of performance degradation
Canary Deployments - Gradual rollout of new versions
Blue-Green Deployment - Zero-downtime updates

Performance & Scaling

Auto-Scaling - Automatically handle variable load
Load Balancing - Distribute requests across multiple instances
Smart Caching - Cache results for faster responses
GPU Acceleration - Leverage GPUs for fast inference
Edge Deployment - Deploy models closer to users globally
Batch Optimization - Automatic batching for throughput
Model Quantization - Reduce model size without accuracy loss

Security & Compliance

API Key Management - Secure authentication with rotation
Encryption - Data encrypted in transit (TLS) and at rest
GDPR Compliance - Full data privacy protection
SOC 2 Type II - Enterprise security standards
Audit Logs - Complete activity tracking for compliance
Role-Based Access - Fine-grained permission control
Data Isolation - Your data never mixed with others
PII Detection - Automatic detection and masking

🚀 Getting Started

Prerequisites

Node.js 18.x or higher
npm or yarn package manager
PostgreSQL 14+ (for production)
Redis 6+ (for caching)

Installation

Clone the repository

git clone https://github.com/Emoji-dot/neuralstack.git
cd neuralstack

Install dependencies

npm install
# or
yarn install

Configure environment

cp .env.example .env

Edit .env with your settings:

PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/neuralstack
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-secret-key
API_KEY_SECRET=your-api-key-secret

# ML Storage
MODEL_STORAGE=./ml-models
DATASET_STORAGE=./datasets

# Optional: GPU acceleration
GPU_ENABLED=false

Run database migrations

npm run migrate

Build the project

npm run build

Start the server

npm start

API available at http://localhost:3000

Quick Example

// Image classification example
const response = await fetch('http://localhost:3000/api/v1/classify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    image_url: 'https://example.com/cat.jpg'
  })
});

const result = await response.json();
console.log(result.predictions);
// [{ label: 'cat', confidence: 0.95 }, ...]

🛠️ Tech Stack

Backend Framework

Node.js 20+ - JavaScript runtime environment
TypeScript 5.3+ - Type-safe development
Express.js - Fast, unopinionated web framework
Fastify - High-performance alternative option

AI/ML Libraries

TensorFlow.js - ML framework for JavaScript/Node.js
ONNX Runtime - Cross-platform ML inference
Sharp - High-performance image processing
Natural - Natural language processing toolkit
Transformers.js - State-of-the-art NLP models

Database & Cache

PostgreSQL - Primary relational database
Redis - High-speed caching and queuing
MongoDB - Document storage for unstructured data
S3/MinIO - Object storage for models and datasets

Infrastructure

Docker - Containerization for consistent deployments
Kubernetes - Container orchestration at scale
Nginx - Reverse proxy and load balancer
PM2 - Node.js process management

Monitoring & Logging

Prometheus - Metrics collection and alerting
Grafana - Beautiful metrics visualization
Winston - Flexible application logging
Sentry - Real-time error tracking
OpenTelemetry - Distributed tracing

📁 Project Structure

neuralstack/
├── src/
│   ├── routes/              # API route definitions
│   ├── controllers/         # Request handlers
│   ├── services/            # Business logic layer
│   │   ├── ml/             # ML model services
│   │   ├── training/       # Model training logic
│   │   └── inference/      # Prediction services
│   ├── models/              # Database models (TypeORM/Prisma)
│   ├── middleware/          # Express middleware
│   ├── utils/              # Utility functions
│   ├── config/             # Configuration management
│   ├── types/              # TypeScript type definitions
│   └── index.ts            # Application entry point
├── ml-models/              # Trained model storage
├── datasets/               # Training dataset storage
├── tests/                  # Test files
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── e2e/               # End-to-end tests
├── docs/                   # API documentation
└── scripts/                # Utility scripts

🎯 API Endpoints

Authentication

POST /api/v1/auth/register   - Create new account
POST /api/v1/auth/login      - Login and get API key
POST /api/v1/auth/refresh    - Refresh access token
POST /api/v1/auth/logout     - Logout and revoke token

Image Processing

POST /api/v1/image/classify  - Classify image content
POST /api/v1/image/detect    - Detect objects in image
POST /api/v1/image/segment   - Segment image regions
POST /api/v1/image/enhance   - Enhance image quality
POST /api/v1/image/generate  - Generate images (AI)

Text Processing

POST /api/v1/text/sentiment  - Analyze sentiment
POST /api/v1/text/summarize  - Summarize long text
POST /api/v1/text/translate  - Translate languages
POST /api/v1/text/entities   - Extract named entities
POST /api/v1/text/classify   - Classify text category

Model Management

GET    /api/v1/models        - List all models
POST   /api/v1/models        - Upload new model
GET    /api/v1/models/:id    - Get model details
PUT    /api/v1/models/:id    - Update model
DELETE /api/v1/models/:id    - Delete model
POST   /api/v1/models/:id/deploy - Deploy to production

Training

POST /api/v1/training/start  - Start training job
GET  /api/v1/training/:id    - Get training status
POST /api/v1/training/stop   - Stop training job
GET  /api/v1/training/:id/logs - Get training logs

🚢 Deployment

Docker

docker build -t neuralstack .
docker run -p 3000:3000 --env-file .env neuralstack

Docker Compose

docker-compose up -d

Kubernetes

kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

Cloud Platforms

AWS ECS

aws ecs create-service --cli-input-json file://ecs-service.json

Google Cloud Run

gcloud run deploy neuralstack --source .

Azure Container Instances

az container create --resource-group myRG --name neuralstack --image neuralstack:latest

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Run load tests
npm run test:load

📊 Monitoring

Metrics Dashboard

Access at http://localhost:3001 (Grafana)

Key metrics monitored:

Request rate and latency percentiles
Model inference time (p50, p95, p99)
GPU utilization and memory usage
Database connection pool status
Cache hit ratio
Error rates by endpoint

Health Checks

# Basic health check
curl http://localhost:3000/health

# Detailed status
curl http://localhost:3000/health/detailed

🐛 Troubleshooting

Model Not Loading

Check: Model file exists in MODEL_STORAGE path
Verify: Model format is supported (TensorFlow, ONNX, PyTorch)
Ensure: Sufficient memory available (check logs)
Review: Error logs in logs/error.log

Slow Inference Times

Enable: GPU acceleration if available (GPU_ENABLED=true)
Use: Model quantization for faster inference
Implement: Request batching in your client
Check: Network latency to model storage

High Memory Usage

Reduce: Batch size in configuration
Enable: Model caching with CACHE_MODELS=true
Use: Lighter model variants when possible
Monitor: For memory leaks with profiler

Database Connection Issues

Verify: DATABASE_URL is correct
Check: Database is running and accessible
Ensure: Connection pool settings are appropriate
Review: Firewall rules and network connectivity

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📄 License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
API_DOCUMENTATION.md		API_DOCUMENTATION.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
GITHUB_SETUP.md		GITHUB_SETUP.md
LICENSE		LICENSE
QUICK_DEPLOY.md		QUICK_DEPLOY.md
QUICK_SUBMIT_TODAY.md		QUICK_SUBMIT_TODAY.md
README.md		README.md
README_FULL.md		README_FULL.md
SETUP_COMPLETE.md		SETUP_COMPLETE.md
TODAY_CHECKLIST.txt		TODAY_CHECKLIST.txt
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
quick_commits.ps1		quick_commits.ps1
tsconfig.json		tsconfig.json
update_readme_with_live_url.ps1		update_readme_with_live_url.ps1

Latest commit

History

Folders and files

Repository files navigation

NeuralStack

🌐 Live Demo

Quick Test

Status Badges

🧠 About NeuralStack

👥 Who Should Use NeuralStack?

Developers

Data Scientists

Product Teams

Startups & Enterprises

✨ Key Features

Pre-Trained Models

Custom Model Training

API Features

Model Management

Performance & Scaling

Security & Compliance

🚀 Getting Started

Prerequisites

Installation

Quick Example

🛠️ Tech Stack

Backend Framework

AI/ML Libraries

Database & Cache

Infrastructure

Monitoring & Logging

📁 Project Structure

🎯 API Endpoints

Authentication

Image Processing

Text Processing

Model Management

Training

🚢 Deployment

Docker

Docker Compose

Kubernetes

Cloud Platforms

🧪 Testing

📊 Monitoring

Metrics Dashboard

Health Checks

🐛 Troubleshooting

Model Not Loading

Slow Inference Times

High Memory Usage

Database Connection Issues

🤝 Contributing

📄 License

🔗 Resources

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages