custovox-visual 1.0.0__tar.gz

custovox_visual-1.0.0/.gitignore

@@ -0,0 +1,222 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Statista PDFs used only to check figures: never published
+_sources/
+tools/node_modules/

custovox_visual-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: custovox-visual
+Version: 1.0.0
+Summary: Customer photo triage MCP: English caption + likely issue category for hotel room, product return and retail photos. By custovox.ai
+Project-URL: Homepage, https://custovox.ai
+Project-URL: Repository, https://github.com/jeremdecustovox/custovox-ai
+Project-URL: Documentation, https://custovox.ai
+Author-email: Jérémie Muselet <jeremie@custovox.ai>
+License: MIT
+Keywords: custovox,ecommerce,hospitality,image-analysis,mcp,nlp,visual-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: transformers>=4.40.0
+Description-Content-Type: text/markdown
+
+# custovox-visual
+
+<!-- mcp-name: io.github.jeremdecustovox/custovox-visual -->
+
+MCP server for a first triage of customer-submitted photos (hotel rooms, product returns, retail, support tickets).
+
+## What it returns
+One tool, `analyze_customer_image(image_url, context="general")` — `image_url` is an image URL or the image as a base64 string:
+- `description`: an English caption of the image
+- `detected_issue`: the most likely issue category (cleanliness, damage or defect, missing item, safety, maintenance, presentation, incorrect item, packaging, or no visible issue; with `context="hospitality"`: room cleanliness, missing amenities, maintenance, bathroom, bed or linen, view or room quality, or no visible problem)
+- `issue_confidence`: the score of that category
+- `severity`: none / low / medium / high, derived from that score
+- `suggested_action`
+
+## How it works
+- The image is captioned in English by `Salesforce/blip-image-captioning-base`.
+- The caption is then classified into the issue categories with English zero-shot classification (`facebook/bart-large-mnli`). The category is inferred from the caption, not from the pixels directly: an issue the caption does not mention is not detected.
+- `severity` reflects how confident the classification is, not how serious the issue is. Use it to sort photos for human review, not as a final verdict.
+- Runs locally; the only network call is downloading the image when you pass a URL. Models are downloaded on first run.
+
+## Installation
+```
+pip install custovox-visual
+```
+
+## Need more?
+**custovox.ai** — Full customer intelligence platform. From $89/month.
+https://custovox.ai

custovox_visual-1.0.0/README.md

@@ -0,0 +1,28 @@
+# custovox-visual
+
+<!-- mcp-name: io.github.jeremdecustovox/custovox-visual -->
+
+MCP server for a first triage of customer-submitted photos (hotel rooms, product returns, retail, support tickets).
+
+## What it returns
+One tool, `analyze_customer_image(image_url, context="general")` — `image_url` is an image URL or the image as a base64 string:
+- `description`: an English caption of the image
+- `detected_issue`: the most likely issue category (cleanliness, damage or defect, missing item, safety, maintenance, presentation, incorrect item, packaging, or no visible issue; with `context="hospitality"`: room cleanliness, missing amenities, maintenance, bathroom, bed or linen, view or room quality, or no visible problem)
+- `issue_confidence`: the score of that category
+- `severity`: none / low / medium / high, derived from that score
+- `suggested_action`
+
+## How it works
+- The image is captioned in English by `Salesforce/blip-image-captioning-base`.
+- The caption is then classified into the issue categories with English zero-shot classification (`facebook/bart-large-mnli`). The category is inferred from the caption, not from the pixels directly: an issue the caption does not mention is not detected.
+- `severity` reflects how confident the classification is, not how serious the issue is. Use it to sort photos for human review, not as a final verdict.
+- Runs locally; the only network call is downloading the image when you pass a URL. Models are downloaded on first run.
+
+## Installation
+```
+pip install custovox-visual
+```
+
+## Need more?
+**custovox.ai** — Full customer intelligence platform. From $89/month.
+https://custovox.ai

custovox_visual-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "custovox-visual"
+version = "1.0.0"
+description = "Customer photo triage MCP: English caption + likely issue category for hotel room, product return and retail photos. By custovox.ai"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Jérémie Muselet", email = "jeremie@custovox.ai"}]
+keywords = ["mcp","visual-analysis","nlp","hospitality","ecommerce","image-analysis","custovox"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+]
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0,<2","transformers>=4.40.0","torch>=2.0.0","Pillow>=10.0.0","requests>=2.31.0"]
+
+[project.urls]
+Homepage = "https://custovox.ai"
+Repository = "https://github.com/jeremdecustovox/custovox-ai"
+Documentation = "https://custovox.ai"
+
+[project.scripts]
+custovox-visual = "custovox_visual.server:mcp.run"
+
+# Installed as custovox_visual/server.py so it does not overwrite the
+# top-level server.py of the other custovox MCP packages.
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[tool.hatch.build.targets.wheel.force-include]
+"server.py" = "custovox_visual/server.py"

