Perseus

https://docs.perseus.lettria.net/docs
Admin
Perseus is Lettria's Text-to-Graph engine that transforms unstructured text into structured...
Tokens:11,568
Snippets:114
Trust Score:4.2
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Perseus Client SDK

Source: https://docs.perseus.lettria.net/docs/index

Installs the Perseus client SDK version 1.0.0-rc.2 using pip. This is the first step to using the Perseus client for graph building.

```bash
pip install perseus-client==1.0.0-rc.2
```

--------------------------------

### Build Graph using Perseus Client

Source: https://docs.perseus.lettria.net/docs/index

Demonstrates how to build a knowledge graph from a specified text file using the `PerseusClient`. It requires a Lettria API key for authentication, which is automatically loaded from environment variables.

```python
from perseus_client.client import PerseusClient

with PerseusClient() as client:
    client.build_graph(
        file_path="assets/pizza.txt",
    )
```

--------------------------------

### Install Python Dependencies and Start Services

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Installs the required Python packages listed in 'requirements.txt' and starts the necessary services using Docker Compose. The embedder service may require a few minutes to initialize on its first run as it downloads its model.

```bash
pip install -r requirements.txt
docker compose up -d
```

--------------------------------

### Clone Perseus Client Repository

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Clones the Perseus client repository from GitHub and navigates to the advanced graph-RAG reporting example directory. This command is essential for obtaining the project's source code and example files.

```bash
git clone https://github.com/Lettria/perseus-client.git
cd perseus-client/examples/advanced/graph-rag-reporting
```

--------------------------------

### Create Ontology Record and Get Upload URL (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Creates a new ontology record on the server and provides a presigned URL for uploading the ontology's content. This function requires the ontology's name and the SHA256 hash of its content. It returns a dictionary containing the created Ontology object and the upload URL.

```python
async def create_ontology(name: str, source_hash: str) -> Dict:
    # Implementation details omitted for brevity
    pass
```

```python
def create_ontology(name: str, source_hash: str) -> Dict:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Explore Extracted Data with SPARQL

Source: https://docs.perseus.lettria.net/docs/cookbooks/finance-compliance

Runs a Python script to read local .ttl files generated by the index script. It displays a summary of extracted entities and allows querying the data using SPARQL. An example query for GHG Emissions is provided.

```python
python explore.py
```

```sparql
SELECT ?label ?value ?unit ?year
WHERE {
    ?metric a ?type .
    FILTER(CONTAINS(STR(?type), "GHGEmissionsMetric"))
    ?metric rdfs:label ?label .
    OPTIONAL { ?metric ont:hasValue ?value }
    OPTIONAL { ?metric ont:hasUnit ?unit }
    OPTIONAL { ?metric ont:hasYear ?year }
    FILTER(CONTAINS(STR(?label), "Scope 1") ||
          CONTAINS(STR(?label), "Scope 2") ||
          CONTAINS(STR(?label), "Scope 3 Emissions 2024"))
}
```

--------------------------------

### Verify ESRS E1 Compliance with Cypher

Source: https://docs.perseus.lettria.net/docs/cookbooks/finance-compliance

Connects to the Neo4j database and runs Cypher queries to check for ESRS E1 compliance indicators. It outputs a compliance scorecard for each company. Example queries for GHG Emissions Disclosure and Strategic Program with Pillars are included.

```python
python compliance.py
```

```cypher
MATCH (c:Company {label: $name})-[:hasMetric]->(m:GHGEmissionsMetric)
RETURN count(m) > 0 AS present
```

```cypher
MATCH (c:Company {label: $name})-[:hasProgram]->(p:StrategicProgram)-[:hasPillar]->(pillar)
RETURN count(pillar) > 0 AS present
```

--------------------------------

### Async Client Initialization using Context Manager

Source: https://docs.perseus.lettria.net/docs/client/initialization

Initializes the PerseusClient as an asynchronous context manager for use in async environments. Ensures proper resource management during initialization and cleanup. Requires the `perseus_client` library.

```python
import asyncio
from perseus_client import PerseusClient

async def main():
    async with PerseusClient() as client:
        await client.build_graph_async(
            file_path="assets/pizza.txt",
        )

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Manual Client Initialization and Closing

Source: https://docs.perseus.lettria.net/docs/client/initialization

Demonstrates manual initialization and closing of the PerseusClient. This method requires explicit calls to `client.close()` to ensure resources are properly released. Requires the `perseus_client` library.

