v0.8.0 · Cloud Deployment Blueprint

Summary

This pre-release adds a sanitized Google Cloud deployment blueprint for VersoVector.

The milestone documents how the project could be deployed as a containerized emotional-semantic recommendation system using Cloud Run, Artifact Registry, Terraform, Docker services, and a future remote model artifact strategy.

This release keeps the public repository portfolio-ready while maintaining a clear boundary between public architecture documentation and private production infrastructure.

Highlights

• Added a sanitized Terraform blueprint under:

infra/gcp-cloud-run-blueprint/

• Added conceptual Google Cloud resources for:

  • Artifact Registry;
  • Cloud Run API service;
  • Cloud Run frontend service;
  • runtime service accounts;
  • public frontend access;
  • private API access from the frontend service account;
  • optional remote model artifact store configuration.

• Added a public GCP architecture diagram:

figs/VersoVector-GCP-Architecture.png

• Updated the main README with:

  • GCP deployment blueprint overview;
  • public vs private repository boundary;
  • updated repository structure;
  • additional documentation links;
  • infrastructure policy;
  • updated current status;
  • updated MLOps workflow phases.

• Updated .gitignore to exclude Terraform local state and sensitive local configuration.

Public Repository Scope

This release keeps the public repository focused on:

architecture
demo frontend
FastAPI backend
Docker services
tests
documentation
sanitized Terraform blueprint

Private Production Scope

The following are intentionally excluded from the public repository:

real GCP project IDs
real IAM bindings
secrets
service account keys
billing configuration
authentication
premium access logic
analytics
production monitoring
private datasets
Terraform state
deployment environments

A real production deployment should live in a private repository or private environment-specific configuration, such as:

VersoVector-Platform

Blueprint Structure

infra/
└── gcp-cloud-run-blueprint/
    ├── README.md
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── versions.tf
    └── terraform.tfvars.example

Validation

Recommended Terraform validation:

cd infra/gcp-cloud-run-blueprint

terraform init
terraform fmt -recursive
terraform validate

Optional local plan:

cp terraform.tfvars.example terraform.tfvars
terraform plan -var-file=terraform.tfvars

Do not commit terraform.tfvars, .terraform/, or *.tfstate.

Pre-release Notice

This is a pre-release architecture and infrastructure blueprint milestone.

It does not deploy a production environment and does not include final Cloud Run deployment automation, real Artifact Registry configuration, production IAM, authentication, billing, monitoring, or GitHub Actions deployment workflows.

The goal is to document a credible public cloud architecture while keeping production infrastructure private and secure.

v0.7.0 · UI Product Experience Foundation

Summary

This pre-release adds the first UI Product Experience Foundation for VersoVector.

It evolves the initial Gradio frontend from a raw technical interface into a calmer, more polished, product-oriented experience for emotional-semantic poetry analysis.

The goal of this milestone is to make the public demo feel closer to an actual AI product while keeping production-only features such as authentication, billing, private datasets, and infrastructure outside the public portfolio repository.

Highlights

• Refined the Gradio frontend layout.
• Added a calmer visual direction based on sage green, forest green, warm cream, and soft card surfaces.
• Improved the VersoVector product header and logo treatment.
• Added a local suggested tag catalog.
• Improved suggested tag chips.
• Improved predicted tag visualization with horizontal percentage bars.
• Improved similar poems presentation.
• Kept technical model details secondary through collapsible sections.
• Added a cleaner advanced options area.
• Added a discreet API and developer guide section.
• Added frontend timeout handling for heavier API calls.
• Added API readiness support for frontend health checks.

Updated Frontend Structure

apps/frontend/
├── README.md
├── app.py
├── client.py
├── tag_catalog.py
├── ui_formatters.py
└── assets/

Product Direction

This release separates the user experience into two layers:

Public Analysis Layer

Focused on the main user journey:

• submit a poem or reflective text;
• select optional suggested tags;
• receive predicted emotional-semantic tags;
• review semantically similar poems;
• inspect the result in a calm, readable interface.

Advanced / Developer Layer

Kept secondary and collapsible:

• advanced thresholds;
• top-k settings;
• API health and readiness;
• raw model output;
• API endpoint guide.

This structure supports the long-term product direction of VersoVector as an emotional-semantic recommendation engine for poetic and lyrical content.

Validation

Recommended local validation:

python -m py_compile \
  apps/frontend/app.py \
  apps/frontend/client.py \
  apps/frontend/ui_formatters.py \
  apps/frontend/tag_catalog.py

Run the API:

PYTHONPATH=src:. uvicorn versovector.api.main:app \
  --host 0.0.0.0 \
  --port 8001 \
  --reload

