WhyHow Knowledge Graph Studio

After configuring collections, you must create a user to obtain an API Key. This key is required to communicate with the backend via the SDK.

Run the following from src/whyhow_api/cli/:

$ python admin.py create-user --email <your email address> --openai-key <your openai api key>

Important: Copy the API Key provided in the output message immediately, as you will need it to configure the WhyHow client.

Use the provided admin script to create the necessary database collections and indexes in your MongoDB Atlas cluster. This script creates 11 collections: chunk, document, graph, node, query, rule, schema, task, triple, user, and workspace.

Run the following command from the src/whyhow_api/cli/ directory:

$ cd src/whyhow_api/cli/
$ python admin.py setup-collections --config-file collection_index_config.json

Start the API server using uvicorn. You can use the whyhow-locate utility to automatically resolve the correct path to the application.

Standard launch:

$ uvicorn src.whyhow_api.main:app

Using the utility script:

$ uvicorn $(whyhow-locate)

Once running, you can access the Swagger UI documentation at http://localhost:8000/docs.

To install the Knowledge Graph Studio package, clone the repository and install via pip. This client requires Python 3.10 or higher.

For standard installation:

$ git clone git@github.com:whyhow-ai/knowledge-graph-studio.git
$ cd knowledge-graph-studio
$ pip install .

For developers requiring an editable install with development and documentation dependencies:

$ pip install -e .[dev,docs]

Before running the API, you must configure your environment variables. Copy the sample file to .env:

$ cp .env.sample .env

At a minimum, the following environment variables must be set:

• WHYHOW__EMBEDDING__OPENAI__API_KEY: Your OpenAI API key for embeddings.
• WHYHOW__GENERATIVE__OPENAI__API_KEY: Your OpenAI API key for generative tasks.
• WHYHOW__MONGODB__USERNAME: Your MongoDB Atlas username.
• WHYHOW__MONGODB__PASSWORD: Your MongoDB Atlas password.
• WHYHOW__MONGODB__DATABASE_NAME: The name of your database (e.g., main).
• WHYHOW__MONGODB__HOST: Your MongoDB Atlas host (e.g., xxx.xxx.mongodb.net).

You can containerize the backend using Docker. Ensure you have completed the environment configuration and user creation steps first.

Build the image:

$ docker build --platform=linux/amd64 -t kg_engine:v1 .

Run the image: Map the internal port 8000 to your desired host port using the OUTSIDE_PORT variable.

$ OUTSIDE_PORT=1234
$ docker run -it --rm -p $OUTSIDE_PORT:8000 kg_engine:v1

The WhyHow API is organized into several functional routers. When interacting with the API, you will use endpoints managed by these routers to perform operations on the following entities:

• workspaces: Manage isolated environments.
• schemas: Define data structures.
• graphs: Manage knowledge graph structures.
• triples: Handle subject-predicate-object relationships.
• nodes: Manage individual entities in the graph.
• documents: Manage source documents.
• chunks: Manage text segments from documents.
• users: Manage user accounts.
• queries: Execute searches or graph traversals.
• rules: Define logic or constraints.
• tasks: Manage asynchronous or background operations.

Documents in WhyHow support two types of metadata:

1. System Metadata (DocumentMetadata): Contains intrinsic file properties like size, format (e.g., pdf, csv, json, txt), and filename.
2. User Metadata (user_metadata): A flexible dictionary allowing users to attach custom structured data. The schema for user_metadata follows a nested structure: dict[str, dict[str, AllowedUserMetadataTypes | list[AllowedUserMetadataTypes]]].

You can update these fields using the DocumentUpdate model, which allows for partial updates to user_metadata and tags.

The API uses MongoDB ObjectIds for entity identification. When interacting with the API, IDs are often represented as strings, but the underlying system validates them as ObjectId types.

• AfterAnnotatedObjectId: A type that accepts either a str or an ObjectId. It automatically converts input to a string and then validates that the string is a valid BSON ObjectId.
• Validation Error: If an invalid string is provided where an ID is expected, the API will raise a ValueError stating that the value is not a valid ObjectId.

The API returns different representations of triples depending on the endpoint and visibility requirements:

1. TripleOut: The full internal representation of a triple. Includes id (aliased from _id), head_node ID, tail_node ID, type, properties, graph ID, created_by ID, and associated chunks IDs.
2. TripleWithId: A detailed response containing the full NodeWithId objects for both the head_node and tail_node, along with a RelationOut object (containing the relation name and properties).
3. PublicTripleWithId: A version of the detailed response that provides NodeWithId objects for the head and tail but uses a simplified RelationOut structure, typically used for public-facing graph queries.

The MongoDB configuration is managed via SettingsMongoDB. To successfully generate a connection URI using the .uri property, you must provide username, password, and host.

Required Fields:

• username: The MongoDB username.
• password: The MongoDB password (handled as a SecretStr).
• host: The MongoDB host address.

Other available fields:

• database_name: The name of the database.
• chunk_collection_name: The name of the collection for chunks (defaults to "chunk").
• vector_search_embedding_size: The size of the embedding vectors (defaults to 1536).

# Example environment variables for MongoDB
WHYHOW__MONGODB__USERNAME=myuser
WHYHOW__MONGODB__PASSWORD=mypassword
WHYHOW__MONGODB__HOST=cluster0.mongodb.net
WHYHOW__MONGODB__DATABASE_NAME=whyhow_db