```python
from perseus_client.client import PerseusClient

client = PerseusClient()
client.build_graph(
    file_path="assets/pizza.txt",
)
client.close()
```

--------------------------------

### Build Knowledge Graph with Perseus Client

Source: https://docs.perseus.lettria.net/docs/cookbooks/finance-compliance

Executes the Perseus client to build a knowledge graph from a source document using a specified ontology. This process uploads the document and ontology to the Perseus platform, extracts structured information into a local .ttl file, and loads it into a Neo4j database.

```python
python index.py assets/ecosteel_annual_report.md
python index.py assets/techgreen_press_release.md
```

--------------------------------

### Create File Record (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Creates a file record on the server, typically used before uploading file content. It requires the file's name and its SHA256 content hash. The function returns a dictionary containing a File object and a presigned URL for uploading the file's content.

```python
async def create_file(name: str, source_hash: str) -> Dict:
    # ... implementation details ...
    pass
```

```python
def create_file(name: str, source_hash: str) -> Dict:
    # ... implementation details ...
    pass
```

--------------------------------

### Download Job Output (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Downloads the output files (.ttl and .cql) for a specified job ID. Optionally, a local path can be provided to save the files. The function returns the base path where the files were saved.

```python
async def download_job_output(job_id: str, output_path: Optional[str] = None) -> str:
    # Implementation details...
    pass
```

```python
def download_job_output(job_id: str, output_path: Optional[str] = None) -> str:
    # Implementation details...
    pass
```

--------------------------------

### Create File

Source: https://docs.perseus.lettria.net/docs/client/services/file

Creates a file record on the server and returns a presigned URL for uploading the file content. This is typically used as a preliminary step before uploading the actual file data.

```APIDOC
## POST /files/create

### Description
Creates a file record on the server and returns a presigned URL for uploading the file content.

### Method
POST

### Endpoint
/files/create

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - The name of the file.
- **source_hash** (str) - Required - The SHA256 hash of the file's content.

### Request Example
```json
{
  "name": "document.pdf",
  "source_hash": "a1b2c3d4e5f67890..."
}
```

### Response
#### Success Response (200)
- **file** (File) - A File object representing the newly created file.
- **upload_url** (str) - A presigned URL to which the file content should be uploaded.

#### Response Example
```json
{
  "file": {
    "id": "file-67890",
    "name": "document.pdf",
    "status": "PENDING_UPLOAD",
    "created_at": "2023-10-27T10:05:00Z"
  },
  "upload_url": "https://perseus-uploads.s3.amazonaws.com/...?AWSAccessKeyId=..."
}
```
```

--------------------------------

### Build Graph Synchronously (Python)

Source: https://docs.perseus.lettria.net/docs/client/methods

Builds a graph synchronously from a specified file path. Optionally accepts an ontology path, output path, and flags for saving to Neo4j or refreshing the graph. Returns a Job object representing the operation.

```python
def build_graph(
    file_path: str,
    ontology_path: Optional[str] = None,
    output_path: Optional[str] = None,
    save_to_neo4j: bool = False,
    refresh_graph: bool = False,
) -> Job:
```

--------------------------------

### Build Graph Asynchronously (Python)

Source: https://docs.perseus.lettria.net/docs/client/methods

Builds a graph asynchronously from a specified file path. Optionally accepts an ontology path, output path, and flags for saving to Neo4j or refreshing the graph. Returns a Job object representing the operation.

```python
async def build_graph_async(
    file_path: str,
    ontology_path: Optional[str] = None,
    output_path: Optional[str] = None,
    save_to_neo4j: bool = False,
    refresh_graph: bool = False,
) -> Job:
```

--------------------------------

### Copy Environment Template

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Copies the template environment file to a new file named '.env'. This new file should then be configured with your Perseus API key. This step is crucial for setting up the application's environment variables.

```bash
cp template.env .env
```

--------------------------------

### Upload File (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Uploads a file to the Perseus API. This function first checks if a file with identical content already exists. If so, it returns the existing file; otherwise, it creates a new file record and provides a presigned URL for content upload. It requires the local file path as input and returns a File object.

```python
async def upload_file(file_path: str) -> File:
    # ... implementation details ...
    pass
```

```python
def upload_file(file_path: str) -> File:
    # ... implementation details ...
    pass
```

--------------------------------

