### Install Python SDK

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Command to install the WhyHow Python package.

```shell
$ pip install whyhow
```

--------------------------------

### Clone Repository and Install Package

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Clone the WhyHow Knowledge Graph Studio repository and install the package. Requires Python 3.10 or higher.

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

--------------------------------

### Install Package with Development Dependencies

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Install the package in editable mode with development and documentation dependencies. This is recommended for developers.

```shell
pip install -e .[dev,docs]
```

--------------------------------

### Launch API Server

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Commands to start the API server using uvicorn.

```shell
$ uvicorn src.whyhow_api.main:app
```

```shell
$ uvicorn $(whyhow-locate)
```

--------------------------------

### Configure and Run WhyHow Client

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Example of initializing the client, creating a workspace, adding chunks and triples, and querying the graph.

```python
from whyhow import WhyHow, Triple, Node, Chunk, Relation

# Configure WhyHow client
client = WhyHow(api_key='<your whyhow api key>', base_url="http://localhost:8000")

# Create workspace
workspace = client.workspaces.create(name="Demo Workspace")

# Create chunk(s)
chunk = client.chunks.create(
    workspace_id=workspace.workspace_id,
    chunks=[Chunk(
        content="preneur and visionary, Sam Altman serves as the CEO of OpenAI, leading advancements in artifici"
    )]
)

# Create triple(s)
triples = [
    Triple(
        head=Node(
            name="Sam Altman",
            label="Person",
            properties={"title": "CEO"}
        ),
        relation=Relation(
            name="runs",
        ),
        tail=Node(
            name="OpenAI",
            label="Business",
            properties={"market cap": "$157 Billion"}
        ),
        chunk_ids=[c.chunk_id for c in chunk]
    )
]

# Create graph
graph = client.graphs.create_graph_from_triples(
    name="Demo Graph",
    workspace_id=workspace.workspace_id,
    triples=triples
)

# Query graph
query = client.graphs.query_unstructured(
    graph_id=graph.graph_id,
    query="Who runs OpenAI?"
)
```

--------------------------------

### Use Python SDK for Knowledge Graph Operations

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Example demonstrating workspace creation, chunking, triple construction, graph building, and querying using the WhyHow Python SDK.

```python
from whyhow import WhyHow, Triple, Node, Chunk, Relation

# Initialize client
client = WhyHow(
    api_key='your-whyhow-api-key',
    base_url="http://localhost:8000"
)

# Create a workspace
workspace = client.workspaces.create(name="Research Knowledge Graph")
print(f"Created workspace: {workspace.workspace_id}")

# Add chunks with text content
chunks = client.chunks.create(
    workspace_id=workspace.workspace_id,
    chunks=[
        Chunk(content="Albert Einstein developed the theory of relativity."),
        Chunk(content="Einstein won the Nobel Prize in Physics in 1921."),
        Chunk(content="The theory of relativity revolutionized modern physics.")
    ]
)
print(f"Created {len(chunks)} chunks")

# Create triples manually
triples = [
    Triple(
        head=Node(
            name="Albert Einstein",
            label="Person",
            properties={"occupation": "Physicist", "birth_year": "1879"}
        ),
        relation=Relation(name="developed"),
        tail=Node(
            name="Theory of Relativity",
            label="Theory",
            properties={"field": "Physics"}
        ),
        chunk_ids=[c.chunk_id for c in chunks[:1]]
    ),
    Triple(
        head=Node(
            name="Albert Einstein",
            label="Person",
            properties={}
        ),
        relation=Relation(name="won"),
        tail=Node(
            name="Nobel Prize in Physics",
            label="Award",
            properties={"year": "1921"}
        ),
        chunk_ids=[c.chunk_id for c in chunks[1:2]]
    )
]

# Build graph from triples
graph = client.graphs.create_graph_from_triples(
    name="Physics Knowledge Graph",
    workspace_id=workspace.workspace_id,
    triples=triples
)
print(f"Created graph: {graph.graph_id}")

# Query the graph
query_result = client.graphs.query_unstructured(
    graph_id=graph.graph_id,
    query="What did Einstein develop and what awards did he win?"
)
print(f"Answer: {query_result.answer}")

# Get graph nodes
nodes = client.graphs.get_nodes(graph_id=graph.graph_id)
for node in nodes:
    print(f"Node: {node.name} ({node.type})")

# Export to Cypher for Neo4j
cypher = client.graphs.export_cypher(graph_id=graph.graph_id)
print(f"Cypher export: {cypher}")
```

