openapi_spec.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "KCSC Construction Standards RAG API",
    "description": "한국건설기준(KDS/KCS/LHCS/SMCS) 초정밀 조항 및 증거(RAG) 검색 API",
    "version": "0.2.0"
  },
  "servers": [
    {
      "url": "https://nicefree19-kcsc-mcp-.hf.space",
      "description": "KCSC RAG 클라우드 실무 운영 서버 (Hugging Face Spaces)"
    }
  ],
  "paths": {
    "/search/clause": {
      "post": {
        "tags": [
          "RAG Search"
        ],
        "summary": "조항 단위 RAG 검색",
        "description": "자연어 질의를 바탕으로 15만 개 건설기준 조항 중 최적의 원문 근거(Evidence)와 공식 웹 링크를 찾아냅니다.",
        "operationId": "search_clause",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 500,
                    "description": "실무 자연어 질의 (예: 고장력 볼트 조임 순서)"
                  },
                  "limit": {
                    "type": "integer",
                    "default": 5,
                    "minimum": 1,
                    "maximum": 10,
                    "description": "반환할 최대 조항 개수"
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          },
          "responses": {
            "200": {
              "description": "검색 성공",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "query": {
                        "type": "string"
                      },
                      "count": {
                        "type": "integer"
                      },
                      "results": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string"
                            },
                            "section": {
                              "type": "string"
                            },
                            "source_location": {
                              "type": "string"
                            },
                            "evidence_text": {
                              "type": "string"
                            },
                            "relevance": {
                              "type": "number"
                            },
                            "official_url": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/assist/response-draft": {
      "post": {
        "tags": [
          "RAG Assist"
        ],
        "summary": "실무 대응 초안 및 고위험 심층 검토서 작성",
        "description": "자연어 질의와 프로젝트 상황(Scenario)을 결합하여, 책임기술자 수준의 정밀 대응 가이드 및 위험 진단 체크리스트를 자동 작성합니다.",
        "operationId": "response_draft",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 500,
                    "description": "실무 자연어 질의"
                  },
                  "scenario": {
                    "type": "string",
                    "maxLength": 1200,
                    "description": "현장의 파손 상태, 부재 정보 등 구체적인 상황적 설명"
                  },
                  "limit": {
                    "type": "integer",
                    "default": 5,
                    "minimum": 1,
                    "maximum": 10
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          },
          "responses": {
            "200": {
              "description": "검토서 작성 성공",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "query": {
                        "type": "string"
                      },
                      "draft": {
                        "type": {
                          "type": "object",
                          "properties": {
                            "confidence": {
                              "type": "string"
                            },
                            "review_required": {
                              "type": "boolean"
                            },
                            "recommended_actions": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "additional_checks": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "answer_markdown": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}