### Create Ontology API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Creates a new ontology record on the server. This endpoint returns a presigned URL which should be used to upload the actual content of the ontology.

```APIDOC
## POST /ontology/create

### Description
Creates an ontology record on the server and returns a presigned URL for uploading the ontology content.

### Method
POST

### Endpoint
/ontology/create

### Parameters
#### Request Body
- **name** (str) - Required - The name of the ontology.
- **source_hash** (str) - Required - The SHA256 hash of the ontology file's content.

### Request Example
```json
{
  "name": "My New Ontology",
  "source_hash": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef123456"
}
```

### Response
#### Success Response (200)
- **ontology** (Ontology) - An Ontology object representing the newly created ontology.
- **upload_url** (str) - A presigned URL to which the ontology content should be uploaded.

#### Response Example
```json
{
  "ontology": {
    "id": "f0e9d8c7-b6a5-4321-0987-654321fedcba",
    "name": "My New Ontology",
    "status": "PENDING_UPLOAD",
    "created_at": "2023-10-27T10:05:00Z"
  },
  "upload_url": "https://example.com/upload/url/for/ontology"
}
```
```

--------------------------------

### Find Files by IDs or Hashes (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Retrieves a list of files based on provided file IDs or their SHA256 source hashes. This function is useful for batch retrieval of file information. It accepts optional lists of IDs and/or source hashes and returns a list of matching File objects, or an empty list if none are found.

```python
async def find_files(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[File]:
    # ... implementation details ...
    pass
```

```python
def find_files(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[File]:
    # ... implementation details ...
    pass
```

--------------------------------

### Run Job (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Submits a job and waits for its completion. This function encapsulates job submission and polling for status updates. It takes a file ID and an optional ontology ID, and returns the completed Job object. Parameters include polling interval and timeout.

```python
async def run_job(file_id: str, ontology_id: Optional[str] = None, polling_interval: int = 5, timeout: int = 3600) -> Job:
    # Implementation details...
    pass
```

```python
def run_job(file_id: str, ontology_id: Optional[str] = None, polling_interval: int = 5, timeout: int = 3600) -> Job:
    # Implementation details...
    pass
```

--------------------------------

### Upload Ontology to Perseus API (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Uploads an ontology file to the Perseus API. This function handles both creating the ontology record and uploading its content to a presigned URL. If an ontology with identical content already exists, it is returned without re-uploading. It requires the local path to the ontology file as input and returns an Ontology object.

```python
async def upload_ontology(ontology_path: str) -> Ontology:
    # Implementation details omitted for brevity
    pass
```

```python
def upload_ontology(ontology_path: str) -> Ontology:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Submit Job (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Submits a job for processing. This function takes a file ID and an optional ontology ID, returning the initial Job object with a PENDING status. It is a prerequisite for running or monitoring jobs.

```python
async def submit_job(file_id: str, ontology_id: Optional[str] = None) -> Job:
    # Implementation details...
    pass
```

```python
def submit_job(file_id: str, ontology_id: Optional[str] = None) -> Job:
    # Implementation details...
    pass
```

--------------------------------

### Upload Ontology API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Uploads an ontology file to the Perseus API. This function handles both creating the ontology record and uploading its content to a presigned URL. If an ontology with identical content already exists, it is returned without re-uploading.

```APIDOC
## POST /ontology/upload

### Description
Uploads an ontology file to the Perseus API. If an ontology with the same content already exists, it will be returned without uploading.

### Method
POST

### Endpoint
/ontology/upload

### Parameters
#### Query Parameters
- **ontology_path** (str) - Required - The local path to the ontology file to upload.

### Request Example
```json
{
  "ontology_path": "/path/to/your/ontology.owl"
}
```

### Response
#### Success Response (200)
- **ontology** (Ontology) - An Ontology object representing the uploaded or existing ontology.

#### Response Example
```json
{
  "ontology": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "My Ontology",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Find File by ID (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Retrieves a single file by its unique ID. This function is used for fetching specific file details when the ID is known. It takes the file ID as a string and returns either a File object if found, or None if no file matches the provided ID.

```python
async def find_file(id: str) -> Optional[File]:
    # ... implementation details ...
    pass
```

```python
def find_file(id: str) -> Optional[File]:
    # ... implementation details ...
    pass
```

--------------------------------

### Find Jobs by IDs (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Finds multiple jobs based on a list of their IDs. This function returns a list of Job objects that match the provided IDs. If no jobs are found, an empty list is returned.

```python
async def find_jobs(ids: List[str]) -> List[Job]:
    # Implementation details...
    pass