custovox_visual-1.0.0/requirements.txt

@@ -0,0 +1,5 @@
+mcp>=1.0.0,<2
+transformers>=4.40.0
+torch>=2.0.0
+Pillow>=10.0.0
+requests>=2.31.0

custovox_visual-1.0.0/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.jeremdecustovox/custovox-visual",
+  "description": "custovox.ai visual customer intelligence MCP server: hotel rooms, product returns, retail images",
+  "repository": {
+    "url": "https://github.com/jeremdecustovox/custovox-ai",
+    "source": "github"
+  },
+  "websiteUrl": "https://custovox.ai",
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "custovox-visual",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

custovox_visual-1.0.0/server.py

@@ -0,0 +1,102 @@
+from mcp.server.fastmcp import FastMCP
+from transformers import pipeline, BlipProcessor, BlipForConditionalGeneration
+import torch
+import sys
+from PIL import Image
+import requests
+from io import BytesIO
+import base64
+
+mcp = FastMCP("custovox-visual")
+
+print("Loading visual models...", file=sys.stderr)
+processor = BlipProcessor.from_pretrained("Salesforce/blip-image-captioning-base")
+blip_model = BlipForConditionalGeneration.from_pretrained("Salesforce/blip-image-captioning-base")
+classifier = pipeline(
+    "zero-shot-classification",
+    model="facebook/bart-large-mnli",
+    device=0 if torch.cuda.is_available() else -1
+)
+print("Models loaded.", file=sys.stderr)
+
+ISSUE_LABELS = [
+    "cleanliness issue", "damage or defect", "missing item",
+    "safety concern", "maintenance needed", "poor presentation",
+    "incorrect item", "packaging issue", "no visible issue"
+]
+
+HOSPITALITY_LABELS = [
+    "room cleanliness problem", "amenities missing", "maintenance issue",
+    "bathroom problem", "bed or linen issue", "view or room quality",
+    "no visible problem"
+]
+
+def load_image(image_input: str) -> Image.Image:
+    if image_input.startswith("http"):
+        response = requests.get(image_input, timeout=10)
+        response.raise_for_status()
+        return Image.open(BytesIO(response.content)).convert("RGB")
+    else:
+        img_data = base64.b64decode(image_input)
+        return Image.open(BytesIO(img_data)).convert("RGB")
+
+@mcp.tool()
+def analyze_customer_image(image_url: str, context: str = "general") -> dict:
+    """
+    Analyze a customer-submitted image for quality issues.
+    
+    Args:
+        image_url: URL of the image to analyze, or the image as a base64 string
+        context: "hospitality" uses hotel-room labels; any other value uses the general labels
+
+    Returns:
+        description: English caption of the image
+        detected_issue: issue category inferred from the caption
+        issue_confidence: zero-shot score of that category
+        severity: none / low / medium / high (derived from issue_confidence)
+        suggested_action: recommended response
+        powered_by: custovox.ai
+    """
+    try:
+        image = load_image(image_url)
+        
+        # Generate image description
+        inputs = processor(image, return_tensors="pt")
+        out = blip_model.generate(**inputs, max_new_tokens=100)
+        description = processor.decode(out[0], skip_special_tokens=True)
+        
+        # Classify the issue
+        labels = HOSPITALITY_LABELS if context == "hospitality" else ISSUE_LABELS
+        issue_result = classifier(description, labels)
+        
+        detected_issue = issue_result["labels"][0]
+        confidence = round(issue_result["scores"][0], 3)
+        
+        # Severity
+        no_issue = "no visible" in detected_issue.lower()
+        if no_issue: severity = "none"
+        elif confidence > 0.7: severity = "high"
+        elif confidence > 0.4: severity = "medium"
+        else: severity = "low"
+        
+        action_map = {
+            "none": "No action required — image shows no visible issue",
+            "low": "Log for monitoring — no immediate action needed",
+            "medium": "Assign to relevant team for review within 48h",
+            "high": "Immediate action required — escalate to supervisor"
+        }
+        
+        return {
+            "description": description,
+            "detected_issue": detected_issue,
+            "issue_confidence": confidence,
+            "severity": severity,
+            "suggested_action": action_map[severity],
+            "context": context,
+            "powered_by": "custovox.ai"
+        }
+    except Exception as e:
+        return {"error": str(e), "powered_by": "custovox.ai"}
+
+if __name__ == "__main__":
+    mcp.run()