Implement API functions for architecture and services by yussufsh · Pull Request #689 · IBM/project-ai-services

yussufsh · 2026-04-29T17:26:20Z

This implements catalog API system for managing AI service architectures and services. The following APIs are implemented with swagger docs.

GET /architectures - List all architectures (summary view)
GET /architectures/:id - Get architecture details
GET /services - List deployable services (excludes dependency-only)
GET /services/:id - Get service details

Key Changes:

New Core Catalog functions - catalog.go
API Server Implementation
Type Definitions - Architecture and Service types for detail views
Swagger Documentation (Auto-generated by Bob)
Template Provider Enhancements

Signed-off-by: Yussuf Shaikh <yussuf.shaikh1@ibm.com>

yussufsh · 2026-04-29T17:38:47Z

=== API 1: List Architectures ===

[
  {
    "id": "rag",
    "name": "Digital Assistant",
    "description": "Enable digital assistants using Retrieval-Augmented Generation (RAG), including AI services that query a managed knowledge base to answer questions from custom documents and data.",
    "certified_by": "IBM",
    "services": [
      "chat",
      "digitize",
      "summarize"
    ]
  }
]

=== API 2: Get Architecture Details (rag) ===

{
  "id": "rag",
  "name": "Digital Assistant",
  "description": "Enable digital assistants using Retrieval-Augmented Generation (RAG), including AI services that query a managed knowledge base to answer questions from custom documents and data.",
  "version": "1.0.0",
  "type": "architecture",
  "certified_by": "IBM",
  "runtimes": [
    "podman"
  ],
  "services": [
    {
      "id": "chat",
      "version": ">=1.0.0"
    },
    {
      "id": "digitize",
      "version": ">=1.0.0"
    },
    {
      "id": "summarize",
      "version": ">=1.0.0",
      "optional": true
    }
  ],
  "links": {
    "demo": "https://example.com/demo/rag",
    "code": "https://github.com/project-ai-services/spyre-rag",
    "documentation": "https://docs.example.com/rag"
  }
}

yussufsh · 2026-04-29T17:39:27Z

=== API 3: List Services ===

[
  {
    "id": "chat",
    "name": "Question and Answer",
    "description": "Answer questions in natural language by sourcing general & domain-specific knowledge",
    "certified_by": "IBM",
    "architectures": [
      "rag"
    ]
  },
  {
    "id": "digitize",
    "name": "Digitize Documents",
    "description": "Transforms documents such as manuals, invoices, and more into texts",
    "certified_by": "IBM",
    "architectures": [
      "rag"
    ]
  },
  {
    "id": "summarize",
    "name": "Summarize",
    "description": "Consolidates input text into a brief statement of main points",
    "certified_by": "IBM",
    "architectures": [
      "rag"
    ]
  }
]

=== API 4: Get Service Details (chat) ===

{
  "id": "chat",
  "name": "Question and Answer",
  "description": "Answer questions in natural language by sourcing general & domain-specific knowledge",
  "type": "service",
  "certified_by": "IBM",
  "architectures": [
    "rag"
  ],
  "dependencies": [
    {
      "id": "opensearch",
      "version": ">=1.0.0"
    },
    {
      "id": "embedding",
      "version": ">=1.0.0"
    },
    {
      "id": "instruct",
      "version": ">=1.0.0"
    },
    {
      "id": "reranker",
      "version": ">=1.0.0"
    }
  ]
}

mayuka-c · 2026-04-30T02:53:09Z