--------------------------------

### Python SDK Usage

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Examples demonstrating how to use the WhyHow Python SDK to interact with the Knowledge Graph Studio API.

```APIDOC
```python
from whyhow import WhyHow, Triple, Node, Chunk, Relation

# Initialize client
client = WhyHow(
    api_key='your-whyhow-api-key',
    base_url="http://localhost:8000"
)

# Create a workspace
workspace = client.workspaces.create(name="Research Knowledge Graph")
print(f"Created workspace: {workspace.workspace_id}")

# Add chunks with text content
chunks = client.chunks.create(
    workspace_id=workspace.workspace_id,
    chunks=[
        Chunk(content="Albert Einstein developed the theory of relativity."),
        Chunk(content="Einstein won the Nobel Prize in Physics in 1921."),
        Chunk(content="The theory of relativity revolutionized modern physics.")
    ]
)
print(f"Created {len(chunks)} chunks")

# Create triples manually
triples = [
    Triple(
        head=Node(
            name="Albert Einstein",
            label="Person",
            properties={"occupation": "Physicist", "birth_year": "1879"}
        ),
        relation=Relation(name="developed"),
        tail=Node(
            name="Theory of Relativity",
            label="Theory",
            properties={"field": "Physics"}
        ),
        chunk_ids=[c.chunk_id for c in chunks[:1]]
    ),
    Triple(
        head=Node(
            name="Albert Einstein",
            label="Person",
            properties={}
        ),
        relation=Relation(name="won"),
        tail=Node(
            name="Nobel Prize in Physics",
            label="Award",
            properties={"year": "1921"}
        ),
        chunk_ids=[c.chunk_id for c in chunks[1:2]]
    )
]

# Build graph from triples
graph = client.graphs.create_graph_from_triples(
    name="Physics Knowledge Graph",
    workspace_id=workspace.workspace_id,
    triples=triples
)
print(f"Created graph: {graph.graph_id}")

# Query the graph
query_result = client.graphs.query_unstructured(
    graph_id=graph.graph_id,
    query="What did Einstein develop and what awards did he win?"
)
print(f"Answer: {query_result.answer}")

# Get graph nodes
nodes = client.graphs.get_nodes(graph_id=graph.graph_id)
for node in nodes:
    print(f"Node: {node.name} ({node.type})")

# Export to Cypher for Neo4j
cypher = client.graphs.export_cypher(graph_id=graph.graph_id)
print(f"Cypher export: {cypher}")
```
```

--------------------------------

### Get graph creation details

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves cost and time estimates for creating a graph based on workspace and schema filters.

```bash
curl -X POST "http://localhost:8000/graphs/create_details" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "507f1f77bcf86cd799439011",
    "schema_": "507f1f77bcf86cd799439041",
    "filters": {}
  }'
```

--------------------------------

### Setup Database Collections and Indexes

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Run the provided CLI script to set up the necessary database collections and indexes in your MongoDB Atlas cluster. This script requires a `collection_index_config.json` file.

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

--------------------------------

### Get a specific graph

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves details for a single graph by its unique ID.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get graph triples

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves a paginated list of triples within a specific graph.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/triples?skip=0&limit=50" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get a Specific Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve details for a specific workspace by its ID. Requires an API key.

```bash
curl -X GET "http://localhost:8000/workspaces/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get graph relations

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves all relations defined within a specific graph.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/relations" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get a Specific Node

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve details for a single node using its ID. Requires authentication.

```bash
# Get a specific node
curl -X GET "http://localhost:8000/nodes/507f1f77bcf86cd799439081" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get graph chunks

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves all data chunks associated with a specific graph.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/chunks" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get a Specific Chunk

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve details for a specific chunk by its ID. Requires an API key.

```bash
curl -X GET "http://localhost:8000/chunks/507f1f77bcf86cd799439021" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get graph nodes

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves a paginated list of nodes within a specific graph.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/nodes?skip=0&limit=50" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get a Specific Triple

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve details for a single triple using its ID. Requires authentication.

```bash
# Get a specific triple
curl -X GET "http://localhost:8000/triples/507f1f77bcf86cd799439091" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get Workspace Tags

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve aggregated tags from chunks and documents associated with a specific workspace. Requires an API key.

```bash
curl -X GET "http://localhost:8000/workspaces/507f1f77bcf86cd799439011/tags" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get Chunks Associated with a Node

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve all chunks linked to a specific node. Requires authentication.

```bash
# Get chunks associated with a node
curl -X GET "http://localhost:8000/nodes/507f1f77bcf86cd799439081/chunks" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get Chunks Associated with a Triple

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve all chunks linked to a specific triple. Requires authentication.

```bash
# Get chunks associated with a triple
curl -X GET "http://localhost:8000/triples/507f1f77bcf86cd799439091/chunks" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get Task Status via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve the status of asynchronous operations using a task ID.

```bash
curl -X GET "http://localhost:8000/tasks/507f1f77bcf86cd799439091" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Get Public Triple Chunks

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve chunks associated with a triple from a public graph. This endpoint does not require authentication.

```bash
# Get public triple chunks
curl -X GET "http://localhost:8000/triples/public/507f1f77bcf86cd799439091/chunks"
```

--------------------------------

### Create Demo Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Create a demo workspace that is pre-populated with sample data. Requires an API key.

```bash
curl -X POST "http://localhost:8000/workspaces/demo" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Copy Environment Sample File

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Copy the sample environment file to `.env` to configure your environment variables. This is a necessary step before setting up the database and API keys.

```shell
cp .env.sample .env
```

--------------------------------

### Create User and Generate API Key

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Create a user for the WhyHow API and generate an API key. Copy the generated API key as it will be needed to communicate with the backend via the SDK.

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

--------------------------------

### Build and Run Docker Image

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Commands to build the Docker image and run the containerized backend.

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

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

--------------------------------

### Create a graph from triples

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Initializes a new knowledge graph using a provided set of triples. Requires a valid workspace and schema ID.

```bash
curl -X POST "http://localhost:8000/graphs/from_triples" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Leaders Graph",
    "workspace": "507f1f77bcf86cd799439011",
    "schema_": "507f1f77bcf86cd799439041",
    "triples": [
      {
        "head": "Sam Altman",
        "head_type": "Person",
        "head_properties": {"title": "CEO"},
        "relation": "leads",
        "relation_properties": {},
        "tail": "OpenAI",
        "tail_type": "Company",
        "tail_properties": {"industry": "AI Research"}
      },
      {
        "head": "OpenAI",
        "head_type": "Company",
        "head_properties": {},
        "relation": "develops",
        "relation_properties": {},
        "tail": "GPT-4",
        "tail_type": "Product",
        "tail_properties": {"type": "Large Language Model"}
      }
    ]
  }'
```

--------------------------------

### Manage Users and API Keys via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for API key rotation, LLM provider configuration, and user account management.

```bash
curl -X GET "http://localhost:8000/users/api_key" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X POST "http://localhost:8000/users/rotate_api_key" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X PUT "http://localhost:8000/users/set_providers_details" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [{
      "type": "llm",
      "value": "openai",
      "api_key": "sk-your-openai-key"
    }]
  }'
```

```bash
curl -X GET "http://localhost:8000/users/providers_details" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X GET "http://localhost:8000/users/status" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X DELETE "http://localhost:8000/users" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### List All Workspaces

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve a list of all workspaces with support for pagination and ordering. Requires an API key.

```bash
curl -X GET "http://localhost:8000/workspaces?skip=0&limit=10&order=1" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Create a New Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Use this endpoint to create a new workspace for organizing knowledge graph components. Requires an API key and a JSON payload with the workspace name.

```bash
curl -X POST "http://localhost:8000/workspaces" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Knowledge Graph Workspace"}'
```

--------------------------------

### Manage Documents via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for uploading, listing, processing, and assigning documents to workspaces.

```bash
# Generate a presigned URL for document upload
curl -X POST "http://localhost:8000/documents/generate_presigned" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "company_report.pdf",
    "workspace_id": "507f1f77bcf86cd799439011"
  }'