```

```python
def find_jobs(ids: List[str]) -> List[Job]:
    # Implementation details...
    pass
```

--------------------------------

### Find Files

Source: https://docs.perseus.lettria.net/docs/client/services/file

Retrieves a list of files based on provided IDs or source hashes. This endpoint is useful for querying existing files.

```APIDOC
## GET /files/find

### Description
Finds and retrieves a list of files based on their IDs or source hashes.

### Method
GET

### Endpoint
/files/find

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ids** (List[str]) - Optional - A list of file IDs to search for.
- **source_hashes** (List[str]) - Optional - A list of SHA256 source hashes to search for.

### Request Example
```json
{
  "ids": ["file-12345", "file-67890"],
  "source_hashes": ["a1b2c3d4e5f67890...", "f0e9d8c7b6a54321..."]
}
```

### Response
#### Success Response (200)
- **files** (List[File]) - A list of File objects matching the criteria. Returns an empty list if no files are found.

#### Response Example
```json
{
  "files": [
    {
      "id": "file-12345",
      "name": "document.pdf",
      "status": "UPLOADED",
      "created_at": "2023-10-27T10:00:00Z"
    },
    {
      "id": "file-67890",
      "name": "image.jpg",
      "status": "UPLOADED",
      "created_at": "2023-10-26T15:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Build Knowledge Graph from Markdown

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Builds a knowledge graph from a generated Markdown document. This process involves uploading the document to the Perseus platform, where the Text-to-Graph engine extracts structured information. The extracted graph is saved as a local '.ttl' file and loaded into a Neo4j database. The input is the path to the Markdown file.

```python
python index.py assets/LOREAL_Rapport_Annuel_2024.md
```

--------------------------------

### Generate Context-Aware Reports

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Generates a detailed, context-aware report by querying a Neo4j database containing a knowledge graph. This script utilizes a RAG approach to answer natural language queries based on the retrieved information. The input is a natural language query string.

```python
python report.py "Money KPIs"
```

--------------------------------

### Find Ontologies API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Retrieves a list of ontologies based on provided IDs or source hashes.

```APIDOC
## GET /ontology/find

### Description
Finds and retrieves a list of ontologies based on their IDs or source hashes.

### Method
GET

### Endpoint
/ontology/find

### Parameters
#### Query Parameters
- **ids** (List[str]) - Optional - A list of ontology IDs to search for.
- **source_hashes** (List[str]) - Optional - A list of SHA256 source hashes to search for.

### Request Example
```json
{
  "ids": ["a1b2c3d4-e5f6-7890-1234-567890abcdef"],
  "source_hashes": ["a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef123456"]
}
```

### Response
#### Success Response (200)
- **ontologies** (List[Ontology]) - A list of Ontology objects matching the criteria.

