semantha SDK

The semantha SDK is a high-level REST client to access the semantha API. The SDK is still under development. An overview of the current progress (i.e. implemented and tested resources and endpoints) may be found at the end of this document (State of Development). The semantha SDK is compatible with python >= 3.8.

Design guideline/idea

Every api call can easily be translated into a python sdk call where the HTTP method becomes the last method: GET /api/info -> api.info.get() The SDK offers type hints and doc strings for services, parameters, input types and return types within your IDE.

Changelog

See list of changes below.

Access

To access semantha's API you will need an API and a server url. Both can be requested via this contact form.

If you have access to semantha you can create your own client credentials: As a domain administrator go to "Administration" App -> then select "Client Administration" in the upper dropdown. Here you can add a new "client" and download the credentials file. You can use this properties file to login with the SDK.

Quickstart

Authentication with client credentials properties file

import semantha_sdk
api = semantha_sdk.login(server_url="<semantha server URL>", key_file="credentials.properties")
print("Talking to semantha server: " + api.info.get().version)

Alternatively you can set the 3 parameters: client_id, client_secret and token_url with the values from your credentials.properties files.

import semantha_sdk
api = semantha_sdk.login(server_url="<semantha server URL>", client_id="<id>", client_secret="<secret>", token_url="<url>")
print("Talking to semantha server: " + api.info.get().version)

Authentication with API key

import semantha_sdk
api = semantha_sdk.login(server_url="<semantha server URL>", key="<your key>")
print("Talking to semantha server: " + api.info.get().version)

Authentication with json key file

import semantha_sdk
api = semantha_sdk.login(server_url="<semantha server URL>", key_file="<path to your key file (json format)>")
# end-points (resp. resources) can be used like objects
my_domain = api.domains("my_domain")
# they may have sub-resources, which can be retrieved as objects as well
reference_documents = my_domain.referencedocuments
# GET all reference documents
print("Library contains "+ len(reference_documents.get()) + " entries")

Example key file in json format:

{ "API_Key" : "<your key>" }

CRUD on End-points

# CRUD operations are functions
domain_settings = my_domain.settings.get()
#Warning: this deletes ALL reference documents/library entries
my_domain.referencedocuments.delete() 

Function Return Types & semantha Data Model

# some functions only return None, e.g.
my_domain.referencedocuments.delete() # returns NoneType

# others return built in types, e.g
roles_list = currentuser.roles.get() # returns List[str]

# but most return objects of the semantha Data Model
# (all returned objects are instances of frozen dataclasses)
settings = my_domain.settings.get() # returns instance of Settings
# attributes can be accessed as properties, e.g.
settings.enable_tagging # returns true or false
# Data Model objects may be complex
document = my_domain.references.post(file=a, referencedocument=b) # returns instance of Document
# the following returns the similarity value of the first references of the first sentence of the
# the first paragraph on the first page of the document (if a reference was found for this sentence)
similarity = pages[0].contents[0].paragraphs[0].references[0].similarity # returns float

Getting an annotated pdf and saving it locally

import semantha_sdk
api = semantha_sdk.login(server_url="<semantha server URL>", key="<your key>")
domain = "<your domain>"
pdf = open('<your_file>.pdf', 'rb')
annotated_pdf = api.domains(domain).documentannotations.post_as_pdf(file=pdf, similaritythreshold=0.85)
with open('annotated.pdf', 'wb') as annotated_file:
    annotated_file.write(annotated_pdf.getbuffer())

Changelog for the Python SDK for the semantha platform

[6.0.1] 2023-10-17

Added

• Support for OAuth 2.0 Client Credentials Flow for credentials created via Semantha Administration UI.

[6.0.0] 2023-10-04

Fixed

• GET of files with different mimetype than application/json (e.g. get_as_docx)

[5.11.1] 2023-09-21

Removed

• /model/domains/{domainname}/extractortables has been removed
• /model/domains/{domainname}/extractortables/{id} has been removed

Fixed

• fixed serialization on post of bulk endpoints with list of objects

[5.11.0]

Changed

• /api/domains/{domainname}/summarizations returns an object now instead of string.
• renamed class Metadata to ModelMetadata

[5.10.0]

