HTTP API is poorly documented

[elimydlarz]

I'm having a lot of trouble using the HTTP server. It has some concepts not explained in the client docs (e.g. "group_id"), and is missing endpoints for client methods (e.g. it has an endpoint to add messages, which the client doesn't have, but it is missing an endpoint to add episodes, which the client docs seem to focus on).

Is there documentation available for this? The API documentation included also isn't very helpful, with minimal descriptive information and some use of "any" instead of more specific typing.

I don't mean to be critical - really excited about this project, but finding a lot of friction so far.

[paul-paliychuk]

@elimydlarz Hi, thanks for raising the issue. The documentation for the fast api service and group_id parameter is still work in progress.

Some context here - the http server is the service we use in Zep Community project to connect to Graphiti. It does not expose all methods that Graphiti client has, but rather exposes the methods that we need on Zep to implement Graphiti. In the graphiti package context this service is designed to serve as an example of that the fast api server implementing Graphiti package could look like.

The group id field is designed to indicate the graph partition the episode (or message) belongs to. For example, you might want to have independent graph partitions for different users/groups of users. Adding episodes (and then searching Graphiti) with a specific group_id will prevent context from leaking between partitions.

In Graphiti package the group_id argument is optional, so you don't have to use it if your use case does not require graph partitions.

I recognize the fact that in the fast api service we have the group_id a required field in DTO, you may use an empty string or default for the time being if you don't have the use case for partitions.

[elimydlarz]

Thanks for the valuable context! It's really helpful for me.

I don't want to be picky - I really appreciate that you've open-sourced this. But as a developer I want to try and provide some useful feedback if I can. In that spirit: You're providing Graphiti as a single Python client that wraps Neo4J with your special logic and API, but this makes it difficult for you to - for example - produce clients in other languages. If you build that logic and API into a standalone server (as you have begun to do for Zep, in the example we discussed above) rather than a library, you can in turn automatically generate clients in virtually every language automatically based on the API specifications of that server, which will in turn allow you to give virtually all developers access to Graphiti.

I'm building a Deno project, what do you suggest I do going forward?

• Give up on Graphiti, as there is only a Python client
• Learn Python and extend your server to match client functionality, by just wrapping client methods in endpoints
• Run your Python client in Deno using this

[paul-paliychuk]

@elimydlarz You are raising very valid points! Graphiti service could definitely helpful to the people who don't have a python service set up / don't really have a need for one outside of Graphiti.

This actually prompted an internal convo, we are in the process of making the graphiti service (the fast api server) better documented and more complete in terms of the methods it exposes from the graphiti package. Additionally, we will be removing the Zep specific terminology from graphiti service making way for more generic constructs from Graphiti to make the service independent. That applies to making group_id an optional field as well.

I think that the easiest option to run use Graphiti from deno environment, would be to start up Graphiti service as a docker image. Deno python runtime sounds promising as well, but I haven't got any experience with it, so can't really attest to how easy it would be to set up.

[elimydlarz]

Yep, I've been able to continue with the server thanks to your advice here.

I'm also having an intermittent failure problem when adding messages. The failures succeed on the first retry, even if the retry is immediate. It's not impactful for me yet - I'm at the experimental stage, so retrying automatically is still tolerable. Here's a log:

error: Uncaught (in promise) TypeError: error sending request from [::1]:61514 for http://localhost:8000/messages ([::1]:8000): client error (SendRequest): connection closed before message completed
  const response = await fetch("http://localhost:8000/messages", {
                   ^
    at async mainFetch (ext:deno_fetch/26_fetch.js:170:12)
    at async fetch (ext:deno_fetch/26_fetch.js:392:7)

I'm using Docker, as you suggest. Here's my compose file:

services:
   graphiti:
      image: zepai/graphiti:latest
      ports:
         - "8000:8000"
      environment:
         - OPENAI_API_KEY=${OPENAI_API_KEY}
         - NEO4J_URI=bolt://neo4j:${NEO4J_PORT}
         - NEO4J_USER=${NEO4J_USER}
         - NEO4J_PASSWORD=${NEO4J_PASSWORD}
   neo4j:
      image: neo4j:5.22.0
      ports:
         - "7474:7474"
         - "${NEO4J_PORT}:${NEO4J_PORT}"
      volumes:
         - neo4j_data:/data
      environment:
         - NEO4J_AUTH=${NEO4J_USER}/${NEO4J_PASSWORD}
volumes:
   neo4j_data:

Should I post another issue? I don't want to bother you about every little thing, but maybe it's an important one 🤔

I appreciate the work you are doing to open-source this - and your responsiveness here - so much <3 Let me know if I can help somehow.