From cb653cb888a3d58f4334e46182039521f7a97f97 Mon Sep 17 00:00:00 2001
From: Josh XT <josh@devxt.com>
Date: Sun, 5 Jan 2025 10:48:36 -0500
Subject: [PATCH] add chain docs

---
 agixt/endpoints/Chain.py | 57 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/agixt/endpoints/Chain.py b/agixt/endpoints/Chain.py
index c3478d421ed2..a249713bf129 100644
--- a/agixt/endpoints/Chain.py
+++ b/agixt/endpoints/Chain.py
@@ -1,5 +1,6 @@
 from fastapi import APIRouter, HTTPException, Depends, Header
 from ApiClient import Chain, verify_api_key, get_api_client, is_admin
+from typing import List, Dict
 from XT import AGiXT
 from Models import (
     RunChain,
@@ -10,13 +11,21 @@
     StepInfo,
     ChainStep,
     ChainStepNewInfo,
+    ChainDetailsResponse,
     ResponseMessage,
 )
 
 app = APIRouter()
 
 
-@app.get("/api/chain", tags=["Chain"], dependencies=[Depends(verify_api_key)])
+@app.get(
+    "/api/chain",
+    tags=["Chain"],
+    dependencies=[Depends(verify_api_key)],
+    response_model=List[str],
+    summary="Get all chains",
+    description="Retrieves a list of all available chains for the authenticated user and global chains.",
+)
 async def get_chains(user=Depends(verify_api_key), authorization: str = Header(None)):
     if is_admin(email=user, api_key=authorization) != True:
         raise HTTPException(status_code=403, detail="Access Denied")
@@ -25,7 +34,12 @@ async def get_chains(user=Depends(verify_api_key), authorization: str = Header(N
 
 
 @app.get(
-    "/api/chain/{chain_name}", tags=["Chain"], dependencies=[Depends(verify_api_key)]
+    "/api/chain/{chain_name}",
+    tags=["Chain"],
+    dependencies=[Depends(verify_api_key)],
+    response_model=Dict[str, ChainDetailsResponse],  # New model needed
+    summary="Get chain details",
+    description="Retrieves detailed information about a specific chain, including all steps and configurations.",
 )
 async def get_chain(chain_name: str, user=Depends(verify_api_key)):
     chain_data = Chain(user=user).get_chain(chain_name=chain_name)
@@ -121,6 +135,9 @@ async def run_chain_step(
     "/api/chain/{chain_name}/args",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=Dict[str, List[str]],
+    summary="Get chain arguments",
+    description="Retrieves the list of available arguments for a specific chain.",
 )
 async def get_chain_args(
     chain_name: str, user=Depends(verify_api_key), authorization: str = Header(None)
@@ -131,7 +148,14 @@ async def get_chain_args(
     return {"chain_args": chain_args}
 
 
-@app.post("/api/chain", tags=["Chain"], dependencies=[Depends(verify_api_key)])
+@app.post(
+    "/api/chain",
+    tags=["Chain"],
+    dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Create new chain",
+    description="Creates a new empty chain with the specified name.",
+)
 async def add_chain(
     chain_name: ChainName,
     user=Depends(verify_api_key),
@@ -143,7 +167,14 @@ async def add_chain(
     return ResponseMessage(message=f"Chain '{chain_name.chain_name}' created.")
 
 
-@app.post("/api/chain/import", tags=["Chain"], dependencies=[Depends(verify_api_key)])
+@app.post(
+    "/api/chain/import",
+    tags=["Chain"],
+    dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Import chain",
+    description="Imports a chain configuration including all steps and settings.",
+)
 async def importchain(
     chain: ChainData, user=Depends(verify_api_key), authorization: str = Header(None)
 ) -> ResponseMessage:
@@ -159,6 +190,9 @@ async def importchain(
     "/api/chain/{chain_name}",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Rename chain",
+    description="Renames an existing chain to a new name.",
 )
 async def rename_chain(
     chain_name: str,
@@ -178,6 +212,9 @@ async def rename_chain(
     "/api/chain/{chain_name}",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Delete chain",
+    description="Deletes a chain and all its associated steps.",
 )
 async def delete_chain(
     chain_name: str, user=Depends(verify_api_key), authorization: str = Header(None)
@@ -192,6 +229,9 @@ async def delete_chain(
     "/api/chain/{chain_name}/step",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Add chain step",
+    description="Adds a new step to an existing chain with specified configurations.",
 )
 async def add_step(
     chain_name: str,
@@ -216,6 +256,9 @@ async def add_step(
     "/api/chain/{chain_name}/step/{step_number}",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Update chain step",
+    description="Updates the configuration of an existing step in the chain.",
 )
 async def update_step(
     chain_name: str,
@@ -242,6 +285,9 @@ async def update_step(
     "/api/chain/{chain_name}/step/move",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Move chain step",
+    description="Changes the position of a step within the chain by updating its step number.",
 )
 async def move_step(
     chain_name: str,
@@ -265,6 +311,9 @@ async def move_step(
     "/api/chain/{chain_name}/step/{step_number}",
     tags=["Chain"],
     dependencies=[Depends(verify_api_key)],
+    response_model=ResponseMessage,
+    summary="Delete chain step",
+    description="Removes a specific step from the chain.",
 )
 async def delete_step(
     chain_name: str,