Package: semantha-sdk
💜 semantha SDKThe semantha SDK is a high-level REST client to access thesemanthaAPI.
The SDK is updated in parallel to each new version of semantha (typically every 2 weeks). Use the same SDK version as your semantha server version.
An overview of the currently supported endpoints may be found at the end of this document (see section "State of Development").
The semantha SDK is compatible with python >= 3.8.🔬 Design guideline/ideaEvery 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()Parameters in the URL become method parameters:POST /api/domains/<your_domain>/referencedocuments -> api.domains("<your_domain>").referencedocuments.post(file=somefile)The SDK offers type hints and doc strings for services, parameters, input types and return types within your IDE.📝 ChangelogSee list of changes below.🚀 QuickstartIf you have access to semantha you can create your own login credentials: As a domain administrator go to "Administration" App -> then select "Client Administration" in the upper dropdown. Here you can add a new "client" by clicking "+ Add new". Configure "Domain Access", "App Access" (not used so far) and Roles. Click "Add" and download the credentials.properties file via the action menu. You can use this properties file to login with the SDK. See an example below.In case you are not a semantha user already you can request a demo access to semantha's API viathis contact form.Authentication with client credentials.properties fileimportsemantha_sdk# file name has to end with '.properties'!api=semantha_sdk.login(key_file="credentials.properties")print("Talking to semantha server: "+api.info.get().version)Alternatively you can set the 4 parameters: server_url, client_id, client_secret and token_url with the values from your credentials.properties files.importsemantha_sdkapi=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)Old: Authentication with API keyimportsemantha_sdkapi=semantha_sdk.login(server_url="<semantha server URL>",key="<your key>")print("Talking to semantha server: "+api.info.get().version)Old: Authentication with json key fileimportsemantha_sdk#file name has to end with '.json'!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 objectsmy_domain=api.domains("my_domain")# they may have sub-resources, which can be retrieved as objects as wellreference_documents=my_domain.referencedocuments# GET all reference documentsprint("Library contains "+len(reference_documents.get())+" entries")Example key file in json format:{"API_Key":"<your key>","server_url":"<your serverurl>"}CRUD on End-points# CRUD operations are functionsdomain_settings=my_domain.settings.get()#Warning: this deletes ALL reference documents/library entriesmy_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.groles_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 complexdocument=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 floatGetting an annotated pdf and saving it locallyimportsemantha_sdkapi=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)withopen('annotated.pdf','wb')asannotated_file:annotated_file.write(annotated_pdf.getbuffer())Changelog for the Python SDK for the semantha platform[6.9.0] 2024-02-23AddedAdded implementation method "post_json" for "overloaded" services where we have content type multipart/form-data as well as application/json:/bulk/domains/{domainname}/referencedocumentsPOST/domains/{domainname}/modelinstancesPOST/domains/{domainname}/referencedocumentsPOST/domains/{domainname}/similaritymatrix/clusterPOST[6.8.0] 2024-02-09RemovedRemoved two setting values: similarity_matcher and similarity_threshold for endpoint:/domains/{domainname}/settingsGETImprovedMore method and parameter commentsEndpoint/domainsGETreturns DomainInfo object now instead of Domain[6.7.0] 2024-01-29ImprovedMore class and method comments, improved styling[6.6.0] 2024-01-18AddedAdded transactions endpoint:/domains/{domainname}/transactionsGETRemovedRemoved deprecated endpoint:/domains/{domainname}/documentcomparisons[6.5.0] 2023-12-21ImprovedReuse session object of requests library to increase performance on multiple calls[6.4.0] 2023-12-07Removed/model/domains/{domainname}/documentcomparisonsPOST(Accept: xlsx)[6.3.0] 2023-11-21FixedPATCH and PUT methods with a list of dataclasses wasn't working.AddedAdded language parameter to /answers and /summarizations endpoints.[6.2.1] 2023-11-13FixedDataclasses aren't frozen anymore.Improved permission denied message with url.[6.2.0] 2023-11-09Addedserver_url is read from credentials.properties file now -> semantha_sdk.login(key_file = "credentials.properties") parameter key_file is enough now.server_url is read from json config file if present.Checks to normalize server_url[6.1.0] 2023-10-25This version should only be used with a semantha server version >= 6.1Changed/api/info is versioned now and SDK calls /api/v3/info internally. This is a breaking changelogin() function and SemanthaAPI class are generated now[6.0.1] 2023-10-17AddedSupport for OAuth 2.0 Client Credentials Flow for credentials created via Semantha Administration UI.[6.0.0] 2023-10-04FixedGET of files with different mimetype than application/json (e.g. get_as_docx)[5.11.1] 2023-09-21Removed/model/domains/{domainname}/extractortableshas been removed/model/domains/{domainname}/extractortables/{id}has been removedFixedfixed serialization on post of bulk endpoints with list of objects[5.11.0]Changed/api/domains/{domainname}/summarizationsreturns 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}/backupsSDK 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}/referencesFixed bug on serialization of/api/domains/{domainname}/modelinstancesresponse.
Fixed return of binary responses of bulk services.[5.4.0]Addednewservice:/api/domains/{domainname}/summarizationswhich generations a summarization for a given list of texts and a given topic.Added support forexistingservices:/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}/answerswith 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 usingsemantha_sdk.domains.get_one("domain_name").
Starting with 4.5.0 it issemantha_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 DevelopmentThe following resources and end-points are fully functional and (partially) tested:/bulk-> BulkEndpoint/bulk/domains-> BulkDomainsEndpoint/bulk/domains/{domainname}-> BulkdomainsDomainEndpoint/bulk/domains/{domainname}/documentclasses-> BulkdomainsDocumentclassesEndpointGET-> List[DocumentClassBulk]POST-> None/bulk/domains/{domainname}/documenttypes-> BulkdomainsDocumenttypesEndpointGET-> List[DocumentType]POST-> None/bulk/domains/{domainname}/referencedocuments-> BulkdomainsReferencedocumentsEndpointGET-> List[Document]POST-> NonePOST-> NoneDELETE-> None/bulk/domains/{domainname}/references-> BulkdomainsReferencesEndpointPOST-> List[Document]/bulk/model-> BulkModelEndpoint/bulk/model/domains-> BulkmodelDomainsEndpoint/bulk/model/domains/{domainname}-> BulkmodelDomainEndpoint/bulk/model/domains/{domainname}/boostwords-> BulkmodelBoostwordsEndpointPOST-> None/bulk/model/domains/{domainname}/classes-> BulkmodelClassesEndpointGET-> List[ClassBulk]POST-> None/bulk/model/domains/{domainname}/classes/{classid}-> BulkmodelClassEndpoint/bulk/model/domains/{domainname}/classes/{classid}/instances-> BulkmodelclassInstancesEndpointGET-> List[Instance]/bulk/model/domains/{domainname}/dataproperties-> BulkmodelDatapropertiesEndpointGET-> List[DataProperty]POST-> None/bulk/model/domains/{domainname}/instances-> BulkmodelInstancesEndpointGET-> List[Instance]POST-> None/bulk/model/domains/{domainname}/metadata-> BulkmodelMetadataEndpointGET-> List[ModelMetadata]POST-> None/bulk/model/domains/{domainname}/namedentities-> BulkmodelNamedentitiesEndpointPOST-> None/bulk/model/domains/{domainname}/rules-> BulkmodelRulesEndpointGET-> List[Rule]POST-> None/bulk/model/domains/{domainname}/stopwords-> BulkmodelStopwordsEndpointPOST-> None/bulk/model/domains/{domainname}/synonyms-> BulkmodelSynonymsEndpointPOST-> None/celltypes-> CelltypesEndpointGET-> List[CellType]/currentuser-> CurrentuserEndpointGET-> CurrentUser/currentuser/roles-> RolesEndpointGET-> List[str]/diff-> DiffEndpointPOST-> List[Difference]/domains-> DomainsEndpointGET-> List[DomainInfo]/domains/{domainname}-> DomainEndpointGET-> Domain/domains/{domainname}/answers-> AnswersEndpointPOST-> Answer/domains/{domainname}/documentannotations-> DocumentannotationsEndpointPOST(Accept: docx) -> IOBasePOST(Accept: pdf) -> IOBase/domains/{domainname}/documentclasses-> DocumentclassesEndpointGET-> List[DocumentClass]POST-> DocumentClassDELETE-> None/domains/{domainname}/documentclasses/{id}-> DocumentclassEndpointGET-> DocumentClassDELETE-> NonePUT-> DocumentClass/domains/{domainname}/documentclasses/{id}/customfields-> DocclassCustomfieldsEndpointDELETE-> NonePUT-> None/domains/{domainname}/documentclasses/{id}/documentclasses-> DocclassDocumentclassesEndpointGET-> List[DocumentClass]POST-> DocumentClassDELETE-> List[DocumentClass]PATCH-> List[DocumentClass]/domains/{domainname}/documentclasses/{id}/referencedocuments-> DocclassReferencedocumentsEndpointGET-> List[DocumentInformation]DELETE-> NonePATCH-> None/domains/{domainname}/documents-> DocumentsEndpointPOST-> List[Document]POST(Accept: xlsx) -> IOBasePOST(Accept: docx) -> IOBase/domains/{domainname}/documenttypes-> DocumenttypesEndpointGET-> List[DocumentType]POST-> DocumentTypeDELETE-> None/domains/{domainname}/documenttypes/{id}-> DocumenttypeEndpointGET-> DocumentTypeDELETE-> NonePATCH-> DocumentType/domains/{domainname}/documenttypes/{id}/clone-> CloneEndpointPOST-> DocumentType/domains/{domainname}/modelclasses-> ModelclassesEndpointGET-> List[ModelClass]/domains/{domainname}/modelinstances-> ModelinstancesEndpointPOST-> SemanticModelPOST-> SemanticModelPOST(Accept: xlsx) -> IOBase/domains/{domainname}/referencedocuments-> ReferencedocumentsEndpointGET-> ReferenceDocumentsResponseContainerGET(Accept: xlsx) -> IOBasePOST-> List[DocumentInformation]POST-> List[DocumentInformation]DELETE-> NonePATCH-> None/domains/{domainname}/referencedocuments/clusters-> ClustersEndpointGET-> SmartClusterResponseContainerPUT-> SmartClusterResponseContainer/domains/{domainname}/referencedocuments/namedentities-> NamedentitiesEndpointGET-> List[DocumentNamedEntity]/domains/{domainname}/referencedocuments/statistic-> StatisticEndpointGET-> Statistic/domains/{domainname}/referencedocuments/{documentid}-> ReferencedocumentEndpointGET-> DocumentDELETE-> NonePATCH-> DocumentInformation/domains/{domainname}/referencedocuments/{documentid}/paragraphs-> ParagraphsEndpoint/domains/{domainname}/referencedocuments/{documentid}/paragraphs/{id}-> ParagraphEndpointGET-> ParagraphDELETE-> NonePATCH-> Paragraph/domains/{domainname}/referencedocuments/{documentid}/sentences-> SentencesEndpoint/domains/{domainname}/referencedocuments/{documentid}/sentences/{id}-> SentenceEndpointGET-> Sentence/domains/{domainname}/references-> ReferencesEndpointPOST-> DocumentPOST(Accept: xlsx) -> IOBasePOST(Accept: docx) -> IOBasePOST(Accept: pdf) -> IOBase/domains/{domainname}/settings-> SettingsEndpointGET-> SettingsPATCH-> Settings/domains/{domainname}/similaritymatrix-> SimilaritymatrixEndpointPOST-> List[MatrixRow]/domains/{domainname}/similaritymatrix/cluster-> SimilaritymatrixClusterEndpointPOST-> List[MatrixRow]POST-> List[MatrixRow]/domains/{domainname}/summarizations-> SummarizationsEndpointPOST-> Summarization/domains/{domainname}/tags-> TagsEndpointGET-> List[str]/domains/{domainname}/tags/{tagname}-> TagEndpoint/domains/{domainname}/tags/{tagname}/referencedocuments-> TagReferencedocumentsEndpointGET-> List[DocumentInformation]DELETE-> None/domains/{domainname}/transactions-> TransactionsEndpointGET-> List[TransactionSummary]/domains/{domainname}/validation-> ValidationEndpointPOST-> SemanticModel/info-> InfoEndpointGET-> Info/languages-> LanguagesEndpointPOST-> LanguageDetection/model-> ModelEndpoint/model/datatypes-> ModelDatatypesEndpointGET-> List[str]/model/domains-> ModelDomainsEndpoint/model/domains/{domainname}-> ModelDomainEndpointGET(Accept: xlsx) -> IOBasePATCH-> IOBase/model/domains/{domainname}/attributes-> ModelAttributesEndpointGET-> List[AttributeOverview]/model/domains/{domainname}/backups-> ModelBackupsEndpointPOST-> None/model/domains/{domainname}/boostwords-> ModelBoostwordsEndpointGET-> List[BoostWord]POST-> BoostWordDELETE-> None/model/domains/{domainname}/boostwords/{id}-> ModelBoostwordEndpointGET-> BoostWordDELETE-> NonePUT-> BoostWord/model/domains/{domainname}/classes-> ModelontClassesEndpointGET-> List[ClassesOverview]POST-> ClazzDELETE-> None/model/domains/{domainname}/classes/{classid}-> ModelontClassEndpointGET-> ClazzDELETE-> NonePUT-> Clazz/model/domains/{domainname}/classes/{classid}/attributes-> ModelontAttributesEndpointGET-> List[Attribute]POST-> AttributeDELETE-> None/model/domains/{domainname}/classes/{classid}/attributes/{id}-> ModelontAttributeEndpointGET-> AttributeDELETE-> NonePUT-> Attribute/model/domains/{domainname}/classes/{classid}/instances-> ModelontclassInstancesEndpointGET-> List[Instance]DELETE-> None/model/domains/{domainname}/dataproperties-> ModelDatapropertiesEndpointGET-> List[Overview]POST-> DataPropertyDELETE-> None/model/domains/{domainname}/dataproperties/{id}-> ModelDatapropertyEndpointGET-> DataPropertyDELETE-> NonePUT-> DataProperty/model/domains/{domainname}/extractorclasses-> ModelExtractorclassesEndpointGET-> List[ExtractorClassOverview]POST-> ExtractorClassDELETE-> NonePUT-> None/model/domains/{domainname}/extractorclasses/{id}-> ModelExtractorclassEndpointGET-> ExtractorClassDELETE-> NonePUT-> ExtractorClass/model/domains/{domainname}/extractorclasses/{id}/extractorclasses-> ChildExtractorclassesEndpointPOST-> ExtractorClass/model/domains/{domainname}/extractors-> ModelExtractorsEndpointGET-> List[Entity]/model/domains/{domainname}/formatters-> ModelFormattersEndpointGET-> List[Formatter]/model/domains/{domainname}/instances-> ModelontInstancesEndpointGET-> List[InstanceOverview]GET(Accept: xlsx) -> IOBasePOST-> InstanceDELETE-> NonePATCH-> None/model/domains/{domainname}/instances/{id}-> ModelontInstanceEndpointGET-> InstanceDELETE-> NonePUT-> Instance/model/domains/{domainname}/metadata-> ModelMetadataEndpointGET-> List[ModelMetadata]POST-> ModelMetadataDELETE-> None/model/domains/{domainname}/metadata/{id}-> ModelOnemetadataEndpointGET-> ModelMetadataDELETE-> NonePUT-> ModelMetadata/model/domains/{domainname}/namedentities-> ModelNamedentitiesEndpointGET-> List[NamedEntity]POST-> NamedEntityDELETE-> None/model/domains/{domainname}/namedentities/{id}-> ModelNamedentityEndpointGET-> NamedEntityDELETE-> NonePUT-> NamedEntity/model/domains/{domainname}/objectproperties-> ModelObjectpropertiesEndpointGET-> List[Overview]/model/domains/{domainname}/regexes-> ModelRegexesEndpointGET-> List[Regex]POST-> RegexDELETE-> None/model/domains/{domainname}/regexes/{id}-> ModelRegexEndpointGET-> RegexDELETE-> NonePUT-> Regex/model/domains/{domainname}/relations-> ModelRelationsEndpointGET-> List[Relation]POST-> RelationDELETE-> None/model/domains/{domainname}/relations/{id}-> ModelRelationEndpointGET-> RelationDELETE-> NonePUT-> Relation/model/domains/{domainname}/rulefunctions-> ModelRulefunctionsEndpointGET-> List[RuleFunction]/model/domains/{domainname}/rules-> ModelRulesEndpointGET-> List[RuleOverview]POST-> RuleDELETE-> None/model/domains/{domainname}/rules/{id}-> ModelRuleEndpointGET-> RuleDELETE-> NonePUT-> Rule/model/domains/{domainname}/stopwords-> ModelStopwordsEndpointGET-> List[StopWord]POST-> StopWordDELETE-> None/model/domains/{domainname}/stopwords/{id}-> ModelStopwordEndpointGET-> StopWordDELETE-> NonePUT-> StopWord/model/domains/{domainname}/synonyms-> ModelSynonymsEndpointGET-> List[Synonym]POST-> SynonymDELETE-> None/model/domains/{domainname}/synonyms/{id}-> ModelSynonymEndpointGET-> SynonymDELETE-> NonePUT-> Synonym/model/extractortypes-> ModelExtractortypesEndpointGET-> List[str]/model/metadatatypes-> ModelMetadatatypesEndpointGET-> List[str]