Improved Use Case SDK

[5.9.0]

Removed

• /api/domains/{domainname}/referencedocuments/{documentid}/paragraphs/{id}/links

[5.8.0]

Added

• /api/domains/{domainname}/documentclasses/{id}/documentclasses
• /api/domains/{domainname}/documentclasses/{id}/referencedocuments
• /api/domains/{domainname}/referencedocuments/{documentid}/paragraphs/{id}/links
• /api/model/domains/{domainname}/backups

SDK covers now 193/197 services.

[5.7.0]

Added new endpoints in:

• /api/domains/{domainname}/documenttypes/*
• /api/domains/{domainname}/documentclasses/{id}/customfields
• /api/model/domains/{domainname}/classes/*

SDK covers now 184/197 services.

[5.6.0]

Added most endpoints in */api/models/ ** SDK covers now 158/180 services.

[5.5.0]

Removed language parameter on /api/domains/{domainname}/references Fixed bug on serialization of /api/domains/{domainname}/modelinstances response. Fixed return of binary responses of bulk services.

[5.4.0]

Added new service:

• /api/domains/{domainname}/summarizations which generations a summarization for a given list of texts and a given topic.

Added support for existing services:

• /api/model/domains/{domainname}/boostwords/{id}
• /api/model/domains/{domainname}/namedentities
• /api/model/domains/{domainname}/namedentities/{id}
• /api/model/domains/{domainname}/stopwords
• /api/model/domains/{domainname}/stopwords/{id}
• /api/model/domains/{domainname}/synonyms/{id}

[5.3.0]

Added new service: /api/domains/{domainid}/answers with retrieval augemented answer generation based on your library entries. Added new parameter on /modelinstances

[5.2.0]

The SDK is now automatically generated from our openapi.json specification. It covers 71/169 (=42%) of all available services. Many class names and package names have been changed.

[4.5.0]

Major restructuring of the SDK. All sub-resources are directly accessible (instead of invoking getters). That also means that (except for a few) all functions are plain get/post/delete/put/patch. For example, in Versions < 4.5.0 a domain resource was fetched using semantha_sdk.domains.get_one("domain_name"). Starting with 4.5.0 it is semantha_sdk.domains("domain_name"). That also means that get/post/put/patch functions return semantha model objects (and never resources), which makes usage more consistent.

State of Development

The following resources and end-points are fully functional and (partially) tested:

• /bulk -> BulkEndpoint
• /bulk/domains -> BulkDomainsEndpoint
• /bulk/domains/{domainname} -> BulkdomainsDomainEndpoint
• /bulk/domains/{domainname}/documentclasses -> BulkdomainsDocumentclassesEndpoint
  • GET -> List[DocumentClassBulk]
  • POST -> None
• /bulk/domains/{domainname}/documenttypes -> BulkdomainsDocumenttypesEndpoint
  • GET -> List[DocumentType]
  • POST -> None
• /bulk/domains/{domainname}/referencedocuments -> BulkdomainsReferencedocumentsEndpoint
  • GET -> List[Document]
  • POST -> None
  • DELETE -> None
• /bulk/domains/{domainname}/references -> BulkdomainsReferencesEndpoint
  • POST -> List[Document]
• /bulk/model -> BulkModelEndpoint
• /bulk/model/domains -> BulkmodelDomainsEndpoint
• /bulk/model/domains/{domainname} -> BulkmodelDomainEndpoint
• /bulk/model/domains/{domainname}/boostwords -> BulkmodelBoostwordsEndpoint
  • POST -> None
• /bulk/model/domains/{domainname}/classes -> BulkmodelClassesEndpoint
  • GET -> List[ClassBulk]
  • POST -> None
• /bulk/model/domains/{domainname}/classes/{classid} -> BulkmodelClassEndpoint
• /bulk/model/domains/{domainname}/classes/{classid}/instances -> BulkmodelclassInstancesEndpoint
  • GET -> List[Instance]
• /bulk/model/domains/{domainname}/dataproperties -> BulkmodelDatapropertiesEndpoint
  • GET -> List[DataProperty]
  • POST -> None
• /bulk/model/domains/{domainname}/instances -> BulkmodelInstancesEndpoint
  • GET -> List[Instance]
  • POST -> None
