docs: Adding fern python documentation

.pre-commit-config.yaml

@@ -12,7 +12,7 @@ repos:
     hooks:
       - id: pyright
         name: pyright (root)
-        exclude: '^examples/'
+        exclude: ^(examples/)
       - id: pyright
         name: pyright (examples)
-        files: '^examples/'
+        files: ^(examples/compass_sdk_examples)

examples/fern_documentation/python/core/add_metadata.py

@@ -0,0 +1,24 @@
+from cohere.compass.clients import CompassClient
+from cohere.compass.models import DocumentAttributes
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+doc_attr = DocumentAttributes()
+doc_attr.key = "value"
+
+error = compass_client.add_attributes(
+    index_name=INDEX_NAME,
+    document_id=DOCUMENT_ID,
+    attributes=doc_attr,
+)
+
+if error:
+    raise Exception(f"Failed to add attributes: {error}")

examples/fern_documentation/python/core/create_index.py

@@ -0,0 +1,15 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.create_index(index_name=INDEX_NAME)
+
+if r.error:
+    raise Exception(f"Failed to create index: {r.error}")

examples/fern_documentation/python/core/delete_doc.py

@@ -0,0 +1,16 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.delete_document(index_name=INDEX_NAME, document_id=DOCUMENT_ID)
+
+if r.error:
+    raise Exception(f"Failed to delete doc: {r.error}")

examples/fern_documentation/python/core/delete_index.py

@@ -0,0 +1,15 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.delete_index(index_name=INDEX_NAME)
+
+if r.error:
+    raise Exception(f"Failed to delete index: {r.error}")

examples/fern_documentation/python/core/direct_search_index.py

@@ -0,0 +1,45 @@
+from typing import Optional
+
+from cohere.compass.clients import CompassClient
+from cohere.compass.models import RetrievedChunkExtended
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+query = {"query": {"match_all": {}}}
+
+
+def call_direct_search_scroll(
+    hits: list[RetrievedChunkExtended],
+    scroll_id: Optional[str] = None,
+) -> list[RetrievedChunkExtended]:
+    if hits is None:
+        hits = []
+
+    if scroll_id is None:
+        return hits
+
+    results_scroll = compass_client.direct_search_scroll(
+        scroll_id=scroll_id,
+        scroll="1m",
+    )
+
+    hits.extend(results_scroll.hits)
+    return call_direct_search_scroll(hits=hits, scroll_id=results.scroll_id)
+
+
+results = compass_client.direct_search(
+    index_name=INDEX_NAME,
+    query=query,
+    scroll="1m",
+    size=100,
+)
+
+hits = call_direct_search_scroll(hits=results.hits, scroll_id=results.scroll_id)

examples/fern_documentation/python/core/get_doc_asset.py

@@ -0,0 +1,45 @@
+import json
+
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+SEARCH_QUERY = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+results = compass_client.search_chunks(index_name=INDEX_NAME, query=SEARCH_QUERY)
+if results.error:
+    raise Exception(f"Failed to search chunks: {results.error}")
+
+hits = results.hits
+
+if not hits:
+    raise Exception("No hits found")
+
+hit = hits[0]
+
+asset_id: str = hit.assets_info[0].asset_id  # type: ignore
+document_id = hit.document_id
+# URL to fetch asset
+presigned_url = hit.assets_info[0].presigned_url
+
+### Get document asset again, after pre-signed url has expired
+asset, content_type = compass_client.get_document_asset(
+    index_name=document_id,
+    document_id=DOCUMENT_ID,
+    asset_id=asset_id,
+)
+
+# Save the asset to a file.
+if content_type in ["image/jpeg", "image/png"]:
+    with open(f"{asset_id}", "wb") as f:
+        f.write(asset)
+# Print the asset as JSON
+elif "text/json" in content_type:
+    print(json.dumps(asset, indent=2))

examples/fern_documentation/python/core/get_document.py

@@ -0,0 +1,18 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.get_document(index_name=INDEX_NAME, document_id=DOCUMENT_ID)
+
+if r.error:
+    raise Exception(f"Failed to get doc: {r.error}")
+
+print(r.result.hits)