+package handlers
+
+import (
+	"encoding/json"
+	"net/http"


I dont think we need test file as we are not writing any UTs now. Can we remove?

mayuka-c · 2026-04-30T02:55:31Z

+	Version     string             `yaml:"version" json:"version"`
+	Type        string             `yaml:"type" json:"type"` // "architecture"
+	CertifiedBy string             `yaml:"certified_by" json:"certified_by"`
+	Runtimes    []string           `yaml:"runtimes" json:"runtimes"`


We do not require runtimes

mayuka-c · 2026-04-30T02:57:35Z

+	Description    string                `yaml:"description" json:"description"`
+	Type           string                `yaml:"type" json:"type"` // "service"
+	CertifiedBy    string                `yaml:"certified_by" json:"certified_by"`
+	DependencyOnly bool                  `yaml:"dependency_only,omitempty" json:"dependency_only,omitempty"`


Do we need this dependency_only in response?. I thought by default we are filtering out the Infra services like Opensearch, models

mayuka-c

Here are my initial comments
I will take a look at the internal logic sometime later as there are lot of things :)

mayuka-c · 2026-04-30T05:02:16Z

+	for _, id := range serviceIDs {
+		service, err := LoadService(id)
+		if err != nil {
+			// Log error but continue with other services


Can we log the error to know the reason why load failed as I see we are simply doing continue

mayuka-c · 2026-04-30T05:05:30Z

+
+// GetDeploymentOrder returns services grouped into deployment layers
+// Services in the same layer can be deployed in parallel
+func GetDeploymentOrder(serviceIDs []string) ([][]string, error) {


Can we add some example on how the resultant of this method look like as it is 2D slice. Will be easier to know how it looks

Shubhamag12 · 2026-04-30T11:53:37Z

+	for _, id := range archIDs {
+		arch, err := LoadArchitecture(id)
+		if err != nil {
+			// Log error but continue with other architectures


we are not logging error here
maybe collect all errors here and print after loop ends?

Shubhamag12 · 2026-04-30T12:11:37Z

+	if visited[serviceID] {
+		return nil
+	}


can you help me understand this part please?

since we are returning nil here, wouldnt it pass if graph has cyclic dependency?
Suppose there are 2 services; S1 and S2
S1 depends on S2
S2 depends on S1

S1 -> not visited -> mark visited
S2 -> not visited -> mark visited
S1 -> visited -> return nil (skipping the cycle here)
append S2 -> [S2]
append S1 -> [S2, S1]

is the aim here to find all unique transitive deps (and ignoring cycles), or to prevent cycles?

Shubhamag12 · 2026-04-30T12:16:05Z

+
+// GetDeploymentOrder returns services grouped into deployment layers
+// Services in the same layer can be deployed in parallel
+func GetDeploymentOrder(serviceIDs []string) ([][]string, error) {


Shubhamag12 · 2026-04-30T12:19:33Z

+func ToServiceSummary(service *types.Service) types.ServiceSummary {
+	return types.ServiceSummary{
+		ID:            service.ID,
+		Name:          service.Name,
+		Description:   service.Description,
+		CertifiedBy:   service.CertifiedBy,
+		Architectures: service.Architectures,
+	}
+}
+
+// ToArchitectureSummary converts an Architecture to ArchitectureSummary
+func ToArchitectureSummary(arch *types.Architecture) types.ArchitectureSummary {
+	// Extract just the service IDs as strings
+	services := make([]string, len(arch.Services))
+	for i, svc := range arch.Services {
+		services[i] = svc.ID
+	}
+
+	return types.ArchitectureSummary{
+		ID:          arch.ID,
+		Name:        arch.Name,
+		Description: arch.Description,
+		CertifiedBy: arch.CertifiedBy,
+		Services:    services,
+	}
+}


should we move these data transformers to types.go?

Implement API functions for architecture and services

25dd4c9

Signed-off-by: Yussuf Shaikh <yussuf.shaikh1@ibm.com>

yussufsh force-pushed the apis_new branch from a0a3e84 to 25dd4c9 Compare April 29, 2026 17:28

yussufsh requested a review from mayuka-c April 29, 2026 17:32

mayuka-c reviewed Apr 30, 2026

View reviewed changes

Shubhamag12 reviewed Apr 30, 2026

View reviewed changes

yussufsh marked this pull request as draft April 30, 2026 12:30

Conversation

yussufsh commented Apr 29, 2026

Uh oh!

yussufsh commented Apr 29, 2026

Uh oh!

yussufsh commented Apr 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mayuka-c left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants