# Forge-AI-Service

Forge-AI-Service is a Python/FastAPI service that provides AI-assisted merchandise and product-lifecycle workflows for Merchmix Forge. It combines Azure OpenAI text and image generation, Azure AI Vision embeddings, tenant and product data retrieval, planning analytics, taxonomy validation, duplicate detection, and deterministic merchandising calculations behind HTTP APIs. It is packaged as a container and deployed to Azure Container Apps.

## Business Summary

This service helps retail teams create and improve product information faster. It can suggest new product concepts, descriptions, attributes, colors, and tags; generate product imagery and technical-pack content; find similar products from an image; identify duplicate products; recommend sizes and unit depth; assess markdown risk; and turn market and competitor data into product research recommendations.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| AI-Assisted Product Concept Creation | Products | `production` | `execute` | user_facing |
| Product Style Assistance | Products | `production` | `execute` | user_facing |
| AI Product Content Generation | Products | `production` | `execute` | user_facing, agent_facing |
| AI Product Image Generation | Products | `production` | `execute` | user_facing |
| Technical Pack Generation | Products | `production` | `execute` | user_facing |
| Product Duplicate Detection | Products | `production` | `read` | user_facing, agent_facing |
| Product Duplication Planning | Products | `production` | `execute` | user_facing |
| Natural-Language Product Editing | Products | `production` | `execute` | user_facing |
| Product Tag Suggestion | Products | `production` | `execute` | user_facing |
| Visual Product and Catalog Search | Products | `production` | `read` | user_facing, agent_facing |
| Merchandising Research and Demand Whitespace Analysis | Research | `production` | `read` | user_facing, agent_facing |
| Size Curve Recommendation | Planning | `production` | `execute` | user_facing, agent_facing |
| Size Depth Recommendation | Planning | `production` | `execute` | user_facing, agent_facing |
| Markdown Risk Assessment | Planning | `production` | `execute` | user_facing, agent_facing |
| Conversational AI Assistance | Other | `production` | `execute` | user_facing, agent_facing |

**AI-Assisted Product Concept Creation** — Generates proposed product concepts and related product details from merchandiser input, references, links, and images.

**Product Style Assistance** — Suggests and enriches product styles for merchandisers, including category, department, season, attributes, commercial bands, and duplicate warnings.

**AI Product Content Generation** — Creates several concise alternatives for product descriptions, internal comments, and creative themes based on existing record information.

**AI Product Image Generation** — Creates product, colorway, and sales-channel images for use in ecommerce, marketplaces, point of sale, and wholesale materials.

**Technical Pack Generation** — Drafts technical product documentation from product details and optional reference imagery, reducing manual preparation for product development.

**Product Duplicate Detection** — Checks whether a proposed product is already represented in the tenant catalog before creation or import.

**Product Duplication Planning** — Interprets a merchandiser's instructions for copying an existing product and prepares a proposed duplicate for confirmation.

**Natural-Language Product Editing** — Converts a merchandiser's instruction for changing an existing product into a structured edit proposal.

**Product Tag Suggestion** — Suggests useful product tags from uploaded images and referenced catalog items.

**Visual Product and Catalog Search** — Finds visually similar products, materials, colors, suppliers, and other catalog objects from an uploaded image, with tenant-specific filters.

**Merchandising Research and Demand Whitespace Analysis** — Combines demand, competitor, social, keyword, pricing, and taxonomy information to highlight market opportunities and recommend product directions.

**Size Curve Recommendation** — Recommends how total planned units should be distributed across sizes for a category and customer context.

**Size Depth Recommendation** — Recommends how deeply a retailer should buy a product or category based on the supplied merchandising context and unit requirement.

**Markdown Risk Assessment** — Estimates markdown risk for a product or category so planners can identify items likely to require price reductions.

**Conversational AI Assistance** — Provides a general authenticated chat capability for Forge users and workflows.

## Workflows

**AI-assisted style or concept creation** — Builds a product proposal while grounding AI suggestions in the tenant's actual merchandising configuration.

1. Receive product or concept input, references, links, images, and tenant context.
2. Resolve tenant schema, taxonomy, brands, seasons, and relevant planning data.
3. Generate draft product/style fields with Azure OpenAI and image analysis where applicable.
4. Calculate or retrieve cost, margin, demand, markdown, and markdown-risk bands.
5. Check for duplicate products and validate suggested attributes.
6. Return a proposal for the user to review.

**Visual catalog search** — Uses an uploaded image to retrieve similar tenant-permitted catalog objects.

