v0.0.4: query_graph_with_schema

.github/workflows/main.yml

@@ -0,0 +1,52 @@
+name: all
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+
+    runs-on:  ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.10']
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+
+    - name: Lint with flake8
+      run: |
+        flake8 src tests examples
+
+    - name: Check style with black
+      run: |
+        black src tests examples
+
+    - name: Run security check
+      run: |
+        bandit -qr -c pyproject.toml src examples
+
+    - name: Run import check
+      run: |
+        isort --check src tests examples
+
+    - name: Run mypy
+      run: |
+        mypy src
+
+    - name: Test with pytest
+      run: |
+        pytest --color=yes

README.md

@@ -7,7 +7,7 @@
 [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)
 [![Whyhow Discord](https://dcbadge.vercel.app/api/server/9bWqrsxgHr?compact=true&style=flat)](https://discord.gg/9bWqrsxgHr)
 
-The WhyHow Knowledge Graph Creation SDK enables you to quickly and easily build automated knowledge graphs tailored to your unique worldview. Instantly build, extend, and query well-scoped KGs using a raw PDF and simple seed concepts in natural language. This version leverages OpenAI for embeddings and NLP, Pinecone serverless for scalable vector search and storage, and Neo4j for graph data storage and management.
+The WhyHow Knowledge Graph Creation SDK enables you to quickly and easily build automated knowledge graphs tailored to your unique worldview. Instantly build, extend, and query well-scoped KGs with your data.
 
 # Installation
 
@@ -74,15 +74,91 @@ Your namespace is a logical grouping of the raw data you upload, the seed concep
 namespace = "harry-potter"
 documents = ["files/harry_potter_and_the_philosophers_stone.pdf","files/harry_potter_and_the_chamber_of_secrets.pdf"]
 
-add_docs_response = client.graph.add_documents(namespace, documents)
-print(add_docs_response)
+documents_response = client.graph.add_documents(namespace, documents)
+print(documents_response)
 # Adding your documents
 
 ```
 
 ## Create a graph
 
-Tell the WhyHow SDK what you care about by providing a list of concepts in the form of natural language questions. Using these questions, we create a small ontology to guide extraction of entities and relationships that are most relevant to your use case. We then construct triples and generate a graph.
+You can create a graph in two different ways. First, you can create a graph using a user-defined schema, giving you complete control over the types of entities and relationships that are extracted and used to build the graph. Or, you can create a graph using a set of seed questions. In this case, WhyHow will automatically extract entities and relationships that are most applicable to the things you want to know, and construct a graph from these concepts.
+
+Create graph with **schema** if...
+
+1. Your graph must adhere to a consistent structure.
+2. You are very familiar with the structure of your raw documents.
+3. You need comprehensive extraction of concepts across the entire document.
+
+Create graph with **seed questions** if...
+
+1. You are unsure as to which relationships and patterns you'd like to build into your graph.
+2. You want to build your graph with only the most semantically similar raw data.
+
+### Create a graph with schema
+
+Tell the WhyHow SDK exactly which entities, relationships, and patterns you'd like to extract and build into your graph by defining them in a JSON-based schema.
+
+```shell
+
+#schema.json
+
+{
+  "entities": [
+    {
+      "name": "character",
+      "description": "A person appearing in the book, e.g., Harry Potter, Ron Weasley, Hermione Granger, Albus Dumbledore."
+    },
+    {
+      "name": "object",
+      "description": "Inanimate items that characters use or interact with, e.g., wand, Philosopher's Stone, Invisibility Cloak, broomstick."
+    }
+    ...
+  ],
+  "relations": [
+    {
+      "name": "friends with",
+      "description": "Denotes a friendly relationship between characters."
+    },
+    {
+      "name": "interacts with",
+      "description": "Describes a scenario in which a character engages with another character, creature, or object."
+    },
+    ...
+  ],
+  "patterns": [
+    {
+      "head": "character",
+      "relation": "friends with",
+      "tail": "character",
+      "description": "One character is friends with another, e.g., Harry Potter is friends with Ron Weasley."
+    },
+    {
+      "head": "character",
+      "relation": "interacts with",
+      "tail": "object",
+      "description": "A character interacting with an object, e.g., Harry Potter interacts with the Invisibility Cloak."
+    }
+  ]
+}
+
+```
+
+Using this schema, we extract relevant concepts from your raw data, construct triples, and generate a graph according to the patterns you define.
+
+```shell
+# Create graph from schema
+
+schema = "files/schema.json"
+create_graph_with_schema_response = client.graph.create_graph_from_schema(namespace, schema)
+print(create_graph_with_schema_response)
+# Creating your graph
+
+```
+
+### Create a graph with seed questions
+
+Tell the WhyHow SDK what you care about by providing a list of concepts in the form of natural language questions. Using these questions, we create a small ontology to guide extraction of entities and relationships that are most relevant to your use case, then construct a graph.
 
 ```shell
 

docs/api.md

@@ -1 +1,193 @@
-# Reference
+Here's the generated `api.md` file for your mkdocs based on the provided code files:
+
+```markdown
+# API Reference
+
+This document provides a reference for the WhyHow API, which allows you to interact with the graph functionality.
+
+## GraphAPI
+
+The `GraphAPI` class provides methods to interact with the graph API synchronously.
+
+### `add_documents`
+
+```python
+def add_documents(self, namespace: str, documents: list[str]) -> str
+```
+
+Add documents to the graph.
+
+#### Parameters
+
+- `namespace` (str): The namespace of the graph.
+- `documents` (list[str]): The documents to add.
+
+#### Returns
+
+- (str): The response message.
+
+#### Raises
+
+- `ValueError`: If no documents are provided, not all documents exist, only PDFs are supported, PDFs are too large (limit: 8MB), or too many documents are provided (limit: 3 files during the beta).
+
+### `create_graph`
+
+```python
+def create_graph(self, namespace: str, questions: list[str]) -> str
+```
+
+Create a new graph.
+
+#### Parameters
+
+- `namespace` (str): The namespace of the graph to create.
+- `questions` (list[str]): The seed concepts to initialize the graph with.
+
+#### Returns
+
+- (str): The response message.
+
+#### Raises
+
+- `ValueError`: If no questions are provided.
+
+### `create_graph_from_schema`
+
+```python
+def create_graph_from_schema(self, namespace: str, schema_file: str) -> str
+```
+
+Create a new graph based on a user-defined schema.
+
+#### Parameters
+
+- `namespace` (str): The namespace of the graph to create.
+- `schema_file` (str): The schema file to use to build the graph.
+
+#### Returns
+
+- (str): The response message.
+
+#### Raises
+
+- `ValueError`: If no schema is provided.
+
+### `query_graph`
+
+```python
+def query_graph(self, namespace: str, query: str) -> QueryGraphReturn
+```
+
+Query the graph.
+
+#### Parameters
+
+- `namespace` (str): The namespace of the graph.
+- `query` (str): The query to run.
+
+#### Returns
+
+- (`QueryGraphReturn`): The answer, triples, and Cypher query.
+
+## Schemas
+
+The WhyHow API uses Pydantic models to define the request and response schemas.
+
+### `AddDocumentsResponse`
+
+```python
+class AddDocumentsResponse(BaseResponse):
+    """Schema for the response body of the add documents endpoint."""
+
+    namespace: str
+    message: str
+```
+
+### `CreateQuestionGraphRequest`
+
+```python
+class CreateQuestionGraphRequest(BaseRequest):
+    """Schema for the request body of the create graph endpoint."""
+
+    questions: list[str]
+```
+
+### `CreateSchemaGraphRequest`
+
+```python
+class CreateSchemaGraphRequest(BaseRequest):
+    """Schema for the request body of the create graph endpoint."""
+
+    graph_schema: SchemaModel
+```
+
+### `CreateGraphResponse`
+
+```python
+class CreateGraphResponse(BaseResponse):
+    """Schema for the response body of the create graph endpoint."""
+
+    namespace: str
+    message: str
+```
+
+### `QueryGraphRequest`
+
+```python
+class QueryGraphRequest(BaseRequest):
+    """Schema for the request body of the query graph endpoint."""
+
+    query: str
+```
+
+### `QueryGraphResponse`
+
+```python
+class QueryGraphResponse(BaseResponse):
+    """Schema for the response body of the query graph endpoint."""
+
+    namespace: str
+    answer: str
+```
+
+### `QueryGraphReturn`
+
+```python
+class QueryGraphReturn(BaseReturn):
+    """Schema for the return value of the query graph endpoint."""
+
+    answer: str
+```
+
+## Base Classes
+
+The WhyHow API uses the following base classes for the API schemas:
+
+### `APIBase`
+
+```python
+class APIBase(BaseModel, ABC):
+    """Base class for API schemas."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: Client
+    prefix: str = ""
+```
+
+### `AsyncAPIBase`
+
+```python
+class AsyncAPIBase(BaseModel, ABC):
+    """Base class for async API schemas."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: AsyncClient
+    prefix: str = ""
+```
+```
+
+This `api.md` file provides an overview of the `GraphAPI` class and its methods, along with the request and response schemas used by the API. It also includes information about the base classes used for the API schemas.
+
+You can include this file in your mkdocs documentation to provide a reference for the WhyHow API.