pip install neuromesh-ai

python -c "import neuromesh; print(neuromesh.__version__)"
# 0.3.0

from neuromesh import Recommender

# 1. Define your items — any schema, only "id" is required
items = [
    {"id": "p1", "title": "Wireless Headphones", "category": "electronics", "brand": "Sony"},
    {"id": "p2", "title": "Gaming Mouse",         "category": "electronics", "brand": "Logitech"},
    {"id": "p3", "title": "Python Cookbook",      "category": "books"},
    {"id": "p4", "title": "Mechanical Keyboard",  "category": "electronics", "brand": "Keychron"},
]

# User interaction data (optional — needed for collaborative / hybrid)
interactions = [
    {"user_id": "alice", "item_id": "p1", "weight": 1.0},
    {"user_id": "alice", "item_id": "p4", "weight": 0.8},
    {"user_id": "bob",   "item_id": "p2", "weight": 1.0},
]

# 2. Create and train
rec = Recommender(engine="tfidf")   # or "embedding", "collaborative", "hybrid"
rec.train(items, interactions=interactions)

# 3. Item-based recommendations
print(rec.recommend("p1", top_k=3))

# 4. User-based recommendations (requires collaborative / hybrid engine)
rec2 = Recommender(engine="collaborative")
rec2.train(items, interactions=interactions)
print(rec2.recommend_for_user("alice", top_k=3))

# 5. Session-based (recency-weighted)
print(rec.recommend_for_session(["p3", "p1"], top_k=3))

# 6. Save and reload
rec.save("model.joblib")           # writes model.joblib + model.joblib.sha256
rec_loaded = Recommender.load("model.joblib")
print(rec_loaded.recommend("p1", top_k=2))

export NEUROMESH_API_KEY=dev-secret
uvicorn neuromesh.api:app --reload

curl -X POST http://localhost:8000/v1/train \
  -H "X-API-Key: dev-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"id":"p1","title":"Wireless Headphones","category":"electronics"},
      {"id":"p2","title":"Gaming Mouse","category":"electronics"},
      {"id":"p3","title":"Python Cookbook","category":"books"}
    ]
  }'

curl -X POST http://localhost:8000/v1/recommend \
  -H "X-API-Key: dev-secret" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"p1","top_k":5}'

{
  "results": [
    {"rank": 1, "item_id": "p2", "score": 0.812},
    {"rank": 2, "item_id": "p3", "score": 0.021}
  ],
  "engine": "tfidf",
  "tenant_id": "default"
}

git clone https://github.com/TheAmitChandra/NeuroMesh-AI.git
cd NeuroMesh-AI
cp .env.example .env          # set NEUROMESH_API_KEY
docker compose -f docker/docker-compose.yml up -d
# API running at http://localhost:8000

engine.fit(items, corpus, popularity_scores, freshness_scores, interactions)
engine.recommend(item_id, top_k, exclude_ids)   # → list[RecommendationResult]
engine.similar(item_id, top_k, exclude_ids)
engine.recommend_for_user(user_id, top_k, exclude_ids)  # raises NotImplementedError if unsupported
engine.engine_name   # str
engine.is_fitted     # bool

from neuromesh import Recommender

# Semantic embedding (requires pip install "neuromesh-ai[embedding]")
rec = Recommender(engine="embedding")
rec.train(items)
results = rec.recommend("p1", top_k=5)

# Collaborative (requires pip install "neuromesh-ai[collaborative]")
rec = Recommender(engine="collaborative")
rec.train(items, interactions=user_interactions)
results = rec.recommend_for_user("user-42", top_k=5)

# Trending
rec = Recommender(engine="trending")
rec.train(items)
results = rec.recommend("p1", top_k=5)   # ranks by popularity × freshness

# Hybrid (requires pip install "neuromesh-ai[all]")
rec = Recommender(engine="hybrid")
rec.train(items, interactions=user_interactions)
results = rec.recommend("p1", top_k=5)

{"error":"Item 'item-99' not found in the catalogue.","code":"item_not_found","details":{}}

curl -X POST http://localhost:8000/v1/tenants \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"shop-a","engine":"hybrid"}'

# Train shop-a
curl -X POST http://localhost:8000/v1/train \
  -H "X-API-Key: your-key" -H "X-Tenant-ID: shop-a" \
  -d '{"items":[{"id":"p1","title":"Widget"}]}'

# Get recommendations for shop-a — completely isolated from other tenants
curl -X POST http://localhost:8000/v1/recommend \
  -H "X-API-Key: your-key" -H "X-Tenant-ID: shop-a" \
  -d '{"item_id":"p1","top_k":5}'

NEUROMESH_ENGINE=hybrid   # tfidf | embedding | collaborative | trending | hybrid

NEUROMESH_MAX_TENANTS=100