1. Discover valid facets for the selected object type.
2. Upload an image with tenant and search parameters.
3. Validate image size, object type, facets, and similarity settings.
4. Create or use visual embeddings and query the Search/assets services.
5. Return visually similar matches.

**Market research recommendation** — Turns tenant market data into demand signals, whitespace gaps, and recommendations.

1. Read competitor, social, keyword, trend, and price-history records from tenant analytics databases.
2. Merge and rank demand signals.
3. Compare demand keywords with the tenant taxonomy to identify whitespace.
4. Provide bounded research data to Azure OpenAI.
5. Return insights and recommendations.

**Technical pack drafting** — Generates selected technical-pack sections while preserving product-owned information.

1. Receive product details, selected sections, optional instructions, and optional image.
2. Build a structured prompt for the requested AI sections.
3. Generate and parse structured JSON through Azure OpenAI.
4. Assemble generated sections with product-owned summary and approved colorway data.
5. Return the technical-pack response.

**Size and commercial risk planning** — Produces planning guidance for size distribution, depth, and markdown exposure.

1. Validate the client and resolve a category/sub-category.
2. Accept manufacturer, gender, price, and unit assumptions.
3. Run the relevant deterministic planning service.
4. Return a size curve, depth recommendation, or markdown risk band.

## Architecture

A modular FastAPI application exposes versioned HTTP routers. Endpoint modules validate requests and coordinate domain services, external API clients, database readers, and Azure AI clients. Most AI operations are proposal or recommendation workflows; product persistence is not implemented in the shown service.

**Components:** app.main: FastAPI application factory and root health response, app.api.v1.router: versioned endpoint registration, app.api.v1.endpoints: chat, AI Studio, style/concept/content assistance, research, planning, duplicate, markdown-risk, technical-pack, and visual-search routes, app.schemas: Pydantic request and response contracts, app.services: style drafting, plan matching, duplicate detection, markdown risk, size curve/depth, taxonomy matching, and visual search logic, app.clients: Azure OpenAI, Azure Vision, Search, Assets, Config, Planning, WSSI, Taxonomy, Reference Catalog, Link Preview, and PostgreSQL database clients, Docker and Bitbucket Pipeline: container build, pytest execution, Azure Container Registry build, and Azure Container Apps deployment

**Patterns:** FastAPI routers with Pydantic validation, Async I/O and concurrent enrichment using asyncio/httpx, External-service client abstraction, Structured JSON prompting and response validation for AI outputs, Tenant-aware taxonomy and configuration resolution, Caller-token forwarding for downstream Forge services, Read-only analytics database access, JWT-protected routes alongside x-forge-context authenticated routes, Bounded bulk requests and uploaded-image size limits

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `http` | `GET / and GET /api/v1/health` | Service and health status endpoints. |
| `http` | `POST /api/v1/chat` | Authenticated conversational Azure OpenAI assistance. |
| `http` | `POST /api/v1/ai-studio/*` | Authenticated product, colorway, channel, and bulk image generation endpoints. |
| `http` | `POST /api/v1/concept-assist/* and POST /api/v1/style-assist/*` | Concept generation, bulk concept generation, tag suggestions, style analysis, and bulk style analysis. |
| `http` | `POST /api/v1/content-assist/generate` | Authenticated generation of description, comment, and theme suggestions. |
| `http` | `POST /api/v1/tech-pack/auto-generate` | Authenticated structured technical-pack generation. |
| `http` | `POST /api/v1/research/recommendations and GET /api/v1/research/demand-whitespace` | Authenticated market recommendations and demand-whitespace analysis. |
| `http` | `POST /api/v1/size-demand/size-curve and POST /api/v1/size-demand/depth-recommendation` | Authenticated size curve and size depth planning recommendations. |
| `http` | `POST /api/v1/product-dedup/check` | Product duplicate matching. |
| `http` | `POST /api/v1/product-duplicate/generate and POST /api/v1/product-edit/generate` | AI-generated product duplication and natural-language edit proposals. |
| `http` | `POST /api/v1/markdown-risk/check` | Markdown risk band calculation. |
| `http` | `GET /api/v1/visual-search/facets and POST /api/v1/visual-search/search` | Tenant-specific visual-search facets and image similarity search. |
| `http` | `POST /computervision/retrieval:vectorizeImage` | Image vectorization route detected in the application surface. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| Product and Style | `reads` | Referenced and proposed product records, including names, categories, seasons, attributes, brands, pricing intent, and SKU structure. |
| Colorway and Product Imagery | `reads` | Product colorways, imagery references, generated images, channel image specifications, and image-derived tags. |
| Taxonomy and Tenant Configuration | `reads` | Tenant category hierarchies, configurable attributes, valid values, brands, departments, and seasons used to constrain AI output. |
| Planning and Commercial Bands | `reads` | Plans, cost bands, margin bands, expected-margin inputs, demand bands, markdown bands, and markdown-risk bands. |
| Duplicate Match Results | `reads` | Potential matching products returned for proposed or existing product information. |
| Technical Pack | `writes` | Generated construction details, measurement instructions, size specifications, bills of materials, packaging/labeling, and product-owned summary/colorway content. |
| Demand and Research Signals | `reads` | Trend keywords, keyword metrics, competitor products, competitor posts, competitor snapshots, social signals, and weekly category price history. |
| Size Recommendations | `writes` | Calculated size curves and depth recommendations based on sales and merchandising inputs. |
| Visual Search Matches | `reads` | Image embeddings and similarity matches across permitted catalog object types such as products, materials, colors, suppliers, RFQs, channels, line plans, and design boards. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| Azure OpenAI | `external_service` | `calls` | `critical` |
| Azure AI Vision | `external_service` | `calls` | `critical` |
| Taxonomy API | `internal_service` | `calls` | `required` |
| Config API | `internal_service` | `calls` | `required` |
| Planning API | `internal_service` | `calls` | `required` |
| WSSI API | `internal_service` | `calls` | `optional` |
| Search API | `internal_service` | `calls` | `required` |
| Assets API | `internal_service` | `calls` | `required` |
| Reference Catalog / Products API | `internal_service` | `reads` | `required` |
| Merchmix Sync PostgreSQL database | `database` | `reads` | `required` |
| Tenant analytics PostgreSQL databases | `database` | `reads` | `required` |
| Link Preview service | `external_service` | `calls` | `supporting` |
| Forge caller authentication | `internal_service` | `authenticates_through` | `required` |

## Technology

Python 3.11+, FastAPI, Uvicorn, Pydantic and pydantic-settings, AsyncIO and httpx, PostgreSQL via asyncpg, Azure Identity DefaultAzureCredential, Azure OpenAI SDK and LangChain OpenAI integrations, Azure AI Vision, PyJWT, Docker, Bitbucket Pipelines, Azure Container Apps

## Limitations

- The scanner shows implementation for proposal, generation, analysis, and recommendation workflows, but no product or catalog write API is shown; generated duplicate/edit proposals appear to require a separate confirmation and persistence flow.
- Some source files and the exact application prefix are truncated or redacted in the evidence, so the complete route surface and exact version-prefix configuration cannot be established.
- Several legacy or compatibility-looking routes are reported by the endpoint scanner without corresponding complete endpoint source in the supplied excerpts; they should not be treated as separate business capabilities without inspecting the remaining files.
- The evidence does not establish model quality, latency, availability, or whether every declared endpoint is enabled in every deployment environment.
- Database ownership is inferred as read-only from configuration comments and client usage; this repository does not appear to own the underlying product, taxonomy, planning, or analytics records.

## Agent Instructions

Use this repository for AI-assisted product lifecycle, merchandise research, visual search, size planning, and markdown-risk workflows. Treat its outputs as proposals, recommendations, analyses, or generated assets unless a separate downstream service explicitly persists them.

- For product creation assistance, prefer concept-assist or style-assist; include tenant context, taxonomy, and client identifiers so results can be validated against real configuration.
- For text-field completion, use content-assist with field_kind set to description, comment, or theme and provide existing record context.
- For product copying or natural-language changes, use product-duplicate or product-edit; do not assume either endpoint mutates the source catalog.
- For visual lookup, call visual-search/facets before search when tenant-specific filters are needed, then send the image with x-forge-context and a valid client_id.
- For size recommendations, always provide or derive a category and sub-category; the size workflows reject category-only context.
- For research recommendations, ensure the client is known and expect results to depend on available tenant analytics and taxonomy data.
- Use JWT bearer authentication for routes whose routers declare require_jwt, and use the caller's x-forge-context token for routes documented in code as forwarding that token downstream.
- Do not send secrets to this service in prompts or payloads. Azure credentials are obtained through managed identity/DefaultAzureCredential, and downstream caller tokens are expected to be forwarded only through their designated headers.

## Source

| Field | Value |
|---|---|
| Repository | `Forge-AI-Service` |
| Branch | `master` |
| Commit | `afd8b51aa3cc` |
| Generated by | `gpt-5.6-luna` |

*Generated by the Merchmix Skills Platform from the current codebase.*