# Response includes presigned POST fields for S3 upload:
# {
#   "url": "https://your-bucket.s3.amazonaws.com/",
#   "fields": {
#     "key": "user_id/company_report.pdf",
#     "x-amz-meta-document-id": "507f1f77bcf86cd799439031",
#     "x-amz-meta-origin-workspace-id": "507f1f77bcf86cd799439011",
#     ...
#   }
# }

# List documents with filtering
curl -X GET "http://localhost:8000/documents?workspace_id=507f1f77bcf86cd799439011&status=processed" \
  -H "X-API-Key: your-api-key"

# Get a specific document
curl -X GET "http://localhost:8000/documents/507f1f77bcf86cd799439031" \
  -H "X-API-Key: your-api-key"

# Trigger document processing (after S3 upload)
curl -X POST "http://localhost:8000/documents/507f1f77bcf86cd799439031/process" \
  -H "X-API-Key: your-api-key"

# Generate presigned download URL
curl -X POST "http://localhost:8000/documents/507f1f77bcf86cd799439031/download" \
  -H "X-API-Key: your-api-key"

# Assign documents to a workspace
curl -X PUT "http://localhost:8000/documents/assign/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '["507f1f77bcf86cd799439031"]'

# Unassign documents from a workspace
curl -X PUT "http://localhost:8000/documents/unassign/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '["507f1f77bcf86cd799439031"]'

# Delete document and associated chunks
curl -X DELETE "http://localhost:8000/documents/507f1f77bcf86cd799439031" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Manage Queries via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for listing, retrieving, and deleting stored query history.

```bash
curl -X GET "http://localhost:8000/queries?graph_id=507f1f77bcf86cd799439051&skip=0&limit=10" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X GET "http://localhost:8000/queries/507f1f77bcf86cd799439071" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X DELETE "http://localhost:8000/queries/507f1f77bcf86cd799439071" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/README.md

Set the required environment variables for MongoDB and OpenAI API keys. Ensure these values are updated per your environment.

```shell
WHYHOW__EMBEDDING__OPENAI__API_KEY=<your openai api key>
WHYHOW__GENERATIVE__OPENAI__API_KEY=<your openai api key - can be the same>
WHYHOW__MONGODB__USERNAME=<your altas database username>
WHYHOW__MONGODB__PASSWORD=<your altas database password>
WHYHOW__MONGODB__DATABASE_NAME=main
WHYHOW__MONGODB__HOST=<your altas host i.e. 'xxx.xxx.mongodb.net'>
```

--------------------------------

### Manage Schemas via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for creating, generating, listing, updating, and deleting knowledge graph schemas.

```bash
# Create a schema
curl -X POST "http://localhost:8000/schemas" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Knowledge Schema",
    "workspace": "507f1f77bcf86cd799439011",
    "entities": [
      {"name": "Person", "description": "A human individual"},
      {"name": "Company", "description": "A business organization"},
      {"name": "Product", "description": "A product or service"}
    ],
    "relations": [
      {"name": "works_at", "description": "Person works at Company"},
      {"name": "leads", "description": "Person leads Company or Product"},
      {"name": "develops", "description": "Company develops Product"}
    ],
    "patterns": [
      {
        "head": "Person",
        "relation": "works_at",
        "tail": "Company",
        "description": "Employment relationship"
      },
      {
        "head": "Person",
        "relation": "leads",
        "tail": "Company",
        "description": "Leadership position"
      }
    ]
  }'

# Response:
# {
#   "message": "Schema created successfully.",
#   "status": "success",
#   "count": 1,
#   "schemas": [{
#     "id": "507f1f77bcf86cd799439041",
#     "name": "Corporate Knowledge Schema",
#     "workspace": "507f1f77bcf86cd799439011",
#     "entities": [...],
#     "relations": [...],
#     "patterns": [...]
#   }]
# }

# Generate a schema from natural language questions
curl -X POST "http://localhost:8000/schemas/generate" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [
      "Who are the key executives at major tech companies?",
      "What products do these companies develop?",
      "How are companies and their subsidiaries related?"
    ]
  }'