curl -X POST http://localhost:8000/v1/ab \
  -H "X-API-Key: your-key" \
  -d '{
    "experiment_id":"engine-test",
    "variants":[
      {"name":"control","engine":"tfidf","weight":0.5},
      {"name":"treatment","engine":"hybrid","weight":0.5}
    ]
  }'

rec = Recommender(engine="tfidf")
rec.train(items)

# Writes: model.joblib  +  model.joblib.sha256
rec.save("model.joblib")

# Loads and verifies the SHA-256 sidecar before deserialising
rec2 = Recommender.load("model.joblib")
results = rec2.recommend("item-1", top_k=5)

NEUROMESH_MODEL_PATH=/var/neuromesh/model.joblib

curl -X POST http://localhost:8000/v1/model/save -H "X-API-Key: your-key"
# {"status":"ok","path":"/var/neuromesh/model.joblib","items_saved":42}

from neuromesh.integrations.shopify import ShopifyConnector
from neuromesh import Recommender

connector = ShopifyConnector(
    shop_url="https://your-store.myshopify.com",
    access_token="shpat_xxxx",
)
items = connector.fetch_products()

rec = Recommender(engine="hybrid")
rec.train(items)

from neuromesh.integrations.odoo import OdooConnector
from neuromesh import Recommender

connector = OdooConnector(
    url="https://your-odoo.com",
    db="your_db",
    username="admin",
    api_key="your_odoo_api_key",
)
items        = connector.fetch_products()
interactions = connector.fetch_orders()   # order lines → interactions

rec = Recommender(engine="collaborative")
rec.train(items, interactions=interactions)

import httpx
from neuromesh import Recommender

products = httpx.get(
    "https://myshop.com/wp-json/wc/v3/products",
    auth=("ck_xxx", "cs_xxx"),
).json()

rec = Recommender(engine="tfidf")
rec.train(products)   # "id" field used automatically

import pandas as pd
from neuromesh import Recommender

df    = pd.read_csv("products.csv")
items = df.to_dict(orient="records")

rec = Recommender(engine="tfidf")
rec.train(items)

NEUROMESH_VECTOR_STORE=pgvector   # faiss | qdrant | chroma | pgvector

# pgvector requires:
NEUROMESH_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/neuromesh

NEUROMESH_REDIS_URL=redis://localhost:6379/0
# TLS:
NEUROMESH_REDIS_URL=rediss://user:password@myredis.example.com:6380/0

pip install "neuromesh-ai[db]"
export NEUROMESH_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/neuromesh
python scripts/setup_db.py   # runs alembic upgrade head

git clone https://github.com/TheAmitChandra/NeuroMesh-AI.git && cd NeuroMesh-AI
cp .env.example .env
docker compose -f docker/docker-compose.yml up -d
docker compose exec neuromesh-api python scripts/setup_db.py

services:
  neuromesh:
    image: ghcr.io/theamitchandra/neuromesh-ai:latest
    ports: ["8000:8000"]
    environment:
      NEUROMESH_ENV: production
      NEUROMESH_API_KEY: change-me
      NEUROMESH_ENGINE: tfidf
      NEUROMESH_REDIS_URL: redis://redis:6379/0
      NEUROMESH_DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/neuromesh
      NEUROMESH_MODEL_PATH: /var/neuromesh/model.joblib
      NEUROMESH_CORS_ORIGINS: https://your-frontend.com
    volumes: [neuromesh_models:/var/neuromesh]
    depends_on: [redis, db]
  redis:
    image: redis:7-alpine
  db:
    image: pgvector/pgvector:pg16
    environment: {POSTGRES_DB: neuromesh, POSTGRES_USER: postgres, POSTGRES_PASSWORD: postgres}
    volumes: [pgdata:/var/lib/postgresql/data]
volumes: {neuromesh_models: {}, pgdata: {}}

apiVersion: apps/v1
kind: Deployment
metadata: {name: neuromesh-api}
spec:
  replicas: 1   # see multi-worker note — use sticky sessions for >1
  selector: {matchLabels: {app: neuromesh-api}}
  template:
    metadata: {labels: {app: neuromesh-api}}
    spec:
      containers:
        - name: api
          image: ghcr.io/theamitchandra/neuromesh-ai:latest
          ports: [{containerPort: 8000}]
          env:
            - name: NEUROMESH_API_KEY
              valueFrom: {secretKeyRef: {name: neuromesh-secrets, key: api-key}}
            - name: NEUROMESH_MODEL_PATH
              value: /var/neuromesh/model.joblib
          volumeMounts: [{name: model-storage, mountPath: /var/neuromesh}]
          livenessProbe:
            httpGet: {path: /v1/health, port: 8000}
            initialDelaySeconds: 15
            periodSeconds: 30
      volumes:
        - name: model-storage
          persistentVolumeClaim: {claimName: neuromesh-model-pvc}