Forge-AI-Service
currentForge-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
15Generates proposed product concepts and related product details from merchandiser input, references, links, and images.
The concept-assist endpoints build product proposals using Azure OpenAI, tenant configuration schemas, taxonomy values, brands and seasons, planning data, reference catalog data, link previews, duplicate checks, margin bands, demand and markdown bands, and image/tag analysis. Bulk generation is also supported.
Suggests and enriches product styles for merchandisers, including category, department, season, attributes, commercial bands, and duplicate warnings.
Style-assist supports single and bulk analysis. It drafts style fields, validates suggested attributes against tenant configuration and taxonomy, retrieves cost, margin, demand, markdown, and markdown-risk bands, and adds duplicate matches.
Creates several concise alternatives for product descriptions, internal comments, and creative themes based on existing record information.
POST /content-assist/generate sends a field-specific prompt to an Azure OpenAI JSON chat client and returns validated suggestion strings for description, comment, or theme fields.
Creates product, colorway, and sales-channel images for use in ecommerce, marketplaces, point of sale, and wholesale materials.
AI Studio endpoints use a dedicated Azure OpenAI image deployment. They support product images, colorway images, bulk colorway generation, channel-specific image specifications, multiple angles, colorways, aspect ratios, and uploaded image inputs.
Drafts technical product documentation from product details and optional reference imagery, reducing manual preparation for product development.
POST /tech-pack/auto-generate uses Azure OpenAI structured JSON generation for selected construction details, how-to-measure instructions, size specifications, bills of materials, and packaging/labeling sections. Summary and approved colorways are passed through from product data rather than generated.
Checks whether a proposed product is already represented in the tenant catalog before creation or import.
POST /product-dedup/check validates the client and calls duplicate matching using category, sub-category, style name, color, brand, and material. Concept and style assistance reuse the same duplicate-detection service.
Interprets a merchandiser's instructions for copying an existing product and prepares a proposed duplicate for confirmation.
POST /product-duplicate/generate retrieves a referenced product, asks Azure OpenAI to determine the new name, season, attribute-copy behavior, colorway-copy behavior, and SKU-structure-copy behavior, and returns a prefilled duplicate proposal rather than creating the product.
Converts a merchandiser's instruction for changing an existing product into a structured edit proposal.
POST /product-edit/generate retrieves product details, current taxonomy, brand options, and tenant configuration, then uses Azure OpenAI to produce a validated edit response. The endpoint does not itself persist the changes.
Suggests useful product tags from uploaded images and referenced catalog items.
Concept-assist tag suggestion functionality accepts image and reference inputs, batches image analysis, and returns image and reference tag suggestions using the Azure vision/AI pipeline.
Finds visually similar products, materials, colors, suppliers, and other catalog objects from an uploaded image, with tenant-specific filters.
POST /visual-search/search validates the image, tenant, object type, facets, result limit, and similarity threshold, then computes or obtains visual matches through Azure Vision and Merchmix Search/assets services. GET /visual-search/facets discovers available filter dimensions.
Combines demand, competitor, social, keyword, pricing, and taxonomy information to highlight market opportunities and recommend product directions.
Research endpoints read tenant analytics databases for competitor products, posts, snapshots, keyword metrics, trend keywords, and weekly category price history. They merge demand signals, identify keywords missing from owned taxonomy, and use Azure OpenAI for recommendations.
Recommends how total planned units should be distributed across sizes for a category and customer context.
POST /size-demand/size-curve resolves a required category/sub-category and calls the size-curve service using client, manufacturer, gender, target MSRP, and total units.
Recommends how deeply a retailer should buy a product or category based on the supplied merchandising context and unit requirement.
POST /size-demand/depth-recommendation calls the size-depth service after resolving and validating category/sub-category context.
Estimates markdown risk for a product or category so planners can identify items likely to require price reductions.
POST /markdown-risk/check computes a markdown risk band using client, category/sub-category, manufacturer, gender, and target MSRP. Category context may be supplied directly or derived from taxonomy match levels.
Provides a general authenticated chat capability for Forge users and workflows.
POST /chat invokes a selected or default Azure OpenAI chat deployment and returns the generated reply. JWT bearer authentication is required.
Workflows
5Builds 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.
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.
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.
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.
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.
Interfaces
13| 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
9| 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
13| 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
Limitations
5- —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.