# List schemas
curl -X GET "http://localhost:8000/schemas?workspace_id=507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key"

# Get a specific schema
curl -X GET "http://localhost:8000/schemas/507f1f77bcf86cd799439041" \
  -H "X-API-Key: your-api-key"

# Update a schema
curl -X PUT "http://localhost:8000/schemas/507f1f77bcf86cd799439041" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Schema Name",
    "entities": [
      {"name": "Person", "description": "Updated description"},
      {"name": "Organization", "description": "Any type of organization"}
    ]
  }'

# Delete a schema (fails if graphs are associated)
curl -X DELETE "http://localhost:8000/schemas/507f1f77bcf86cd799439041" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### POST /schemas

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Creates a new knowledge graph schema.

```APIDOC
## POST /schemas

### Description
Creates a new schema defining entity types, relations, and patterns for a knowledge graph.

### Method
POST

### Endpoint
/schemas

### Request Body
- **name** (string) - Required - Name of the schema.
- **workspace** (string) - Required - Workspace ID.
- **entities** (array) - Required - List of entity objects.
- **relations** (array) - Required - List of relation objects.
- **patterns** (array) - Required - List of pattern objects.

### Response Example
{
  "message": "Schema created successfully.",
  "status": "success",
  "schemas": [{
    "id": "507f1f77bcf86cd799439041",
    "name": "Corporate Knowledge Schema"
  }]
}
```

--------------------------------

### List Chunks with Filtering

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve a list of chunks from a specific workspace, with options for pagination and excluding embeddings. Requires an API key.

```bash
curl -X GET "http://localhost:8000/chunks?workspace_id=507f1f77bcf86cd799439011&skip=0&limit=10&include_embeddings=false" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Run All Unit Tests with Pytest

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/tests/README.md

Execute all unit tests located in the `tests/unit` directory. This is the standard command for a full test suite run.

```shell
pytest tests/unit
```

--------------------------------

### Manage Rules via API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for listing, retrieving, and deleting rules within workspaces or specific graphs.

```bash
curl -X GET "http://localhost:8000/rules?workspace_id=507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/rules" \
  -H "X-API-Key: your-api-key"
```

```bash
curl -X DELETE "http://localhost:8000/rules/507f1f77bcf86cd799439101" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### List Triples with Filtering

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve a list of triples from a graph, with options to filter by type and paginate results. Requires authentication.

```bash
# List triples with filtering
curl -X GET "http://localhost:8000/triples?graph_id=507f1f77bcf86cd799439051&type=leads&skip=0&limit=20" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### List Nodes with Filtering

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieve a list of nodes from a specific graph, with options to filter by type and paginate results. Requires authentication.

```bash
# List nodes with filtering
curl -X GET "http://localhost:8000/nodes?graph_id=507f1f77bcf86cd799439051&type=Person&skip=0&limit=20" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Create a Node

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Use this endpoint to create a new node in a specified graph. Requires authentication and a JSON payload with node details. The `strict_mode` parameter controls behavior on validation errors.

```bash
# Create a node
curl -X POST "http://localhost:8000/nodes" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Elon Musk",
    "type": "Person",
    "graph": "507f1f77bcf86cd799439051",
    "properties": {"title": "CEO", "companies": ["Tesla", "SpaceX"]},
    "strict_mode": false
  }'
```

--------------------------------

### D3.js Knowledge Graph Rendering

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/src/whyhow_api/static/templates/graph_template.html

JavaScript code using D3.js to set up the SVG canvas, initialize the force simulation, and render nodes, links, and labels. Includes drag and zoom functionality.

