Feat/addtional fast apis for non-streaming simulation and managing relationshio

[XuhuiZhou]

Add additional fastAPI to align with the Sotopia-S4 paper

Closes #

📑 Description

✅ Checks

• My pull request adheres to the code style of this project
• My code requires changes to the documentation
• I have updated the documentation as required
• All the tests have passed
• Branch name follows type/descript (e.g. feature/add-llm-agents)
• Ready for code review

ℹ Additional Information

[ProKil]

It seems that this API would only return after the whole episode is run. A better design is to return an episode id immediately, and the user can check the episode's status via following calls.

[ProKil]

You add the arun_one_episode into background tasks.

[XuhuiZhou]

? Not quite sure if I follow here, are you referring to constantly saving episodes when each msg is produced?

You add the arun_one_episode into background tasks.
what does this mean?

[ProKil]

So right now, the episode_pk is returned after the simulation is done. But this takes long to return to the client. So a better way is to return an episode_pk immediately, and run arun_one_episode in the background. Here is the pseudocode:

@app.post("/simulate/", response_model=str)
async def simulate(simulate_request: SimulateRequest) -> str:
    ...
    episode_pk = EpisodeLog().pk
    asyncio.create_task(arun_one_episode(..., episode_pk=episode_pk)) # update arun_one_episode to take an extra arg: episode_pk
    return episode_pk

async def arun_one_episode(..., episode_pk: str):
    # run simulation
    ....
    # finish simulation
    episode_log.pk = episode_pk
    episode_log.save()

[ProKil]

A step after this is to add a simulation status:

class SimulationStatus(JsonModel):
    episode_pk: str = Field(index)
    status: Literal["Started", "Error", "Completed"]

@app.get("/episodes/{episode_pk}")
class get_episode(episode_pk):
    status = SimulationStatus.find(SimulationStatus.episode_pk == episode_pk)
    if status.status in ["Started", "Error"]:
        return ....
    elif status.staus in ["Completed"]:
        return ...

[XuhuiZhou]

Updated the simulation status and made sure every simulation call would return an episode pk

I don't quite follow tho, about the asyncio.create_task one as users won't be able to check the episode until the task is done either way, and the current async implementation of the async def simulate(simulate_request: SimulateRequest) won't block any process?

Like people can still batch the simulate API call?

[ProKil]

Normally, when dealing with long-running requests, the standard way is to give client a fast response (202). Here are some references:

1. https://learn.microsoft.com/en-us/azure/architecture/patterns/async-request-reply
2. 202 (Accepted) as return code https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.3

Here is what Claude generates for me as an example workflow

POST /api/tasks
> 202 Accepted
{
    "task_id": "abc123",
    "status_url": "/api/tasks/abc123"
}

GET /api/tasks/abc123
> 200 OK
{
    "status": "processing",
    "progress": 45
}

GET /api/tasks/abc123
> 200 OK
{
    "status": "completed",
    "result": { ... }
}

[XuhuiZhou]

@ProKil I see,

[ProKil]

Can you also make the PR name more informative? Like APIs related to what functions?