To keep the core API sleek while providing advanced features like the relationship graph and pairwise similarity matrix, we can add an optional query parameter to enable these advanced features. This way, users can request these extra outputs without cluttering the basic functionality.

For a breakdown into individual tasks and progress, see this Kanban board

Here’s an updated version of the API specification with advanced options:

SimScore API Specification (with Advanced Features)

Base URL

https://api.simscore.com

Endpoints

  1. POST /rank-ideas

    This endpoint will accept a list of subjective opinions (ideas), calculate similarity scores, assign clusters, and optionally include advanced outputs such as the relationship graph and pairwise similarity matrix.

Request Body (Input)

{
  "ideas": [
    {"id": 1, "author_id": "user1", "idea": "Idea 1 description"},
    {"id": 2, "author_id": "user2", "idea": "Idea 2 description"},
    {"id": 3, "author_id": "userN", "idea": "Idea 3 description"},
    ...
  ],
  "advanced_features": {
    "relationship_graph": false,
    "pairwise_similarity_matrix": false,
    "cluster_names": false,
  }
}

Response Body (Output)

{
  "ranked_ideas": [
    {"id": 1, "author_id": "user1", "idea": "Idea 1 description", "similarity_score": 0.85, "cluster_id": 1},
    {"id": 2, "author_id": "userX", "idea": "Idea 2 description", "similarity_score": 0.78, "cluster_id": 2},
    {"id": 3, "author_id": "user1", "idea": "Idea 3 description", "similarity_score": 0.72, "cluster_id": 1},
    ...
  ],
  "relationship_graph": {
    "nodes": [
      {"id": 1, "coordinates": {"x":0.2, "y": 0.5}},
      {"id": 2, "coordinates": {"x":-0.4, "y": 0.7}},
      {"id": 3, "coordinates": {"x":0.8, "y": -0.9}}
    ],
    "edges": [
      {"from": 1, "to": 2, "weight": 0.85},
      {"from": 1, "to": 3, "weight": 0.75}
    ]
  },
  "pairwise_similarity_matrix": [
    [1.0, 0.85, 0.72],
    [0.85, 1.0, 0.78],
    [0.72, 0.78, 1.0]
  ],
  "cluster_names": [
	  {"id": 1, "name": "Cluster One"},
	  {"id": 2, "name": "Second"},
	  {"id": 3, "name": "Third cluster"},
  ]
}