Getting Started¶

Setting up and running VSS Feature Store from scratch

Prerequisites¶

Python 3.10 or higher
uv installed (Official Documentation)
MinIO access permission

1. Clone Project¶

git clone <repository-url> mantis-ml-platform
cd mantis-ml-platform

2. Virtual Environment Setup¶

Create Virtual Environment¶

uv venv

Output:

Using Python 3.10.12
Creating virtualenv at: .venv

Activate Virtual Environment¶

source .venv/bin/activate

Activation confirmation:

(.venv) ail@server:~/pyler/mantis-ml-platform$

3. Install Libraries¶

uv pip install -e "packages/mantis_common" -e "services/svc-vss/data/feast"

Output:

Resolved 87 packages in 2.3s
Installed 87 packages in 1.8s
 + feast==0.40.1
 + milvus-lite==2.4.9
 + pandas==2.2.3
 + pyyaml==6.0.2
 ...

Installation Complete

All required packages have been installed successfully.

4. Environment Variable Setup¶

MinIO Feature Store Connection¶

export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

Maintain Environment Variables

Environment variables are only valid for the current terminal session.
You must set them again each time you open a new terminal.

Permanent Setup (Optional)¶

If you find it cumbersome to set every time, add to ~/.bashrc or ~/.zshrc:

# VSS Feature Store Environment Variables
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

Apply:

source ~/.bashrc  # or source ~/.zshrc

5. Verify MCP Server Execution¶

Run MCP Server¶

python services/svc-vss/data/feast/mcp_server.py

Success Output¶

2026-01-19 09:09:31,373 - __main__ - INFO - Starting VSS Feature Store MCP Server...
2026-01-19 09:09:31,378 - __main__ - INFO - Server initialized, waiting for requests...

MCP Server Running Successfully

The server has started normally!
You can stop it with Ctrl+C.

Checks When Execution Fails¶

Error: ModuleNotFoundError

Solution: Check virtual environment activation
source .venv/bin/activate

Error: MinIO Connection Failure

Solution: Check environment variables
echo $AWS_ENDPOINT_URL_S3

Error: No such file or directory

Solution: Check path
pwd  # Verify it's /home/ail/pyler/mantis-ml-platform

6. Function Testing¶

Run Test¶

python services/svc-vss/data/feast/test_feast.py

7. Quick Start: Python Script¶

After setting up virtual environment and environment variables, try running this code:

import api
from constants import FEATURE_VIEW_VIDEO_DESCRIPTION

# 0) Target Feature View
fv = FEATURE_VIEW_VIDEO_DESCRIPTION

# 1) Register New Captions (required step)
result = api.register_captions(
    feature_view=fv,
    uuid='yt-video-001',
    mp4_source='https://www.youtube.com/watch?v=wjZofJX0v4M',
    model='gpt-4o',
    segments=[
        {'index': 0, 'start': 0.0,  'end': 10.0, 'text': 'Intro segment...'},
        {'index': 1, 'start': 10.0, 'end': 20.0, 'text': 'Content segment...'},
    ],
)

# 2) Retrieve Captions (verify registration result)
captions = api.get_captions(
    feature_view=fv,
    uuid='yt-video-001',
    model='gpt-4o',
)

# 3) Search Metadata (optional)
metadata = api.search_metadata(
    feature_view=fv,
    models=['gpt-4o'],
)

print(f"Registered {len(captions)} segments")
print(f"Metadata count: {len(metadata)}")

Feature View Types¶

from constants import (
    FEATURE_VIEW_VIDEO,               # Video information
    FEATURE_VIEW_VIDEO_DESCRIPTION,    # Video description
    FEATURE_VIEW_AUDIO_TRANSCRIPT,     # Audio transcription
    FEATURE_VIEW_CAPTION_SUMMARY,      # Caption summary 
)

Troubleshooting¶

Virtual Environment Not Activated¶

# Check current directory
pwd  # /home/ail/pyler/mantis-ml-platform

# Recreate virtual environment
rm -rf .venv
uv venv
source .venv/bin/activate

Environment Variables Not Set¶

# Check environment variables
env | grep -E "AWS|FEAST"

# If no output, set again
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

MinIO Connection Failure¶

# Check MinIO endpoint access
curl http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

# Or ping test
ping andrew-minio-2025-12-03-svc.dev.idc.k8s

Package Installation Error¶

# Upgrade pip
uv pip install --upgrade pip

# Individual reinstall
uv pip install -e "packages/mantis_common" --force-reinstall
uv pip install -e "services/svc-vss/data/feast" --force-reinstall

Installation Checklist¶

Check off completed items:

[ ] Python 3.10 or higher installed
[ ] uv installed
[ ] Project cloned
[ ] Virtual environment created and activated
[ ] Libraries installed
[ ] Environment variables set
[ ] MCP server execution verified
[ ] Function test passed

Next Steps¶

MCP Integration¶

To use MCP server in Claude Code or Cursor:

👉 MCP Integration Guide

API Usage¶

To use VSS Feature Store in Python code:

👉 API Reference

Config Setup¶

To customize caption generation settings:

👉 Configuration

Understanding Architecture¶

To learn more about system structure:

👉 Architecture

Summary¶

# 1. Virtual environment setup
uv venv
source .venv/bin/activate

# 2. Install libraries
uv pip install -e "packages/mantis_common" -e "services/svc-vss/data/feast"

# 3. Set environment variables
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

# 4. Run MCP server (verify)
python services/svc-vss/data/feast/mcp_server.py

# 5. Function test
python services/svc-vss/data/feast/test_feast.py

Installation Complete! 🎉