examples/fern_documentation/python/core/list_index.py

@@ -0,0 +1,20 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.list_indexes()
+if r.error:
+    raise Exception(f"Failed to list indexes: {r.error}")
+
+indexes = r.result["indexes"]
+for index in indexes:
+    print(f"Index name: {index['name']}")
+    print(f"Chunk count: {index['count']}")
+    print(f"Document count: {index['parent_doc_count']}")

examples/fern_documentation/python/core/put_doc_into_index.py

@@ -0,0 +1,23 @@
+from cohere.compass.clients import CompassClient, CompassParserClient
+
+COMPASS_API_URL = ...
+PARSER_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+FOLDER_TO_PROCESS = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+compass_parser_client = CompassParserClient(parser_url=PARSER_URL)
+
+docs_to_index = compass_parser_client.process_folder(
+    folder_path=FOLDER_TO_PROCESS, recursive=True
+)
+
+compass_client.create_index(index_name=INDEX_NAME)
+r = compass_client.insert_docs(index_name=INDEX_NAME, docs=docs_to_index, num_jobs=1)
+
+print(r)

examples/fern_documentation/python/core/refresh_index.py

@@ -0,0 +1,14 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.refresh_index(index_name=INDEX_NAME)
+if r.error:
+    raise Exception(f"Failed to refresh indexes: {r.error}")

examples/fern_documentation/python/core/search_chunks.py

@@ -0,0 +1,19 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+SEARCH_QUERY = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.search_chunks(index_name=INDEX_NAME, query=SEARCH_QUERY)
+
+if r.error:
+    raise Exception(f"Failed to search: {r.error}")
+
+print(r.hits)

examples/fern_documentation/python/core/search_docs.py

@@ -0,0 +1,19 @@
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+SEARCH_QUERY = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.search_documents(index_name=INDEX_NAME, query=SEARCH_QUERY)
+
+if r.error:
+    raise Exception(f"Failed to search doc: {r.error}")
+
+print(r.hits)

examples/fern_documentation/python/core/update_group_auth.py

@@ -0,0 +1,28 @@
+from cohere.compass import GroupAuthorizationInput
+from cohere.compass.clients import CompassClient
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+AUTHORIZED_GROUP_NAME = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+r = compass_client.update_group_authorization(
+    index_name=INDEX_NAME,
+    group_auth_input=GroupAuthorizationInput(
+        document_ids=[DOCUMENT_ID],
+        authorized_groups=[AUTHORIZED_GROUP_NAME],
+        action=GroupAuthorizationInput.Actions.ADD,
+    ),
+)
+
+for doc in r.results:
+    if doc.error:
+        print(f"Error processing doc: {doc.document_id}, error: {doc.error}")
+        continue
+    print(f"Successfully processed doc: {doc.document_id}")

examples/fern_documentation/python/core/upload_files.py

@@ -0,0 +1,37 @@
+import uuid
+
+from cohere.compass.clients import CompassClient
+from cohere.compass.models import DocumentAttributes
+
+COMPASS_API_URL = ...
+BEARER_TOKEN = ...
+INDEX_NAME = ...
+DOCUMENT_ID = ...
+FILE_PATH = ...
+FILE_NAME = ...
+CONTENT_TYPE = ...
+
+compass_client = CompassClient(
+    index_url=COMPASS_API_URL,
+    bearer_token=BEARER_TOKEN,
+)
+
+doc_attr = DocumentAttributes()
+doc_attr.key = "value"
+
+file_path = FILE_PATH
+if not file_path:
+    raise Exception("FILE_PATH is required")
+
+with open(file_path, "rb") as f:
+    file_bytes = f.read()
+
+result = compass_client.upload_document(
+    index_name=INDEX_NAME,
+    filename=FILE_NAME,
+    filebytes=file_bytes,
+    content_type=CONTENT_TYPE,
+    document_id=uuid.uuid4(),
+)
+
+print(result)