Warm up the model:

curl http://localhost:8001/ready | jq .

Run the frontend:

VERSOVECTOR_API_BASE_URL=http://localhost:8001 \
VERSOVECTOR_API_TIMEOUT_SECONDS=300 \
PORT=7860 \
python apps/frontend/app.py

Open:

http://localhost:7860

Pre-release Notice

This is a pre-release foundation milestone.

The project is not yet production-deployed and does not include final authentication, subscription logic, billing, Terraform, Cloud Run infrastructure, Artifact Registry configuration, or GitHub Actions deployment automation.

Production datasets, private deployment settings, commercial features, and monetization logic are intentionally excluded from this public repository.

v0.6.0 · Packaging and Services Foundation

Summary

This pre-release adds the first Packaging and Services Foundation for VersoVector.

It introduces a clearer path from Python package code to local service execution by adding package build support, tox orchestration, Docker-based API and frontend services, Docker Compose, and an initial Gradio demo application.

Highlights

• Stabilized pyproject.toml for package builds.
• Added wheel generation support with python -m build.
• Updated package license metadata to use modern SPDX-style configuration.
• Added tox.ini for tests, coverage, linting, formatting, and build validation.
• Made spaCy loading lazy to support lightweight test environments.
• Added FastAPI Docker service packaging.
• Added Gradio frontend Docker service packaging.
• Added local Docker Compose orchestration for API and frontend.
• Added the first user-facing Gradio demo app.
• Added documentation for apps/ and services/.
• Updated the main README with the Packaging and Services Foundation section.

New Structure

apps/
└── frontend/
    ├── README.md
    ├── app.py
    ├── client.py
    └── assets/

services/
├── api/
│   ├── Dockerfile
│   ├── README.md
│   └── .dockerignore
├── frontend/
│   ├── Dockerfile
│   ├── README.md
│   └── .dockerignore
└── compose.yaml

Local Build

Build the Python package:

python -m build

The generated files are written to:

dist/
├── versovector-0.6.0-py3-none-any.whl
└── versovector-0.6.0.tar.gz

The dist/ directory is generated locally and is not committed to Git.

Local Services

Run API and frontend together:

docker compose -f services/compose.yaml up --build

Local URLs:

API:
    http://localhost:8001

API docs:
    http://localhost:8001/docs

Frontend:
    http://localhost:7860

Model Artifact Strategy

The Docker image packages code, not model artifacts.

In this foundation stage, the API container expects a local model bundle mounted as a read-only volume:

artifacts/model_bundle:/app/artifacts/model_bundle:ro

A future Cloud Run version should retrieve the model bundle from a controlled artifact store such as Google Cloud Storage, Artifact Registry, or an MLflow artifact store.

Validation

Recommended validation commands:

tox -e unit
tox -e integration
tox -e coverage
tox -e build

Pre-release Notice

This is a pre-release foundation milestone.

The project is not yet production-deployed and does not include the final Cloud Run, Terraform, Artifact Registry, or GitHub Actions deployment layer.

v0.5.0 · Testing Foundation

Summary

This release adds the first unit and integration testing foundation for VersoVector.

It introduces a structured test layer for reusable modules, inference components, and FastAPI endpoints, preparing the project for future CI/CD workflows.

Highlights

• Added tests/README.md with the testing strategy.
• Added tests/conftest.py with minimal dummy model components and fixtures.
• Added unit tests for:
  • preprocessing utilities;
  • artifact store helpers;
  • inference schemas;
  • semantic similarity formatting;
  • tag prediction ranking.
• Added integration tests for:
  • minimal model bundle loading;
  • PoemAnalyzer.analyze_dict;
  • FastAPI endpoints with TestClient.
• Added requirements-test.txt.
• Updated dependency group documentation.
• Configured pytest warning filters for known third-party warnings.

Test Structure

tests/
├── README.md
├── conftest.py
├── unit/
│   ├── test_preprocessing.py
│   ├── test_artifact_store.py
│   ├── test_inference_schemas.py
│   ├── test_similarity_search.py
│   └── test_tag_predictor.py
└── integration/
    ├── test_model_bundle_loading.py
    ├── test_poem_analyzer_end_to_end.py
    └── test_api_endpoints.py

Validation

The following commands were executed successfully:

PYTHONPATH=src:. pytest tests/unit
PYTHONPATH=src:. pytest tests/integration
PYTHONPATH=src:. pytest --cov=src --cov=modules tests/

Result:

20 passed

Coverage

The current coverage baseline is approximately:

TOTAL: 66%

This gives the project a measurable quality baseline for future CI/CD improvements.

Notes

