docs(samples): Document AI Warehouse - Created Quickstart Sample Code (#8969)

* docs(samples): Document AI Warehouse - Created Quickstart and Search Documents sample code

* docs(samples): Added contentwarehouse to blunderbuss and Codeowners

* docs(samples): Resolved Typing error
- Put File type filter in `DocumentQuery`

* docs(samples): Adjusted Histogram Printing with f-strings

* docs(samples): Added project number conversion to Document AI Warehouse Tests

* docs(samples): Upgrade contentwarehouse to `0.3.0`

* docs(samples): Updated Document Warehouse Quickstart & Search based on Code Review comments

* Update contentwarehouse/snippets/noxfile_config.py

Co-authored-by: Dan Lee <[email protected]>

* Update noxfile_config.py

Enabled Type Hints

* docs(samples): Moved get_project_number into test_utilities.py

* docs(samples): Added Types to Tests

* docs(samples): Chanaged Any for capsys to pytest.CaptureFixture

* Ran isort with Google Profile

Co-authored-by: Dan Lee <[email protected]>
Co-authored-by: Karl Weinmeister <[email protected]>
Co-authored-by: gcf-merge-on-green[bot] <60162190+gcf-merge-on-green[bot]@users.noreply.github.com>

Author: 4 people

.github/CODEOWNERS

@@ -36,6 +36,7 @@
 /compute/**/*                          @m-strzelczyk @GoogleCloudPlatform/dee-infra @GoogleCloudPlatform/python-samples-reviewers
 /container/**/*                        @GoogleCloudPlatform/dee-platform-ops @GoogleCloudPlatform/python-samples-reviewers
 /containeranalysis/**/*                @GoogleCloudPlatform/aap-dpes @GoogleCloudPlatform/python-samples-reviewers
+/contentwarehouse/**/*                 @GoogleCloudPlatform/dee-data-ai  @GoogleCloudPlatform/python-samples-reviewers
 /data-science-onramp/                  @leahecole @bradmiro @GoogleCloudPlatform/python-samples-reviewers
 /datacatalog/**/*                      @GoogleCloudPlatform/python-samples-reviewers
 /dataflow/**/*                         @davidcavazos @GoogleCloudPlatform/python-samples-reviewers

.github/blunderbuss.yml

@@ -84,6 +84,7 @@ assign_issues_by:
   to:
   - GoogleCloudPlatform/api-iot
 - labels:
+  - 'api: contentwarehouse'
   - 'api: enterpriseknowledgegraph'
   - 'api: documentai'
   - 'api: language'
@@ -186,6 +187,7 @@ assign_prs_by:
   to:
   - GoogleCloudPlatform/infra-db-dpes
 - labels:
+  - 'api: contentwarehouse'
   - 'api: enterpriseknowledgegraph'
   - 'api: documentai'
   - 'api: retail'

contentwarehouse/AUTHORING_GUIDE.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/AUTHORING_GUIDE.md

contentwarehouse/CONTRIBUTING.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/CONTRIBUTING.md

contentwarehouse/__init__.py

@@ -0,0 +1,42 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Default TEST_CONFIG_OVERRIDE for python repos.
+
+# You can copy this file into your directory, then it will be imported from
+# the noxfile.py.
+
+# The source of truth:
+# https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/noxfile_config.py
+
+TEST_CONFIG_OVERRIDE = {
+    # You can opt out from the test for specific Python versions.
+    "ignored_versions": ["2.7", "3.6", "3.8", "3.9", "3.10", "3.11"],
+    # Old samples are opted out of enforcing Python type hints
+    # All new samples should feature them
+    "enforce_type_hints": True,
+    # An envvar key for determining the project id to use. Change it
+    # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
+    # build specific Cloud project. You can also use your own string
+    # to use your own Cloud project.
+    "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
+    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # If you need to use a specific version of pip,
+    # change pip_version_override to the string representation
+    # of the version number, for example, "20.2.4"
+    "pip_version_override": None,
+    # A dictionary you want to inject into your test. Don't put any
+    # secrets here. These values will override predefined values.
+    "envs": {},
+}

contentwarehouse/snippets/__init__.py

@@ -0,0 +1,95 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+
+# [START contentwarehouse_quickstart]
+
+from google.cloud import contentwarehouse
+
+# TODO(developer): Uncomment these variables before running the sample.
+# project_number = 'YOUR_PROJECT_NUMBER'
+# location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
+
+
+def quickstart(project_number: str, location: str) -> None:
+
+    # Create a Schema Service client
+    document_schema_client = contentwarehouse.DocumentSchemaServiceClient()
+
+    # The full resource name of the location, e.g.:
+    # projects/{project_number}/locations/{location}
+    parent = document_schema_client.common_location_path(
+        project=project_number, location=location
+    )
+
+    # Define Schema Property of Text Type
+    property_definition = contentwarehouse.PropertyDefinition(
+        name="stock_symbol",  # Must be unique within a document schema (case insensitive)
+        display_name="Searchable text",
+        is_searchable=True,
+        text_type_options=contentwarehouse.TextTypeOptions(),
+    )
+
+    # Define Document Schema Request
+    create_document_schema_request = contentwarehouse.CreateDocumentSchemaRequest(
+        parent=parent,
+        document_schema=contentwarehouse.DocumentSchema(
+            display_name="My Test Schema",
+            property_definitions=[property_definition],
+        ),
+    )
+
+    # Create a Document schema
+    document_schema = document_schema_client.create_document_schema(
+        request=create_document_schema_request
+    )
+
+    # Create a Document Service client
+    document_client = contentwarehouse.DocumentServiceClient()
+
+    # The full resource name of the location, e.g.:
+    # projects/{project_number}/locations/{location}
+    parent = document_client.common_location_path(
+        project=project_number, location=location
+    )
+
+    # Define Document Property Value
+    document_property = contentwarehouse.Property(
+        name=document_schema.property_definitions[0].name,
+        text_values=contentwarehouse.TextArray(values=["GOOG"]),
+    )
+
+    # Define Document
+    document = contentwarehouse.Document(
+        display_name="My Test Document",
+        document_schema_name=document_schema.name,
+        plain_text="This is a sample of a document's text.",
+        properties=[document_property],
+    )
+
+    # Define Request
+    create_document_request = contentwarehouse.CreateDocumentRequest(
+        parent=parent, document=document
+    )
+
+    # Create a Document for the given schema
+    response = document_client.create_document(request=create_document_request)
+
+    # Read the output
+    print(f"Rule Engine Output: {response.rule_engine_output}")
+    print(f"Document Created: {response.document}")
+
+
+# [END contentwarehouse_quickstart]

contentwarehouse/snippets/noxfile_config.py

@@ -0,0 +1,35 @@
+# # Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import os
+
+from contentwarehouse.snippets import quickstart_sample
+from contentwarehouse.snippets import test_utilities
+import pytest
+
+project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
+location = "us"  # Format is 'us' or 'eu'
+
+
+def test_quickstart(capsys: pytest.CaptureFixture) -> None:
+    project_number = test_utilities.get_project_number(project_id)
+    quickstart_sample.quickstart(
+        project_number=project_number,
+        location=location,
+    )
+    out, _ = capsys.readouterr()
+
+    assert "Rule Engine Output" in out
+    assert "Document Created" in out

contentwarehouse/snippets/quickstart_sample.py

@@ -0,0 +1,3 @@
+pytest==7.2.0
+mock==5.0.0
+google-cloud-resource-manager==1.8.0

contentwarehouse/snippets/quickstart_sample_test.py

@@ -0,0 +1 @@
+google-cloud-contentwarehouse==0.3.0

contentwarehouse/snippets/requirements-test.txt

@@ -0,0 +1,91 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+
+# [START contentwarehouse_search_documents]
+
+from google.cloud import contentwarehouse
+
+# TODO(developer): Uncomment these variables before running the sample.
+# project_number = 'YOUR_PROJECT_NUMBER'
+# location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
+# document_query_text = 'YOUR_DOCUMENT_QUERY'
+
+
+def search_documents_sample(
+    project_number: str,
+    location: str,
+    document_query_text: str,
+) -> None:
+
+    # Create a client
+    client = contentwarehouse.DocumentServiceClient()
+
+    # The full resource name of the location, e.g.:
+    # projects/{project_number}/locations/{location}
+    parent = client.common_location_path(project=project_number, location=location)
+
+    # File Type Filter
+    # Options: DOCUMENT, FOLDER
+    file_type_filter = contentwarehouse.FileTypeFilter(
+        file_type=contentwarehouse.FileTypeFilter.FileType.DOCUMENT
+    )
+
+    # Document Text Query
+    document_query = contentwarehouse.DocumentQuery(
+        query=document_query_text,
+        file_type_filter=file_type_filter,
+    )
+
+    # Histogram Query
+    histogram_query = contentwarehouse.HistogramQuery(
+        histogram_query='count("DocumentSchemaId")'
+    )
+
+    # Define request
+    request = contentwarehouse.SearchDocumentsRequest(
+        parent=parent,
+        document_query=document_query,
+        histogram_queries=[histogram_query],
+    )
+
+    # Make the request
+    response = client.search_documents(request=request)
+
+    # Print search results
+    for matching_document in response.matching_documents:
+        document = matching_document.document
+        # Display name - schema display name.
+        # Name.
+        # Create date.
+        # Snippet - keywords are highlighted with <b> & </b>.
+        print(
+            f"{document.display_name} - {document.document_schema_name}\n"
+            f"{document.name}\n"
+            f"{document.create_time}\n"
+            f"{matching_document.search_text_snippet}\n"
+        )
+
+    # Print histogram
+    for histogram_query_result in response.histogram_query_results:
+        print(
+            f"Histogram Query: {histogram_query_result.histogram_query}\n"
+            f"| {'Schema':<70} | {'Count':<15} |"
+        )
+        for key, value in histogram_query_result.histogram.items():
+            print(f"| {key:<70} | {value:<15} |")
+
+
+# [END contentwarehouse_search_documents]

contentwarehouse/snippets/requirements.txt

@@ -0,0 +1,36 @@
+# # Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import os
+
+from contentwarehouse.snippets import search_documents_sample
+from contentwarehouse.snippets import test_utilities
+import pytest
+
+project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
+location = "us"  # Format is 'us' or 'eu'
+document_query_text = "document"
+
+
+def test_search_documents(capsys: pytest.CaptureFixture) -> None:
+    project_number = test_utilities.get_project_number(project_id)
+    search_documents_sample.search_documents_sample(
+        project_number=project_number,
+        location=location,
+        document_query_text=document_query_text,
+    )
+    out, _ = capsys.readouterr()
+
+    assert "document" in out

contentwarehouse/snippets/search_documents_sample.py

@@ -0,0 +1,24 @@
+# # Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from google.cloud import resourcemanager
+
+
+def get_project_number(project_id: str) -> str:
+    client = resourcemanager.ProjectsClient()
+    name = client.project_path(project=project_id)
+    project = client.get_project(name=name)
+    project_number = client.parse_project_path(project.name)["project"]
+    return project_number