```javascript
// Set up SVG and graph parameters
const width = document.getElementById("graph").clientWidth;
const height = document.getElementById("graph").clientHeight;

const svg = d3
  .select("#graph")
  .append("svg")
  .attr("width", "100%")
  .attr("height", "100%")
  .call(
    d3.zoom().on("zoom", function (event) {
      svg.attr("transform", event.transform);
    })
  )
  .append("g");

const nodes = {{ nodes | tojson }};
const links = {{ links | tojson }};

// Initialize force simulation
const simulation = d3
  .forceSimulation(nodes)
  .force("link", d3.forceLink(links).id((d) => d.id))
  .force("charge", d3.forceManyBody().strength(-1000)) // Increase strength to spread out nodes
  .force("center", d3.forceCenter(width / 2, height / 2));

const link = svg
  .append("g")
  .attr("stroke", "#999")
  .attr("stroke-opacity", 0.6)
  .selectAll("line")
  .data(links)
  .join("line")
  .attr("stroke-width", 2)
  .attr("marker-end", "url(#arrow)");

// Add arrowheads
const node = svg
  .append("g")
  .attr("stroke", "#fff")
  .attr("stroke-width", 1.5)
  .selectAll("circle")
  .data(nodes)
  .join("circle")
  .attr("r", (d) => d.value) // Node size based on "value"
  .attr("fill", (d) => d.color) // Node color based on "color"
  .call(
    d3
      .drag()
      .on("start", dragstarted)
      .on("drag", dragged)
      .on("end", dragended)
  );

const labels = svg
  .append("g")
  .attr("class", "labels")
  .selectAll("text")
  .data(nodes)
  .join("text")
  .text((d) => d.name)
  .attr("x", (d) => d.x)
  .attr("y", (d) => d.y);

svg
  .append("defs")
  .append("marker")
  .attr("id", "arrow")
  .attr("viewBox", "0 -5 10 10")
  .attr("refX", 25)
  .attr("refY", 0)
  .attr("markerWidth", 6)
  .attr("markerHeight", 6)
  .attr("orient", "auto")
  .append("path")
  .attr("fill", "#999")
  .attr("d", "M0,-5L10,0L0,5");

simulation.on("tick", () => {
  link
    .attr("x1", (d) => d.source.x)
    .attr("y1", (d) => d.source.y)
    .attr("x2", (d) => d.target.x)
    .attr("y2", (d) => d.target.y);

  node.attr("cx", (d) => d.x).attr("cy", (d) => d.y);
  labels.attr("x", (d) => d.x + 5).attr("y", (d) => d.y + 5);
});

function dragstarted(event, d) {
  if (!event.active) simulation.alphaTarget(0.3).restart();
  d.fx = d.x;
  d.fy = d.y;
}

function dragged(event, d) {
  d.fx = event.x;
  d.fy = event.y;
}

function dragended(event, d) {
  if (!event.active) simulation.alphaTarget(0);
  d.fx = null;
  d.fy = null;
}
```

--------------------------------

### POST /documents/generate_presigned

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Generates a presigned URL for uploading documents to S3.

```APIDOC
## POST /documents/generate_presigned

### Description
Generates a presigned URL and fields required to upload a document to S3.

### Method
POST

### Endpoint
/documents/generate_presigned

### Request Body
- **filename** (string) - Required - The name of the file to upload.
- **workspace_id** (string) - Required - The ID of the workspace.

### Response Example
{
  "url": "https://your-bucket.s3.amazonaws.com/",
  "fields": {
    "key": "user_id/company_report.pdf",
    "x-amz-meta-document-id": "507f1f77bcf86cd799439031",
    "x-amz-meta-origin-workspace-id": "507f1f77bcf86cd799439011"
  }
}
```

--------------------------------

### Run Pytest Suite with Fail Fast

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/tests/README.md

Execute the entire unit test suite but stop immediately upon encountering the first test failure. This is useful for quickly identifying and fixing the initial errors.

```shell
pytest tests/unit -x --ff
```

--------------------------------

### List all graphs

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Retrieves a list of graphs filtered by workspace and status.

```bash
curl -X GET "http://localhost:8000/graphs?workspace_id=507f1f77bcf86cd799439011&status=ready" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### POST /graphs/from_triples

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Creates a new knowledge graph from a list of triples.

```APIDOC
## POST /graphs/from_triples

### Description
Creates a new knowledge graph from a provided list of triples.

### Method
POST

### Endpoint
http://localhost:8000/graphs/from_triples

### Request Body
- **name** (string) - Required - Name of the graph
- **workspace** (string) - Required - Workspace ID
- **schema_** (string) - Required - Schema ID
- **triples** (array) - Required - List of triple objects