#### Response Example
```json
{
  "ontologies": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "My Ontology",
      "status": "UPLOADED",
      "created_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Find Ontologies by IDs or Hashes (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Retrieves a list of ontologies based on provided IDs or source hashes. This function is useful for querying existing ontologies. It accepts optional lists of IDs and/or source hashes and returns a list of matching Ontology objects, or an empty list if none are found.

```python
async def find_ontologies(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[Ontology]:
    # Implementation details omitted for brevity
    pass
```

```python
def find_ontologies(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[Ontology]:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Save Cypher Queries to Neo4j (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/neo4j

Reads a file containing Cypher queries and executes them against a Neo4j database. This function takes the file path as input and returns nothing. It is designed to handle Cypher query files, such as those downloaded from job outputs.

```python
async def save_output_to_neo4j(file_path: str) -> None:
    # Implementation details for async execution
    pass
```

```python
def save_output_to_neo4j(file_path: str) -> None:
    # Implementation details for sync execution
    pass
```

--------------------------------

### Find File by ID

Source: https://docs.perseus.lettria.net/docs/client/services/file

Retrieves a single file by its unique ID. Returns the file object if found, otherwise returns null.

```APIDOC
## GET /files/{id}

### Description
Finds and retrieves a single file by its ID.

### Method
GET

### Endpoint
/files/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the file to find.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **file** (File | null) - A File object if a file with the given ID is found, otherwise null.

#### Response Example
```json
{
  "file": {
    "id": "file-12345",
    "name": "document.pdf",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```

#### Not Found Response (404)
```json
{
  "file": null
}
```
```

--------------------------------

### Upload File

Source: https://docs.perseus.lettria.net/docs/client/services/file

Uploads a file to the Perseus API. This function handles both creating a file record and uploading its content to a presigned URL. If a file with identical content already exists, it is returned without re-uploading.

```APIDOC
## POST /files/upload

### Description
Uploads a file to the Perseus API. This is a higher-level function that encapsulates `create_file` and the upload to a presigned URL. If a file with the same content already exists, it will be returned without uploading.

### Method
POST

### Endpoint
/files/upload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file_path** (str) - Required - The local path to the file to upload.

### Request Example
```json
{
  "file_path": "/path/to/your/local/file.txt"
}
```

### Response
#### Success Response (200)
- **file** (File) - A File object representing the uploaded or existing file, including its ID, name, status, and creation timestamp.

#### Response Example
```json
{
  "file": {
    "id": "file-12345",
    "name": "file.txt",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Wait for Ontology Upload Completion (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Polls the server to wait until an ontology's upload status changes to 'UPLOADED' or 'FAILED'. This is typically used after uploading content to a presigned URL. It requires the ontology ID and allows configuration of polling interval and timeout, returning the final Ontology object.

```python
async def wait_for_ontology_upload(ontology_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> Ontology:
    # Implementation details omitted for brevity
    pass
```

```python
def wait_for_ontology_upload(ontology_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> Ontology:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Wait for Ontology Upload API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Polls the status of an ontology upload until it is marked as UPLOADED or FAILED. This is typically used after initiating an upload via a presigned URL.

```APIDOC
## GET /ontology/wait_for_upload

### Description
Waits for an ontology's status to become `UPLOADED` or `FAILED`. This is useful after getting a presigned URL and uploading the ontology.

### Method
GET

### Endpoint
/ontology/wait_for_upload

### Parameters
#### Query Parameters
- **ontology_id** (str) - Required - The ID of the ontology to wait for.
- **polling_interval** (float) - Optional - The interval in seconds to poll for the ontology status. Defaults to `0.5`.
- **timeout** (int) - Optional - The maximum time in seconds to wait. Defaults to `3600`.

### Request Example
```json
{
  "ontology_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "polling_interval": 1.0,
  "timeout": 600
}
```

### Response
#### Success Response (200)
- **ontology** (Ontology) - The final `Ontology` object once the upload is complete.

#### Response Example
```json
{
  "ontology": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "My Ontology",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Stop and Remove Docker Services

Source: https://docs.perseus.lettria.net/docs/cookbooks/finance-compliance

Command to stop and remove all services defined in the docker-compose.yml file, effectively cleaning up the running environment.

```bash
docker compose down
```

--------------------------------

### Convert PDF to Markdown

Source: https://docs.perseus.lettria.net/docs/cookbooks/graph-rag-reporting

Converts a specified PDF document into a structured Markdown file using an LLM. This script preserves key information and formatting from the PDF, preparing it for knowledge graph extraction. The input is the path to the PDF file.

```python
python pdf_to_markdown.py assets/LOREAL_Rapport_Annuel_2024.pdf
```

--------------------------------

### Find Latest Job (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Retrieves the most recently completed job for a given file and optional ontology. This function returns the latest Job object with a SUCCEEDED status, or None if no such job exists.

```python
async def find_latest_job(file_id: str, ontology_id: Optional[str] = None) -> Optional[Job]:
    # Implementation details...
    pass
```

```python
def find_latest_job(file_id: str, ontology_id: Optional[str] = None) -> Optional[Job]:
    # Implementation details...
    pass
```

--------------------------------

### Find Single Job by ID (Async/Sync)

Source: https://docs.perseus.lettria.net/docs/client/services/job

Finds a single job using its unique ID. This function returns the corresponding Job object if found, otherwise it returns None. It's useful for retrieving the status of a specific job.

```python
async def find_job(id: str) -> Optional[Job]:
    # Implementation details...
    pass
```

```python
def find_job(id: str) -> Optional[Job]:
    # Implementation details...
    pass
```

--------------------------------

### Wait for File Upload Completion (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Polls the status of a file upload until it is marked as 'UPLOADED' or 'FAILED'. This is typically called after initiating an upload using a presigned URL. It requires the file ID and allows configuration of polling interval and timeout, returning the final File object.

```python
async def wait_for_file_upload(file_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> File:
    # ... implementation details ...
    pass
```

```python
def wait_for_file_upload(file_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> File:
    # ... implementation details ...
    pass
```

--------------------------------

### Wait for File Upload

Source: https://docs.perseus.lettria.net/docs/client/services/file

Polls the status of a file upload until it is completed (`UPLOADED`) or has failed (`FAILED`). This is useful after initiating an upload via a presigned URL.

```APIDOC
## POST /files/{file_id}/wait_for_upload

### Description
Waits for a file's status to become `UPLOADED` or `FAILED`. This is useful after getting a presigned URL and uploading the file.

### Method
POST

### Endpoint
/files/{file_id}/wait_for_upload

### Parameters
#### Path Parameters
- **file_id** (str) - Required - The ID of the file to wait for.

#### Query Parameters
- **polling_interval** (float) - Optional - The interval in seconds to poll for the file status. Defaults to `0.5`.
- **timeout** (int) - Optional - The maximum time in seconds to wait. Defaults to `3600`.

#### Request Body
None

### Response
#### Success Response (200)
- **file** (File) - The final `File` object once the upload is complete or has failed.

#### Response Example
```json
{
  "file": {
    "id": "file-12345",
    "name": "document.pdf",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```

#### Timeout Response (408)
- **message** (str) - Indicates that the operation timed out.

#### Timeout Response Example (408)
```json
{
  "message": "Timeout waiting for file upload to complete."
}
```
```

--------------------------------

### Find Single Ontology by ID (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Retrieves a single ontology by its unique ID. This function is used to fetch specific ontology details. It takes the ontology ID as a string and returns either the corresponding Ontology object or None if no ontology with that ID exists.

```python
async def find_ontology(id: str) -> Optional[Ontology]:
    # Implementation details omitted for brevity
    pass
```

```python
def find_ontology(id: str) -> Optional[Ontology]:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Find Ontology by ID API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Retrieves a single ontology by its unique ID.

```APIDOC
## GET /ontology/{id}

### Description
Finds and retrieves a single ontology by its ID.

### Method
GET

### Endpoint
/ontology/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the ontology to find.

### Response
#### Success Response (200)
- **ontology** (Ontology) - An Ontology object if found.

#### Success Response (404)
- No content returned if the ontology is not found.

#### Response Example
```json
{
  "ontology": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "My Ontology",
    "status": "UPLOADED",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Delete File by ID (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/file

Deletes a file from the system using its unique ID. This operation permanently removes the file record. It requires the file ID as a string and returns None upon successful deletion.

```python
async def delete_file(file_id: str) -> None:
    # ... implementation details ...
    pass
```

```python
def delete_file(file_id: str) -> None:
    # ... implementation details ...
    pass
```

--------------------------------

### Delete File

Source: https://docs.perseus.lettria.net/docs/client/services/file

Deletes a file from the system using its ID. This operation is irreversible.

```APIDOC
## DELETE /files/{file_id}

### Description
Deletes a file by its ID.

### Method
DELETE

### Endpoint
/files/{file_id}

### Parameters
#### Path Parameters
- **file_id** (str) - Required - The ID of the file to delete.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (204)
No content is returned on successful deletion.

#### Error Response (404)
- **message** (str) - Description of the error, e.g., "File not found."

#### Error Response Example (404)
```json
{
  "message": "File with ID file-99999 not found."
}
```
```

--------------------------------

### Delete Ontology by ID (Python)

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Deletes an ontology from the server using its unique ID. This operation permanently removes the ontology record. It requires the ontology ID as a string and returns None upon successful deletion.

```python
async def delete_ontology(ontology_id: str) -> None:
    # Implementation details omitted for brevity
    pass
```

```python
def delete_ontology(ontology_id: str) -> None:
    # Implementation details omitted for brevity
    pass
```

--------------------------------

### Delete Ontology API

Source: https://docs.perseus.lettria.net/docs/client/services/ontology

Deletes an ontology from the system using its unique ID.

```APIDOC
## DELETE /ontology/{ontology_id}

### Description
Deletes an ontology by its ID.

### Method
DELETE

### Endpoint
/ontology/{ontology_id}

### Parameters
#### Path Parameters
- **ontology_id** (str) - Required - The ID of the ontology to delete.

### Response
#### Success Response (204)
- No content is returned upon successful deletion.

#### Error Response (404)
- Ontology not found.
```
Tokens:
Raw