The integration tests use a minimal mocked model bundle generated under tmp_path.

They do not require the real artifacts/model_bundle/ directory and do not use large model artifacts.

v0.4.0 · API Serving Foundation

Summary

This release adds the first FastAPI serving layer for VersoVector.

It exposes the inference package through API endpoints for emotional-semantic poem analysis, tag prediction, model information, and semantic similarity search.

Highlights

• Added FastAPI application entrypoint.
• Added API request and response schemas.
• Added runtime settings with environment variable support.
• Added lazy PoemAnalyzer dependency loading.
• Added health check endpoint.
• Added model information endpoint.
• Added full poem analysis endpoint.
• Added tag prediction endpoint.
• Added semantic similarity endpoint.
• Updated package documentation.

API Endpoints

GET  /
GET  /health
GET  /v1/model-info
POST /v1/analyze
POST /v1/predict-tags
POST /v1/similar

Local Run

PYTHONPATH=src:. uvicorn versovector.api.main:app \
  --host 0.0.0.0 \
  --port 8001 \
  --reload

Example Analysis Request

curl -X POST http://localhost:8001/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "title": "test poem",
    "poet": "anonymous",
    "poem": "I walk through the rain carrying a memory of light.",
    "top_k_tags": 5,
    "top_n_similar": 5
  }'

Notes

This release does not include Docker packaging, Cloud Run deployment, Terraform, or GitHub Actions yet.

The API expects a local model bundle generated by the training pipeline.

v0.3.0 · Inference Foundation

Summary

This release adds the first reusable inference layer for VersoVector.

It introduces a Python inference package capable of loading a generated model bundle and running emotional-semantic analysis on new poems or user-provided text.

Highlights

• Added model bundle loading utilities.
• Added structured inference schemas.
• Added tag prediction logic.
• Added semantic similarity search.
• Added topic and cluster prediction helpers.
• Added PoemAnalyzer as the main inference orchestrator.

Inference Package

src/versovector/inference/
├── artifact_loader.py
├── poem_analyzer.py
├── schemas.py
├── similarity_search.py
├── tag_predictor.py
└── topic_clusterer.py

Main Entry Point

from versovector.inference import PoemAnalyzer

analyzer = PoemAnalyzer.from_bundle("artifacts/model_bundle")

result = analyzer.analyze_dict(
    poem="I walk through the rain carrying a memory of light.",
    top_k_tags=5,
    top_n_similar=5,
)

Notes

This release does not train models.

The inference layer expects a local model bundle generated by the MLOps training pipeline:

artifacts/model_bundle/

Generated model artifacts are not included in the repository.

v0.2.0 · MLOps Training Foundation

Summary

This release adds the first script-based MLOps training foundation for VersoVector.

The main goal is to move beyond notebook-only experimentation by introducing reproducible training entrypoints under src/versovector/training.

Highlights

• Added script-based training pipeline structure.
• Added dataset building script.
• Added feature pipeline training script.
• Added supervised training script.
• Added unsupervised training script.
• Added model bundle registration script.
• Added optional MLflow helper utilities.
• Updated artifact handling and .gitignore rules for generated model outputs.

Training Scripts

src/versovector/training/
├── build_dataset.py
├── train_features.py
├── train_supervised.py
├── train_unsupervised.py
├── register_model.py
└── mlflow_utils.py

MLOps Direction

This release establishes the training-side foundation for:

• reproducible script execution;
• optional MLflow experiment tracking;
• model artifact generation;
• model bundle packaging;
• future CI/CD automation.

Notes

This release does not include the inference package or FastAPI serving layer yet.

Generated artifacts under artifacts/, local MLflow runs, and large binary files remain intentionally excluded from Git.

v0.1.0 · Notebook-to-MLOps Baseline

Summary

This release establishes the first baseline of VersoVector as a notebook-driven NLP project transitioning toward an MLOps architecture.

It captures the initial analytical foundation for poetry embeddings, clustering, supervised classification, and emotional-semantic exploration.

Highlights

• Added the initial notebook-based modeling workflow.
• Introduced the poetry analysis pipeline as the foundation for future MLOps work.
• Established the first bridge between exploratory notebooks and scriptable training.
• Started positioning VersoVector as an emotional-semantic recommendation project for poetic and lyrical language.

Scope

This version is primarily exploratory and research-oriented.

It focuses on:

• dataset cleaning;
• feature extraction;
• supervised and unsupervised modeling;
• early semantic similarity exploration;
• notebook-based validation.

Notes

This release does not include a production API, model bundle contract, Docker packaging, or CI/CD automation yet.

Generated model artifacts and local datasets are not intended to be versioned in Git.