### Request Example
{
  "name": "Tech Leaders Graph",
  "workspace": "507f1f77bcf86cd799439011",
  "schema_": "507f1f77bcf86cd799439041",
  "triples": [
    {
      "head": "Sam Altman",
      "head_type": "Person",
      "head_properties": {"title": "CEO"},
      "relation": "leads",
      "relation_properties": {},
      "tail": "OpenAI",
      "tail_type": "Company",
      "tail_properties": {"industry": "AI Research"}
    }
  ]
}

### Response
#### Success Response (200)
- **message** (string) - Status message
- **status** (string) - Operation status
- **graphs** (array) - List of created graph objects
```

--------------------------------

### Knowledge Graph Visualization CSS

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/src/whyhow_api/static/templates/graph_template.html

CSS styles for the graph container and SVG elements. Ensures proper layout and appearance of the graph visualization.

```css
/* CSS styles */
body {
  margin: 0;
  font-family: Arial, sans-serif;
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background-color: #f4f4f4;
  /* Light grey background */
}

#graph {
  width: 80vw;
  height: 80vh;
  border: 1px solid #e0e0e0;
  /* Light grey border */
  background-color: #fff;
  /* White background */
  box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
  /* subtle shadow similar to Paper */
  padding: 20px;
  /* Padding around content */
  overflow: hidden;
  /* Prevents any overflows */
  border-radius: 1rem;
}

svg {
  width: 100%;
  height: 100%;
}
```

--------------------------------

### Export graph as Cypher

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Exports the graph structure as Cypher statements compatible with Neo4j.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/export/cypher" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Users API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

User management endpoints for API key rotation and LLM provider configuration.

```APIDOC
## GET /users/api_key

### Description
Retrieves the current API key associated with the user.

### Method
GET

### Endpoint
/users/api_key

### Request Example
```bash
curl -X GET "http://localhost:8000/users/api_key" \
  -H "X-API-Key: your-api-key"
```

## POST /users/rotate_api_key

### Description
Rotates the current API key, generating a new one.

### Method
POST

### Endpoint
/users/rotate_api_key

### Request Example
```bash
curl -X POST "http://localhost:8000/users/rotate_api_key" \
  -H "X-API-Key: your-api-key"
```

## PUT /users/set_providers_details

### Description
Configures details for LLM providers.

### Method
PUT

### Endpoint
/users/set_providers_details

### Request Body
- **providers** (array) - Required - A list of provider configurations.
  - **type** (string) - Required - The type of provider (e.g., "llm").
  - **value** (string) - Required - The name of the provider (e.g., "openai").
  - **api_key** (string) - Required - The API key for the provider.

### Request Example
```json
{
  "providers": [
    {
      "type": "llm",
      "value": "openai",
      "api_key": "sk-your-openai-key"
    }
  ]
}
```

## GET /users/providers_details

### Description
Retrieves the configured provider details. API keys are obfuscated.

### Method
GET

### Endpoint
/users/providers_details

### Request Example
```bash
curl -X GET "http://localhost:8000/users/providers_details" \
  -H "X-API-Key: your-api-key"
```

## GET /users/status

### Description
Retrieves the current status of the user account.

### Method
GET

### Endpoint
/users/status

### Request Example
```bash
curl -X GET "http://localhost:8000/users/status" \
  -H "X-API-Key: your-api-key"
```

## DELETE /users

### Description
Deletes the user and all associated data.

### Method
DELETE

### Endpoint
/users

