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.

Disclaimer

IMPORTANT: The SDK is under development and interfaces may change at any time without notice. Use with caution and on own risk.

Update Note

Version 4.5.0 comes with a 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.

Access

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

Basic Usage

Import

import semantha_sdk

Authentication

semantha = semantha_sdk.login(url="<semantha platform server URL>", key="<your key>")
# or
semantha = semantha_sdk.login(url="<semantha platform server URL>", key_file="<path to your key file (json format)>")

End-point (Resource) Access

# end-points (resp. resources) can be used like objects
current_user = semantha.currentuser
my_domain = semantha.domains("my_domain")

# they may have sub-resources, which can be retrieved as objects as well
reference_documents = my_domain.referencedocuments

CRUD on End-points

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

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 DomainSettings
# 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

State of Development

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

login -> API
- .currentuser -> CurrentUser
  - get -> UserData(SemanthaModelEntity)
  - roles -> CurrentUserRoles
    - get -> list[str]
- .diff -> Diff
  - post -> list[Diff(SemanthaModelEntity)]
- .info -> VersionInfo
  - get -> VersionInfo
- .languages -> list[str]
- .domains -> Domains
  - get -> list[Domain(SemanthaModelEntity)]
- .domains("domain_name") -> Domain
  - .documentannotations -> DocumentAnnotations
    - post -> not yet implemented
  - .documentclasses -> DocumentClasses
    - get -> list[DocumentClass(SemanthaModelEntity)]
    - post -> DocumentClass(SemanthaModelEntity)
    - delete -> None
  - .documentclasses("id") -> DocumentClass
    - get -> DocumentClass(SemanthaModelEntity)
    - delete -> None
    - put -> DocumentClass(SemanthaModelEntity)
    - documentclasses -> InnerDocumentClasses
      - get -> list[DocumentClass(SemanthaModelEntity)]
      - post -> DocumentClass(SemanthaModelEntity)
    - referencedocuments -> InnerReferenceDocuments
      - get -> list[Document(SemanthaModelEntity)]
      - patch -> None
      - delete -> None
  - .documentcomparisons -> DocumentComparisons
    - post -> not yet implemented
    - .documents -> Documents
      - post -> list[Document(SemanthaModelEntity)]
  - .modelinstances -> ModelInstance
  - .modelclasses -> ModelClass
  - .referencedocuments -> ReferenceDocuments
    - get -> ReferenceDocuments(SemanthaModelEntity)
    - delete -> None
    - post -> list[DocumentInformation(SemanthaModelEntity)]
    - .clusters -> DocumentCluster
      - get -> DocumentCluster(SemanthaModelEntity)
    - .statistic -> Statistics
      - get -> Statistic(SemanthaModelEntity)
    - .namedentities -> NamedEntities
      - get -> Optional[NamedEntities(SemanthaModelEntity)]
  - .referencedocuments("id") -> ReferenceDocument
    - get -> Document(SemanthaModelEntity)
    - delete -> None
    - patch -> DocumentInformation(SemanthaModelEntity)
    - .paragraphs("id") -> ReferenceDocumentParagraph
      - get -> Paragraph(SemanthaModelEntity)
      - patch -> Paragraph(SemanthaModelEntity)
      - delete -> None
    - .sentences("id") -> ReferenceDocumentSentence
      - get -> Sentence(SemanthaModelEntity)
  - .references -> References
    - post -> Document(SemanthaModelEntity)
  - .settings -> DomainSettings
    - get -> DomainSettings(SemanthaModelEntity)
    - patch -> DomainSettings(SemanthaModelEntity)
  - .similaritymatrix -> List[MatrixRow]
    - .clusters -> List[MatrixRow]
  - .tags -> DomainTags
    - get -> list[str]
    - .("tag").referencedocuments
      - get
      - delete
  - .validation -> SemanticModel
- .model
  - .domains("domain_name")
    - .boostwords -> Boostwords
      - get -> list[Boostword(SemanthaModelEntity)]
      - delete -> None
      - post_word -> Boostword(SemanthaModelEntity)
      - post_regex -> Boostword(SemanthaModelEntity)
    - .boostwords("id") -> Boostword
      - get -> Boostword(SemanthaModelEntity)
      - delete -> None
      - put_word -> Boostword(SemanthaModelEntity)
      - put_regex -> Boostword(SemanthaModelEntity)
    - .synonyms -> Synonyms
      - get -> list[Synonym(SemanthaModelEntity)]
      - delete -> None
      - post_word -> Synonym(SemanthaModelEntity)
      - post_regex -> Synonym(SemanthaModelEntity)
    - .synonyms("id") -> Synonym
      - get -> Synonym(SemanthaModelEntity)
      - delete -> None
      - put_word -> Synonym(SemanthaModelEntity)
      - put_regex -> Synonym(SemanthaModelEntity)
    - .datatypes -> list[str]

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

semantha_sdk-4.8.0.tar.gz (30.8 kB view details)

Uploaded Mar 30, 2023 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

semantha_sdk-4.8.0-py3-none-any.whl (53.9 kB view details)

Uploaded Mar 30, 2023 Python 3

File details

Details for the file semantha_sdk-4.8.0.tar.gz.

File metadata

Download URL: semantha_sdk-4.8.0.tar.gz
Upload date: Mar 30, 2023
Size: 30.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: poetry/1.3.2 CPython/3.10.8 Windows/10

File hashes

Hashes for semantha_sdk-4.8.0.tar.gz
Algorithm	Hash digest
SHA256	`37106d5692d2de58c18dc394238b2beb6f8ede10c333d2e306b7de9cbdebc3e8`
MD5	`81b8eee8b4c6cfcebfabf2d1a8b8e406`
BLAKE2b-256	`43e5072d7399a756b0584b9071075d1af3c63d5de7eca0bc8364b393af5f97e4`

See more details on using hashes here.

File details

Details for the file semantha_sdk-4.8.0-py3-none-any.whl.

File metadata

Download URL: semantha_sdk-4.8.0-py3-none-any.whl
Upload date: Mar 30, 2023
Size: 53.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: poetry/1.3.2 CPython/3.10.8 Windows/10

File hashes

Hashes for semantha_sdk-4.8.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`2a675d97b3fb5c1ffd1d653df8f6abfafe36117158782add0e28eefd0c7042d7`
MD5	`4c6fb6b020b777cab3ae7df5af6ed50a`
BLAKE2b-256	`c49a5643551586bc4722726d1c9e7719632c575a9563e4303a9fa611dab41712`