• /bulk/model/domains/{domainname}/metadata -> BulkmodelMetadataEndpoint
  • GET -> List[ModelMetadata]
  • POST -> None
• /bulk/model/domains/{domainname}/namedentities -> BulkmodelNamedentitiesEndpoint
  • POST -> None
• /bulk/model/domains/{domainname}/rules -> BulkmodelRulesEndpoint
  • GET -> List[Rule]
  • POST -> None
• /bulk/model/domains/{domainname}/stopwords -> BulkmodelStopwordsEndpoint
  • POST -> None
• /bulk/model/domains/{domainname}/synonyms -> BulkmodelSynonymsEndpoint
  • POST -> None
• /celltypes -> CelltypesEndpoint
  • GET -> List[CellType]
• /currentuser -> CurrentuserEndpoint
  • GET -> CurrentUser
• /currentuser/roles -> RolesEndpoint
  • GET -> List[str]
• /diff -> DiffEndpoint
  • POST -> List[Difference]
• /domains -> DomainsEndpoint
  • GET -> List[Domain]
• /domains/{domainname} -> DomainEndpoint
  • GET -> Domain
• /domains/{domainname}/answers -> AnswersEndpoint
  • POST -> Answer
• /domains/{domainname}/documentannotations -> DocumentannotationsEndpoint
  • POST (Accept: docx) -> IOBase
  • POST (Accept: pdf) -> IOBase
• /domains/{domainname}/documentclasses -> DocumentclassesEndpoint
  • GET -> List[DocumentClass]
  • POST -> DocumentClass
  • DELETE -> None
• /domains/{domainname}/documentclasses/{id} -> DocumentclassEndpoint
  • GET -> DocumentClass
  • DELETE -> None
  • PUT -> DocumentClass
• /domains/{domainname}/documentclasses/{id}/customfields -> DocclassCustomfieldsEndpoint
  • DELETE -> None
  • PUT -> None
• /domains/{domainname}/documentclasses/{id}/documentclasses -> DocclassDocumentclassesEndpoint
  • GET -> List[DocumentClass]
  • POST -> DocumentClass
  • DELETE -> List[DocumentClass]
  • PATCH -> List[DocumentClass]
• /domains/{domainname}/documentclasses/{id}/referencedocuments -> DocclassReferencedocumentsEndpoint
  • GET -> List[DocumentInformation]
  • DELETE -> None
  • PATCH -> None
• /domains/{domainname}/documentcomparisons -> DocumentcomparisonsEndpoint
  • POST (Accept: xlsx) -> IOBase
• /domains/{domainname}/documents -> DocumentsEndpoint
  • POST -> List[Document]
  • POST (Accept: xlsx) -> IOBase
  • POST (Accept: docx) -> IOBase
• /domains/{domainname}/documenttypes -> DocumenttypesEndpoint
  • GET -> List[DocumentType]
  • POST -> DocumentType
  • DELETE -> None
• /domains/{domainname}/documenttypes/{id} -> DocumenttypeEndpoint
  • GET -> DocumentType
  • DELETE -> None
  • PATCH -> DocumentType
• /domains/{domainname}/documenttypes/{id}/clone -> CloneEndpoint
  • POST -> DocumentType
• /domains/{domainname}/modelclasses -> ModelclassesEndpoint
  • GET -> List[ModelClass]
• /domains/{domainname}/modelinstances -> ModelinstancesEndpoint
  • POST -> SemanticModel
  • POST (Accept: xlsx) -> IOBase
• /domains/{domainname}/referencedocuments -> ReferencedocumentsEndpoint
  • GET -> ReferenceDocumentsResponseContainer
  • GET (Accept: xlsx) -> IOBase
  • POST -> List[DocumentInformation]
  • DELETE -> None
  • PATCH -> None
• /domains/{domainname}/referencedocuments/clusters -> ClustersEndpoint
  • GET -> SmartClusterResponseContainer
  • PUT -> SmartClusterResponseContainer
• /domains/{domainname}/referencedocuments/namedentities -> NamedentitiesEndpoint
  • GET -> List[DocumentNamedEntity]