### Request Example
```bash
curl -X DELETE "http://localhost:8000/users" \
  -H "X-API-Key: your-api-key"
```
```

--------------------------------

### Access Public Graphs

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Use these endpoints to retrieve data from public knowledge graphs without requiring authentication. Useful for sharing read-only graph data.

```bash
# Get a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051"
```

```bash
# Get nodes from a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051/nodes?limit=50"
```

```bash
# Get triples from a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051/triples"
```

```bash
# Get relations from a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051/relations"
```

```bash
# Get chunks from a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051/chunks"
```

```bash
# Get rules from a public graph
curl -X GET "http://localhost:8000/graphs/public/507f1f77bcf86cd799439051/rules"
```

--------------------------------

### Debug Unit Tests with Breakpoint

Source: https://github.com/whyhow-ai/knowledge-graph-studio/blob/main/tests/README.md

Utilize Python's built-in `breakpoint()` function to pause test execution and enter the Pdb debugger. This allows for interactive inspection of variables and code flow.

```python
breakpoint()
```

--------------------------------

### Assign Chunks to Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Assign existing chunks to a specific workspace. Requires the workspace ID, API key, and a JSON payload containing an array of chunk IDs.

```bash
curl -X PUT "http://localhost:8000/chunks/assign/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '["507f1f77bcf86cd799439021", "507f1f77bcf86cd799439022"]'
```

--------------------------------

### Add Chunks to Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Add new text chunks to a specified workspace. Requires the workspace ID, API key, and a JSON payload containing an array of chunk objects with their content.

```bash
curl -X POST "http://localhost:8000/chunks/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunks": [
      {"content": "Sam Altman is the CEO of OpenAI, a leading AI research company."},
      {"content": "OpenAI developed GPT-4 and ChatGPT, revolutionizing AI applications."}
    ]
  }'
```

--------------------------------

### Create Merge Nodes Rule

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Define a rule to automatically merge nodes that match specified criteria. This is useful for entity resolution. Requires authentication and a JSON payload describing the rule.

```bash
# Create a merge nodes rule
curl -X POST "http://localhost:8000/rules" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "507f1f77bcf86cd799439011",
    "rule": {
      "rule_type": "merge_nodes",
      "from_node_names": ["OpenAI Inc", "OpenAI Inc."],
      "to_node_name": "OpenAI",
      "node_type": "Company"
    }
  }'
```

--------------------------------

### Find similar nodes for entity resolution

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Identifies potential duplicate nodes within a graph to assist in entity resolution.

```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/resolve?limit=10" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### POST /graphs/{id}/query

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Queries a knowledge graph using natural language or structured entity filters.

```APIDOC
## POST /graphs/{id}/query

### Description
Queries a knowledge graph using RAG to find relevant nodes and generate answers.

### Method
POST

### Endpoint
http://localhost:8000/graphs/{id}/query

### Parameters
#### Path Parameters
- **id** (string) - Required - The graph ID

### Request Body
- **query** (string) - Required - Natural language query
- **entities** (array) - Optional - List of specific entities
- **relations** (array) - Optional - List of specific relations

### Request Example
{
  "query": "Who leads OpenAI?"
}

### Response
#### Success Response (200)
- **message** (string) - Status message
- **queries** (array) - List containing the answer and retrieved context
```

--------------------------------

### Rules Management API

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Endpoints for managing rules within workspaces and graphs.

```APIDOC
## GET /rules

### Description
Lists all rules for a given workspace.

### Method
GET

### Endpoint
/rules

### Query Parameters
- **workspace_id** (string) - Required - The ID of the workspace to list rules from.

### Request Example
```bash
curl -X GET "http://localhost:8000/rules?workspace_id=507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key"
```

## GET /graphs/{graph_id}/rules

### Description
Retrieves all rules associated with a specific graph.

### Method
GET

### Endpoint
/graphs/{graph_id}/rules

### Path Parameters
- **graph_id** (string) - Required - The ID of the graph whose rules are to be retrieved.

### Request Example
```bash
curl -X GET "http://localhost:8000/graphs/507f1f77bcf86cd799439051/rules" \
  -H "X-API-Key: your-api-key"
```

## DELETE /rules/{rule_id}

### Description
Deletes a specific rule.

### Method
DELETE

### Endpoint
/rules/{rule_id}

### Path Parameters
- **rule_id** (string) - Required - The ID of the rule to delete.

### Request Example
```bash
curl -X DELETE "http://localhost:8000/rules/507f1f77bcf86cd799439101" \
  -H "X-API-Key: your-api-key"
```
```

--------------------------------

### Unassign Chunks from Workspace

Source: https://context7.com/whyhow-ai/knowledge-graph-studio/llms.txt

Unassign chunks from a specific workspace. Requires the workspace ID, API key, and a JSON payload containing an array of chunk IDs to be unassigned.

```bash
curl -X PUT "http://localhost:8000/chunks/unassign/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '["507f1f77bcf86cd799439021"]'
```