• /domains/{domainname}/referencedocuments/statistic -> StatisticEndpoint
  • GET -> Statistic
• /domains/{domainname}/referencedocuments/{documentid} -> ReferencedocumentEndpoint
  • GET -> Document
  • DELETE -> None
  • PATCH -> DocumentInformation
• /domains/{domainname}/referencedocuments/{documentid}/paragraphs -> ParagraphsEndpoint
• /domains/{domainname}/referencedocuments/{documentid}/paragraphs/{id} -> ParagraphEndpoint
  • GET -> Paragraph
  • DELETE -> None
  • PATCH -> Paragraph
• /domains/{domainname}/referencedocuments/{documentid}/sentences -> SentencesEndpoint
• /domains/{domainname}/referencedocuments/{documentid}/sentences/{id} -> SentenceEndpoint
  • GET -> Sentence
• /domains/{domainname}/references -> ReferencesEndpoint
  • POST -> Document
  • POST (Accept: xlsx) -> IOBase
  • POST (Accept: docx) -> IOBase
  • POST (Accept: pdf) -> IOBase
• /domains/{domainname}/settings -> SettingsEndpoint
  • GET -> Settings
  • PATCH -> Settings
• /domains/{domainname}/similaritymatrix -> SimilaritymatrixEndpoint
  • POST -> List[MatrixRow]
• /domains/{domainname}/similaritymatrix/cluster -> SimilaritymatrixClusterEndpoint
  • POST -> List[MatrixRow]
• /domains/{domainname}/summarizations -> SummarizationsEndpoint
  • POST -> Summarization
• /domains/{domainname}/tags -> TagsEndpoint
  • GET -> List[str]
• /domains/{domainname}/tags/{tagname} -> TagEndpoint
• /domains/{domainname}/tags/{tagname}/referencedocuments -> TagReferencedocumentsEndpoint
  • GET -> List[DocumentInformation]
  • DELETE -> None
• /domains/{domainname}/validation -> ValidationEndpoint
  • POST -> SemanticModel
• /info -> InfoEndpoint
  • GET -> Info
• /languages -> LanguagesEndpoint
  • POST -> LanguageDetection
• /model -> ModelEndpoint
• /model/datatypes -> ModelDatatypesEndpoint
  • GET -> List[str]
• /model/domains -> ModelDomainsEndpoint
• /model/domains/{domainname} -> ModelDomainEndpoint
  • GET (Accept: xlsx) -> IOBase
  • PATCH -> IOBase
• /model/domains/{domainname}/attributes -> ModelAttributesEndpoint
  • GET -> List[AttributeOverview]
• /model/domains/{domainname}/backups -> ModelBackupsEndpoint
  • POST -> None
• /model/domains/{domainname}/boostwords -> ModelBoostwordsEndpoint
  • GET -> List[BoostWord]
  • POST -> BoostWord
  • DELETE -> None
• /model/domains/{domainname}/boostwords/{id} -> ModelBoostwordEndpoint
  • GET -> BoostWord
  • DELETE -> None
  • PUT -> BoostWord
• /model/domains/{domainname}/classes -> ModelontClassesEndpoint
  • GET -> List[ClassesOverview]
  • POST -> Clazz
  • DELETE -> None
• /model/domains/{domainname}/classes/{classid} -> ModelontClassEndpoint
  • GET -> Clazz
  • DELETE -> None
  • PUT -> Clazz
• /model/domains/{domainname}/classes/{classid}/attributes -> ModelontAttributesEndpoint
  • GET -> List[Attribute]
  • POST -> Attribute
  • DELETE -> None
• /model/domains/{domainname}/classes/{classid}/attributes/{id} -> ModelontAttributeEndpoint
  • GET -> Attribute
  • DELETE -> None
  • PUT -> Attribute
• /model/domains/{domainname}/classes/{classid}/instances -> ModelontclassInstancesEndpoint
  • GET -> List[Instance]
  • DELETE -> None
• /model/domains/{domainname}/dataproperties -> ModelDatapropertiesEndpoint
  • GET -> List[Overview]
  • POST -> DataProperty
  • DELETE -> None
• /model/domains/{domainname}/dataproperties/{id} -> ModelDatapropertyEndpoint
  • GET -> DataProperty
  • DELETE -> None
  • PUT -> DataProperty
• /model/domains/{domainname}/extractorclasses -> ModelExtractorclassesEndpoint
  • GET -> List[ExtractorClassOverview]
  • POST -> ExtractorClass
  • DELETE -> None
  • PUT -> None
• /model/domains/{domainname}/extractorclasses/{id} -> ModelExtractorclassEndpoint
  • GET -> ExtractorClass
  • DELETE -> None
  • PUT -> ExtractorClass
• /model/domains/{domainname}/extractorclasses/{id}/extractorclasses -> ChildExtractorclassesEndpoint
  • POST -> ExtractorClass
• /model/domains/{domainname}/extractors -> ModelExtractorsEndpoint
  • GET -> List[Entity]
• /model/domains/{domainname}/formatters -> ModelFormattersEndpoint
  • GET -> List[Formatter]
• /model/domains/{domainname}/instances -> ModelontInstancesEndpoint
  • GET -> List[InstanceOverview]
  • GET (Accept: xlsx) -> IOBase
  • POST -> Instance
  • DELETE -> None
  • PATCH -> None
• /model/domains/{domainname}/instances/{id} -> ModelontInstanceEndpoint
  • GET -> Instance
  • DELETE -> None
  • PUT -> Instance
• /model/domains/{domainname}/metadata -> ModelMetadataEndpoint
  • GET -> List[ModelMetadata]
  • POST -> ModelMetadata
  • DELETE -> None
• /model/domains/{domainname}/metadata/{id} -> ModelOnemetadataEndpoint
  • GET -> ModelMetadata
  • DELETE -> None
  • PUT -> ModelMetadata
• /model/domains/{domainname}/namedentities -> ModelNamedentitiesEndpoint
  • GET -> List[NamedEntity]
  • POST -> NamedEntity
  • DELETE -> None
• /model/domains/{domainname}/namedentities/{id} -> ModelNamedentityEndpoint
  • GET -> NamedEntity
  • DELETE -> None
  • PUT -> NamedEntity
• /model/domains/{domainname}/objectproperties -> ModelObjectpropertiesEndpoint
  • GET -> List[Overview]
• /model/domains/{domainname}/regexes -> ModelRegexesEndpoint
  • GET -> List[Regex]
  • POST -> Regex
  • DELETE -> None
• /model/domains/{domainname}/regexes/{id} -> ModelRegexEndpoint
  • GET -> Regex
  • DELETE -> None
  • PUT -> Regex
• /model/domains/{domainname}/relations -> ModelRelationsEndpoint
  • GET -> List[Relation]
  • POST -> Relation
  • DELETE -> None
• /model/domains/{domainname}/relations/{id} -> ModelRelationEndpoint
  • GET -> Relation
  • DELETE -> None
  • PUT -> Relation
• /model/domains/{domainname}/rulefunctions -> ModelRulefunctionsEndpoint
  • GET -> List[RuleFunction]
• /model/domains/{domainname}/rules -> ModelRulesEndpoint
  • GET -> List[RuleOverview]
  • POST -> Rule
  • DELETE -> None
• /model/domains/{domainname}/rules/{id} -> ModelRuleEndpoint
  • GET -> Rule
  • DELETE -> None
  • PUT -> Rule
• /model/domains/{domainname}/stopwords -> ModelStopwordsEndpoint
  • GET -> List[StopWord]
  • POST -> StopWord
  • DELETE -> None
• /model/domains/{domainname}/stopwords/{id} -> ModelStopwordEndpoint
  • GET -> StopWord
  • DELETE -> None
  • PUT -> StopWord
• /model/domains/{domainname}/synonyms -> ModelSynonymsEndpoint
  • GET -> List[Synonym]
  • POST -> Synonym
  • DELETE -> None
• /model/domains/{domainname}/synonyms/{id} -> ModelSynonymEndpoint
  • GET -> Synonym
  • DELETE -> None
  • PUT -> Synonym
• /model/extractortypes -> ModelExtractortypesEndpoint
  • GET -> List[str]
• /model/metadatatypes -> ModelMetadatatypesEndpoint
  • GET -> List[str]