### Start OntoCast Server

Source: https://github.com/growgraph/ontocast/blob/main/demo/README.md

Starts the OntoCast server with specified ontology and working directories. Ensure OntoCast is installed and a triple store is running.

```bash
uv run serve --ontology-directory ../data/ontologies --working-directory ../data
```

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

### Example Neo4j .env.example

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

This is an example of the .env.example file for configuring the Neo4j Docker image, including version, ports, plugins, and authentication.

```bash
IMAGE_VERSION=neo4j:5.20
SPEC=test
CONTAINER_NAME="${SPEC}.sem.neo4j"
NEO4J_PORT=7476
NEO4J_BOLT_PORT=7689
STORE_FOLDER="$HOME/tmp/${CONTAINER_NAME}"
NEO4J_PLUGINS='["apoc", "graph-data-science", "n10s"]'
NEO4J_AUTH="neo4j/test!passfortesting"
```

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

### Triple Store Setup

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Information on supported triple stores and quick setup instructions using Docker.

```APIDOC
## Triple Store Setup

OntoCast supports multiple triple store backends with automatic fallback:

1. **Apache Fuseki** (Recommended) - Native RDF with SPARQL support
2. **Neo4j with n10s** - Graph database with RDF capabilities  
3. **Filesystem** (Fallback) - Local file-based storage

When multiple triple stores are configured, **Fuseki is preferred over Neo4j**.

### Quick Setup with Docker

**Fuseki:**
```bash
cd docker/fuseki
cp .env.example .env
# Edit .env with your values
docker compose --env-file .env fuseki up -d
```

**Neo4j:**
```bash
cd docker/neo4j
cp .env.example .env
```
```

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

### Start OntoCast Server

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Launch the OntoCast server using the command line, specifying the environment file and working/ontology directories. This command starts the service for processing documents.

```bash
ontocast \
    --env-path .env \
    --working-directory /path/to/working \
    --ontology-directory /path/to/ontologies
```

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

### Example Fuseki .env.example

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

This is an example of the .env.example file for configuring the Fuseki Docker image, including version, dataset name, ports, and credentials.

```bash
IMAGE_VERSION=secoresearch/fuseki:5.1.0
SPEC=test
CONTAINER_NAME="${SPEC}.fuseki"
STORE_FOLDER="$HOME/tmp/${CONTAINER_NAME}"
TS_PORT=3032
TS_PASSWORD="abc123-qwe"
TS_USERNAME="admin"
UID=1000
GID=1000
```

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

### Install Development Dependencies

Source: https://github.com/growgraph/ontocast/blob/main/docs/contributing.md

Installs all development dependencies, including those for documentation processing. Run this after cloning the repository.

```bash
uv sync --all-groups --extra doc-processing
```

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

### Install OntoCast

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Use 'uv add' or 'pip install' to add OntoCast to your project.

```sh
uv add ontocast 
# or
pip install ontocast
```

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

### Start OntoCast REST API Server

Source: https://context7.com/growgraph/ontocast/llms.txt

Configure environment variables in a .env file and start the OntoCast server using the CLI. Ensure LLM provider, API key, model, and port are set.

```bash
cat > .env << 'EOF' \
LLM_PROVIDER=openai \
LLM_API_KEY=your-api-key-here \
LLM_MODEL_NAME=gpt-4o-mini \
LLM_TEMPERATURE=0.1 \
PORT=8999 \
MAX_VISITS=3 \
ONTOCAST_WORKING_DIRECTORY=/path/to/working \
ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontologies \
FUSEKI_URI=http://localhost:3030 \
FUSEKI_AUTH=admin:password \
FUSEKI_DATASET=ontocast \
EOF

ontocast --env-file .env
```

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

### Start OntoCast Server

Source: https://context7.com/growgraph/ontocast/llms.txt

Starts the OntoCast server with specified environment file and input path for document processing. Includes an option to set the number of head chunks.

```bash
# Start server with file processing
ontocast --env-file .env --input-path ./documents --head-chunks 5
```

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

### Install OntoCast with Document Processing

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Install OntoCast with optional document processing capabilities, including PDF and OCR support. Use `uv` or `pip` for installation.

```sh
uv add ontocast[doc-processing] 
# or
pip install ontocast
```

```sh
uv add "ontocast[doc-processing]"
# or
pip install "ontocast[doc-processing]"
```

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

### Run OntoCast Server

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Start the OntoCast server using the command line, specifying the environment file path.

```bash
# Backend automatically detected from .env configuration
ontocast --env-path .env
```

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

### Install OntoCast using pip

Source: https://github.com/growgraph/ontocast/blob/main/docs/getting_started/installation.md

Use this command to install OntoCast globally or within a virtual environment using pip.

```bash
pip install ontocast
```

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

### Ontology User Instruction Example

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Use this instruction to guide ontology extraction, focusing on specific entity types and their relationships.

```plaintext
Focus on extracting geographical locations, organizations, and their relationships. Pay special attention to company mergers, acquisitions, and partnerships.
```

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

### Start Neo4j Docker Compose

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Starts the Neo4j database service using Docker Compose with a specified environment file.

```bash
docker compose --env-file .env neo4j up -d
```

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

### OntoCast API - Advanced Examples

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Examples demonstrating advanced usage of the OntoCast API for multi-domain extraction, temporal focus, and geographic focus.

```APIDOC
## Advanced Examples

### 1. Multi-Domain Extraction

```json
{
  "text": "Your document text...",
  "ontology_user_instruction": "Extract both business and technical concepts. Focus on companies, products, technologies, and their relationships.",
  "facts_user_instruction": "Extract business metrics, technical specifications, and performance data. Include all numerical values with proper context."
}
```

### 2. Temporal Focus

```json
{
  "text": "Your document text...",
  "ontology_user_instruction": "Focus on extracting entities and relationships that are time-sensitive or have temporal aspects.",
  "facts_user_instruction": "Extract all dates, time periods, and temporal relationships. Pay special attention to historical events and chronological data."
}
```

### 3. Geographic Focus

```json
{
  "text": "Your document text...",
  "ontology_user_instruction": "Focus on extracting geographical entities, locations, and spatial relationships.",
  "facts_user_instruction": "Extract all geographical coordinates, addresses, and location-specific data. Include all spatial and geographical information."
}
```
```

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

### Prepare Fuseki Environment File

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

Copy the example environment file and edit it with your specific values for Fuseki Docker deployment.

```bash
cd docker/fuseki
cp .env.example .env
# Edit with your values
```

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

### Configure OntoCast with Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Set up OntoCast by creating a `.env` file to configure LLM providers, server settings, paths, and optional triple store integration. This example shows common configurations.

```bash
# LLM Configuration
LLM_PROVIDER=openai
LLM_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o-mini
LLM_TEMPERATURE=0.1

# Server Configuration
PORT=8999
MAX_VISITS=3
RECURSION_LIMIT=1000
ESTIMATED_CHUNKS=30
ONTOLOGY_MAX_TRIPLES=10000

# Path Configuration
ONTOCAST_WORKING_DIRECTORY=/path/to/working
ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontologies
ONTOCAST_CACHE_DIR=/path/to/cache

# Optional: Triple Store Configuration
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:password
FUSEKI_DATASET=ontocast

# Optional: Skip ontology critique
SKIP_ONTOLOGY_DEVELOPMENT=false
# Optional: Maximum triples allowed in ontology graph (set empty for unlimited)
ONTOLOGY_MAX_TRIPLES=10000

# Optional: Web search grounding (search-later mode)
# Node execution starts without search; search runs only when node output requests it.
WEB_SEARCH_ENABLED=false
WEB_SEARCH_PROVIDER=duckduckgo
WEB_SEARCH_TOP_K=3
WEB_SEARCH_TIMEOUT_SECONDS=8.0
WEB_SEARCH_MAX_SNIPPET_CHARS=400
WEB_SEARCH_MAX_TOTAL_CHARS=1800
WEB_SEARCH_ONTOLOGY_RENDER_ENABLED=true
WEB_SEARCH_ONTOLOGY_CRITIC_ENABLED=true
WEB_SEARCH_FACTS_RENDER_ENABLED=false
WEB_SEARCH_FACTS_CRITIC_ENABLED=false
WEB_SEARCH_PLANNER_ENABLED=true
WEB_SEARCH_PLANNER_MAX_QUERIES=3
WEB_SEARCH_PLANNER_MIN_QUERY_CHARS=12
WEB_SEARCH_PLANNER_MIN_CONFIDENCE=0.35
WEB_SEARCH_REUSE_EVIDENCE_ACROSS_ATTEMPT=true
WEB_SEARCH_MIN_SNIPPET_CHARS=40
WEB_SEARCH_ALLOWED_DOMAINS=
WEB_SEARCH_BLOCKED_DOMAINS=
```

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

### Install Pre-commit Hooks

Source: https://github.com/growgraph/ontocast/blob/main/docs/contributing.md

Installs pre-commit hooks to ensure code quality and style consistency before committing changes.

```bash
pre-commit install
```

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

### Prepare Neo4j Environment File

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

Copy the example environment file and edit it with your specific values for Neo4j Docker deployment, including plugins.

```bash
cd docker/neo4j
cp .env.example .env
# Edit with your values
```

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

### Start OntoCast Server with Caching

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/llm_caching.md

This command starts the OntoCast server, automatically enabling caching for all LLM operations. Ensure environment variables and working directory are correctly set.

```bash
ontocast --env-path .env --working-directory /data/working
```

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

### Example Debug Output for User Instructions

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Shows example debug log messages indicating how user instructions for ontology and facts extraction are set within the OntoCast system.

```text
DEBUG - Set ontology user instruction: Focus on extracting geographical locations and organizations
DEBUG - Set facts user instruction: Extract financial data and numerical values
```

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

### Manual Ontocast Configuration

Source: https://context7.com/growgraph/ontocast/llms.txt

Configure LLM, path, Fuseki, chunking, and web search settings. This setup is used to initialize the ToolBox.

```python
from ontocast.config import (
    ToolConfig, ServerConfig, PathConfig,
    FusekiConfig, ChunkConfig, WebSearchConfig
)

tool_config = ToolConfig(
    llm_config=LLMConfig(
        provider=LLMProvider.OPENAI,
        model_name=OpenAIModel.GPT4_O_MINI,
        temperature=0.1,
        api_key="your-api-key"
    ),
    path_config=PathConfig(
        working_directory="/path/to/working",
        ontology_directory="/path/to/ontologies"
    ),
    fuseki=FusekiConfig(
        uri="http://localhost:3030",
        auth="admin:password",
        dataset="ontocast"
    ),
    chunk_config=ChunkConfig(
        min_size=3000,
        max_size=12000,
        breakpoint_threshold_type="percentile",
        breakpoint_threshold_amount=95.0
    ),
    web_search=WebSearchConfig(
        enabled=True,
        provider="duckduckgo",
        top_k=3
    )
)

config = Config(
    tool_config=tool_config,
    server=ServerConfig(
        port=8999,
        max_visits_per_node=3,
        render_mode="ontology_and_facts",
        ontology_max_triples=50000,
        parallel_workers=4
    )
)
```

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

### Run Ontocast Server with Custom Configuration

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Starts the Ontocast server with custom settings for environment path, working directory, ontology directory, and skips ontology critique.

```bash
ontocast \
    --env-path .env \
    --working-directory /data/working \
    --ontology-directory /data/ontologies \
    --skip-ontology-critique \
    --head-chunks 10
```

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

### Copy and Edit Environment File

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Copy the example .env file to customize your environment variables for OntoCast configuration.

```bash
cp .env.example .env
# Edit with your values
```

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

### OntoCast API - Examples by Domain

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Examples of ontology and facts instructions tailored for specific domains like Healthcare, Finance, Legal, Scientific, and Technical.

```APIDOC
## Examples by Domain

### Healthcare
- **Ontology**: "Focus on medical conditions, treatments, and healthcare relationships"
- **Facts**: "Extract patient data, medical codes, and clinical measurements"

### Finance
- **Ontology**: "Focus on financial entities, business relationships, and economic concepts"
- **Facts**: "Extract monetary amounts, financial ratios, and economic indicators"

### Legal
- **Ontology**: "Focus on legal entities, court cases, and regulatory frameworks"
- **Facts**: "Extract case numbers, legal citations, and compliance information"

### Scientific
- **Ontology**: "Focus on scientific concepts, methodologies, and research relationships"
- **Facts**: "Extract experimental data, measurements, and research findings"

### Technical
- **Ontology**: "Focus on technical concepts, systems, and technological relationships"
- **Facts**: "Extract technical specifications, performance metrics, and system data"
```

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

### Set up Neo4j Triple Store with Docker

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Use Docker Compose to set up and run a Neo4j triple store. Remember to copy and edit the .env.example file before starting the service.

```bash
cd docker/neo4j
cp .env.example .env
```

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

### Facts User Instruction Example

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Use this instruction to guide facts extraction, focusing on specific data points and their attributes.

```plaintext
Extract financial data, dates, and numerical values. Focus on revenue, profit, and growth metrics. Include all monetary amounts with proper currency information.
```

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

### Run OntoCast Server

Source: https://github.com/growgraph/ontocast/blob/main/docs/getting_started/quickstart.md

Start the OntoCast server using the CLI. The backend is automatically detected from the .env configuration. You can specify an input path or limit the number of chunks for testing.

```bash
# Backend automatically detected from .env configuration
ontocast --env-path .env
```

```bash
# Process specific file
ontocast --env-path .env --input-path ./document.pdf
```

```bash
# Process with chunk limit (for testing)
ontocast --env-path .env --head-chunks 5
```

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

### Start Neo4j Docker Container

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

Use Docker Compose to start the Neo4j service in detached mode, loading specified plugins.

```bash
cd docker/neo4j
docker compose --env-file .env up neo4j -d
```

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

### Ontocast CLI Usage

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Examples of how to use the Ontocast command-line interface for processing files.

```APIDOC
## Ontocast CLI Usage

### Process specific file
```bash
ontocast --env-path .env --input-path ./document.pdf
```

### Process with chunk limit (for testing)
```bash
ontocast --env-path .env --head-chunks 5
```

**Configuration Notes:**
- Backend selection is automatic based on available configuration.
- No explicit backend flags are needed; provide credentials/paths in `.env`.
- All paths and directories are configured via the `.env` file.
```

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

### OntoCast .env Configuration Example

Source: https://github.com/growgraph/ontocast/blob/main/docs/getting_started/quickstart.md

Configure OntoCast settings by creating a .env file. This includes domain, LLM, server, backend, and path configurations. Paths and directories are typically configured here.

```dotenv
# Domain configuration (used for URI generation) 
CURRENT_DOMAIN=https://example.com
PORT=8999
LLM_TEMPERATURE=0.0

# LLM Configuration
LLM_PROVIDER=openai
LLM_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o-mini

# Server Configuration
MAX_VISITS=3
BASE_RECURSION_LIMIT=1000
ESTIMATED_CHUNKS=30
RENDER_MODE=ontology_and_facts
ONTOLOGY_MAX_TRIPLES=50000
PARALLEL_WORKERS=4
PARALLEL_FACTS_RETRIES=3
PARALLEL_ONTOLOGY_RETRIES=3
ENABLE_ONTOLOGY_CONSOLIDATION=false

# Backend Configuration (auto-detected)
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:password
ONTOCAST_WORKING_DIRECTORY=/path/to/working

# Path Configuration (required for filesystem backends)
ONTOCAST_WORKING_DIRECTORY=/path/to/working/directory
ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontology/files
ONTOCAST_CACHE_DIR=/path/to/cache/directory

# Triple Store Configuration (optional)
# For Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_AUTH=username:password

# For Fuseki
FUSEKI_URI=http://localhost:3030
FUSEKI_AUTH=username:password
FUSEKI_DATASET=dataset_name
FUSEKI_ONTOLOGIES_DATASET=ontologies

# Optional aggregation controls
AGG_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
AGG_SIMILARITY_THRESHOLD=0.80

# Optional web-search grounding
WEB_SEARCH_ENABLED=false
WEB_SEARCH_PROVIDER=duckduckgo
WEB_SEARCH_TOP_K=3
```

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

### Start Fuseki Docker Container

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

Use Docker Compose to start the Fuseki service in detached mode, using the environment variables defined in the .env file.

```bash
cd docker/fuseki
docker compose --env-file .env up fuseki -d
```

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

### Start and Stop Neo4j Docker Container

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/triple_stores.md

Commands to start and stop a Neo4j Docker container using docker compose. Ensure you are in the correct directory and use the appropriate .env file.

```bash
# Start
cd docker/neo4j
docker compose --env-file .env neo4j up -d

# Stop
docker compose stop neo4j
```

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

### Start and Stop Fuseki Docker Container

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/triple_stores.md

Commands to start and stop an Apache Fuseki Docker container using docker compose. Ensure you are in the correct directory and use the appropriate .env file.

```bash
# Start
cd docker/fuseki
docker compose --env-file .env fuseki up -d

# Stop
# (use the container name from your .env, e.g. test.fuseki)
docker compose stop test.fuseki
```

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

### Add OntoCast using uv

Source: https://github.com/growgraph/ontocast/blob/main/docs/getting_started/installation.md

Use this command to add OntoCast to your project's dependencies with the uv package installer.

```bash
uv add ontocast
```

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

### Get OntoCast Service Information

Source: https://context7.com/growgraph/ontocast/llms.txt

Retrieve service capabilities, supported input/output types, and version information by sending a GET request to the /info endpoint. This helps understand the API's functionalities.

```bash
curl -X GET http://localhost:8999/info
```

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

### Service Info Endpoint

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Use the GET /info endpoint to retrieve service information.

```bash
GET /info
```

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

### OntoCast REST API Server

Source: https://context7.com/growgraph/ontocast/llms.txt

This section details the REST API endpoints for interacting with the OntoCast server, including starting the server, health checks, service information, document processing, and flushing the triple store.

```APIDOC
## Starting the OntoCast Server

To start the OntoCast server, you need to create a `.env` configuration file with your API keys and desired settings, and then run the `ontocast` command.

### Method

N/A (Shell command)

### Command

```bash
# Create .env configuration file
cat > .env << 'EOF'
LLM_PROVIDER=openai
LLM_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o-mini
LLM_TEMPERATURE=0.1
PORT=8999
MAX_VISITS=3
ONTOCAST_WORKING_DIRECTORY=/path/to/working
ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontologies
FUSEKI_URI=http://localhost:3030
FUSEKI_AUTH=admin:password
FUSEKI_DATASET=ontocast
EOF

# Start the server
ontocast --env-file .env
```

### Parameters

No direct parameters for the `ontocast` command itself, but the `.env` file supports the following:

#### Environment Variables (`.env` file)

- **LLM_PROVIDER** (string) - Required - The LLM provider to use (e.g., `openai`).
- **LLM_API_KEY** (string) - Required - Your API key for the LLM provider.
- **LLM_MODEL_NAME** (string) - Required - The name of the LLM model to use (e.g., `gpt-4o-mini`).
- **LLM_TEMPERATURE** (float) - Optional - The temperature setting for the LLM (default: 0.1).
- **PORT** (integer) - Optional - The port the server will listen on (default: 8999).
- **MAX_VISITS** (integer) - Optional - Maximum number of visits for certain agent processes.
- **ONTOCAST_WORKING_DIRECTORY** (string) - Required - Path to the working directory.
- **ONTOCAST_ONTOLOGY_DIRECTORY** (string) - Required - Path to the ontology directory.
- **FUSEKI_URI** (string) - Optional - URI for Apache Fuseki triple store.
- **FUSEKI_AUTH** (string) - Optional - Authentication credentials for Fuseki (user:password).
- **FUSEKI_DATASET** (string) - Optional - Default dataset name for Fuseki.
```

```APIDOC
## GET /health

### Description

Checks the health status of the OntoCast server and retrieves information about the configured LLM provider.

### Method

GET

### Endpoint

`/health`

### Parameters

None

### Request Example

```bash
curl -X GET http://localhost:8999/health
```

### Response

#### Success Response (200)

- **status** (string) - The health status of the server (e.g., `healthy`).
- **version** (string) - The current version of the OntoCast server.
- **llm_provider** (string) - The LLM provider currently in use.

#### Response Example

```json
{
  "status": "healthy",
  "version": "0.1.1",
  "llm_provider": "openai"
}
```
```

```APIDOC
## GET /info

### Description

Retrieves information about the OntoCast service, including its name, version, description, capabilities, and supported input/output formats.

### Method

GET

### Endpoint

`/info`

### Parameters

None

### Request Example

```bash
curl -X GET http://localhost:8999/info
```

### Response

#### Success Response (200)

- **name** (string) - The name of the service.
- **version** (string) - The version of the service.
- **description** (string) - A brief description of the service.
- **capabilities** (array of strings) - A list of capabilities supported by the service (e.g., `["text-to-triples", "ontology-extraction"]`).
- **input_types** (array of strings) - A list of input document formats supported (e.g., `["text", "json", "pdf", "markdown"]`).
- **output_types** (array of strings) - A list of output formats supported (e.g., `["turtle", "json"]`).

#### Response Example

```json
{
  "name": "ontocast",
  "version": "0.1.1",
  "description": "Agentic ontology assisted framework for semantic triple extraction",
  "capabilities": ["text-to-triples", "ontology-extraction"],
  "input_types": ["text", "json", "pdf", "markdown"],
  "output_types": ["turtle", "json"]
}
```
```

```APIDOC
## POST /process

### Description

Processes documents to extract semantic triples and build knowledge graphs. Supports various input formats and allows for user-defined instructions to guide the extraction process.

### Method

POST

### Endpoint

`/process`

### Parameters

#### Query Parameters

- **ontology_user_instruction** (string) - Optional - User-specific instructions for ontology extraction.
- **facts_user_instruction** (string) - Optional - User-specific instructions for fact extraction.
- **dataset** (string) - Optional - The name of the dataset to use or create in the triple store.
- **render_mode** (string) - Optional - Specifies the output format (e.g., `ontology_and_facts`).

#### Request Body

- **file** (file) - Required - The document file to process (e.g., PDF, JSON, Markdown, text).
- **text** (string) - Required (if `file` is not used) - The text content to process.

### Request Example

**Processing a PDF document:**
```bash
curl -X POST http://localhost:8999/process \
  -F "file=@document.pdf"
```

**Processing a JSON document with user instructions:**
```bash
curl -X POST "http://localhost:8999/process?ontology_user_instruction=Focus%20on%20extracting%20places&facts_user_instruction=Extract%20dates%20and%20events" \
  -F "file=@data.json"
```

**Processing text with specific dataset and render mode:**
```bash
curl -X POST "http://localhost:8999/process?dataset=my_dataset&render_mode=ontology_and_facts" \
  -H "Content-Type: application/json" \
  -d '{"text": "Apple Inc. was founded by Steve Jobs in 1976 in Cupertino, California."}'
```

### Response

#### Success Response (200)

- **status** (string) - Indicates the processing status (e.g., `success`).
- **data** (object) - Contains the extracted ontology and facts in RDF/Turtle format.
  - **facts** (string) - RDF/Turtle representation of extracted facts.
  - **ontology** (string) - RDF/Turtle representation of the extracted ontology.
- **metadata** (object) - Contains metadata about the processing.
  - **status** (string) - Processing status within metadata.
  - **chunks_processed** (integer) - Number of chunks processed.
  - **chunks_remaining** (integer) - Number of chunks remaining.
  - **budget** (object) - Information about LLM usage and generated triples.
    - **chars_sent** (integer) - Total characters sent to the LLM.
    - **chars_received** (integer) - Total characters received from the LLM.
    - **calls_count** (integer) - Number of LLM calls made.
    - **ontology_triples_generated** (integer) - Number of ontology triples generated.
    - **facts_triples_generated** (integer) - Number of fact triples generated.

#### Response Example

```json
{
  "status": "success",
  "data": {
    "facts": "@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> ...",
    "ontology": "@prefix owl: <http://www.w3.org/2002/07/owl#> ..."
  },
  "metadata": {
    "status": "success",
    "chunks_processed": 5,
    "chunks_remaining": 0,
    "budget": {
      "chars_sent": 15000,
      "chars_received": 8000,
      "calls_count": 12,
      "ontology_triples_generated": 45,
      "facts_triples_generated": 120
    }
  }
}
```
```

```APIDOC
## POST /flush

### Description

Clears data from the configured triple store. This operation can flush all datasets or a specific dataset.

### Method

POST

### Endpoint

`/flush`

### Parameters

#### Query Parameters

- **dataset** (string) - Optional - The name of the specific Fuseki dataset to flush. If omitted, all datasets (Fuseki) or the entire database (Neo4j) will be flushed.

### Request Example

**Flush all datasets (Fuseki) or entire database (Neo4j):**
```bash
curl -X POST http://localhost:8999/flush
```

**Flush a specific Fuseki dataset:**
```bash
curl -X POST "http://localhost:8999/flush?dataset=my_dataset"
```

### Response

#### Success Response (200)

- **status** (string) - Indicates the flush operation status (e.g., `success`).
- **message** (string) - A confirmation message detailing the operation performed.

#### Response Example

```json
{
  "status": "success",
  "message": "Fuseki dataset 'my_dataset' flushed successfully"
}
```
```

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

### Set up Fuseki Triple Store with Docker

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Use Docker Compose to set up and run an Apache Fuseki triple store. Ensure to configure the .env file with your specific values.

```bash
cd docker/fuseki
cp .env.example .env
# Edit .env with your values
docker compose --env-file .env fuseki up -d
```

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

### Initialize Ontocast Tools

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Loads configuration and initializes the ToolBox for processing documents in Python.

```python
from ontocast.config import Config
from ontocast.toolbox import ToolBox

# Load configuration
config = Config()

# Initialize tools
tools = ToolBox(config)

# Process documents
# ... (use tools for processing)
```

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

### Initialize ToolBox and Access Tools

Source: https://context7.com/growgraph/ontocast/llms.txt

Initialize the ToolBox with a configuration object and access various tools like LLM, converter, and SPARQL client. The triple store manager is auto-selected based on the configuration.

```python
import asyncio
from ontocast.config import Config
from ontocast.toolbox import ToolBox

# Initialize ToolBox with configuration
config = Config()
tools = ToolBox(config)
asyncio.run(tools.initialize())

# Access individual tools
llm_tool = tools.llm
converter = tools.converter
chunker = tools.chunker
aggregator = tools.aggregator
sparql_tool = tools.sparql_tool
version_manager = tools.version_manager

# Access triple store manager (auto-selected based on config)
triple_store = tools.triple_store_manager  # Fuseki, Neo4j, or Filesystem
filesystem_manager = tools.filesystem_manager

# Update dataset dynamically (for Fuseki)
await tools.update_dataset("new_dataset")

# Get LLM tool with budget tracking
from ontocast.onto.state import BudgetTracker
budget_tracker = BudgetTracker()
llm_with_budget = await tools.get_llm_tool(budget_tracker)
```

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

### Loading and Accessing Configuration in Python

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/configuration.md

Demonstrates how to import the `Config` class and access configuration values, including nested settings like LLM and path configurations.

```python
from ontocast.config import Config

config = Config()
tool_config = config.get_tool_config()

print(config.server.port)
print(config.server.max_visits_per_node)
print(tool_config.llm_config.provider)
print(tool_config.path_config.cache_dir)
```

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

### Health Check Endpoint

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Use the GET /health endpoint for a service health check.

```bash
GET /health
```

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

### Best Practice: Domain-Specific Language

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

Utilize domain-specific terminology in your instructions to guide the AI effectively.

```plaintext
Extract medical diagnoses, symptoms, treatments, and patient information. Focus on ICD-10 codes and medical terminology.
```

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

### JSON Document Structure Example

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

JSON documents processed by OntoCast must contain a 'text' field.

```json
{
  "text": "abc"
}
```

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

### Paths and Domain Configuration Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/configuration.md

Specify the current domain and directories for OntoCast working files, ontology files, and cache.

```bash
CURRENT_DOMAIN=https://example.com
ONTOCAST_WORKING_DIRECTORY=/path/to/working/directory
ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontology/files
ONTOCAST_CACHE_DIR=/path/to/cache/directory
```

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

### Run OntoCast CLI with Parameters

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Execute OntoCast from the command line, using parameters to control its behavior, such as skipping critique steps or limiting processed chunks.

```bash
# Skip ontology critique step
ontocast --skip-ontology-critique
```

```bash
# Process only first N chunks (for testing)
ontocast --head-chunks 5
```

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

### Configuration Structure Overview

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/configuration.md

This diagram illustrates the hierarchical structure of the OntoCast configuration, showing nested configuration objects for tools and server settings.

```text
Config
├── tool_config: ToolConfig
│   ├── llm_config: LLMConfig
│   ├── chunk_config: ChunkConfig
│   ├── path_config: PathConfig
│   ├── neo4j: Neo4jConfig
│   ├── fuseki: FusekiConfig
│   ├── domain: DomainConfig
│   ├── web_search: WebSearchConfig
│   └── aggregation: AggregationConfig
└── server: ServerConfig
```

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

### Configure Triple Store with Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Set environment variables to configure the connection details for Fuseki or Neo4j triple stores.

```bash
# Fuseki (Preferred)
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:password
FUSEKI_DATASET=dataset_name
```

```bash
# Neo4j (Alternative)
NEO4J_URI=bolt://localhost:7689
NEO4J_AUTH=neo4j:password
```

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

### Test Ontocast Configuration (Python)

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/triple_stores.md

Test your Ontocast configuration after upgrading. This script loads the configuration and prints details about the LLM provider and working directory.

```python
# Test your configuration
from ontocast.config import Config

config = Config()
print("Configuration loaded successfully!")
print(f"LLM Provider: {config.tool_config.llm_config.provider}")
print(f"Working Directory: {config.tool_config.path_config.working_directory}")
```

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

### Get LLM Cache Statistics

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/llm_caching.md

Retrieve statistics about the LLM cache, such as the number of files and total size. This helps in monitoring cache usage.

```python
from ontocast.tool.llm import LLMTool

# Get cache statistics
llm_tool = LLMTool.create(config=llm_config)
stats = llm_tool.cache.get_cache_stats()
print(f"Cache stats: {stats}")
```

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

### Multipart Form Data Request with User Instructions

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/user_instructions.md

When using multipart form data, provide user instructions as separate form fields.

```bash
curl -X POST http://localhost:8999/process \
  -F "file=@document.pdf" \
  -F "ontology_user_instruction=Focus on extracting geographical locations and organizations" \
  -F "facts_user_instruction=Extract financial data and numerical values"
```

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

### Get Converter Cache Statistics and Clear

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/llm_caching.md

Access statistics for the Converter cache and clear it if necessary. This helps manage disk space and ensure fresh conversions.

```python
from ontocast.tool.converter import ConverterTool
from ontocast.tool.chunk.chunker import ChunkerTool

# Get cache statistics
converter = ConverterTool()
stats = converter.cache.get_cache_stats()
print(f"Converter cache: {stats['total_files']} files, {stats['total_size_bytes']} bytes")

# Clear cache if needed
converter.cache.clear()
```

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

### Build OntoCast Docker Image

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Build the OntoCast Docker image using docker buildx. Output is piped to build.log.

```bash
docker buildx build -t growgraph/ontocast:0.1.4 . 2>&1 | tee build.log
```

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

### Initialize LLM Tool with Shared Cache

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/llm_caching.md

Demonstrates creating a shared Cacher instance and initializing an LLMTool with it. The first call to the tool will hit the API and cache the response, while subsequent identical calls will return the cached result instantly.

```python
from ontocast.tool.llm import LLMTool
from ontocast.config import LLMConfig
from ontocast.tool.cache import Cacher

# Create shared cache instance
shared_cache = Cacher()

# Create LLM tool with shared cache
llm_config = LLMConfig(
    provider="openai",
    model_name="gpt-4o-mini",
    api_key="your-api-key"
)

llm_tool = LLMTool.create(config=llm_config, cache=shared_cache)

# First call - hits API and caches response
response1 = llm_tool("What is the capital of France?")

# Second call - returns cached response instantly
response2 = llm_tool("What is the capital of France?")
```

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

### Triple Stores Configuration Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/configuration.md

Configure connection details for Fuseki and Neo4j triple stores, including URIs, authentication, and dataset names.

```bash
# Fuseki
FUSEKI_URI=http://localhost:3030/test
FUSEKI_AUTH=admin/admin
FUSEKI_DATASET=dataset_name
FUSEKI_ONTOLOGIES_DATASET=ontologies

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_AUTH=neo4j/test
NEO4J_PORT=7476
NEO4J_BOLT_PORT=7689
```

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

### Configure Triple Store Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/docker/README.md

Set these environment variables in your .env file to configure the connection to your chosen triple store. Fuseki is preferred if FUSEKI_URI and FUSEKI_AUTH are set.

```bash
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin/abc123-qwe
```

```bash
NEO4J_URI=bolt://localhost:7689
NEO4J_AUTH=neo4j/test!passfortesting
```

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

### Configuration System

Source: https://github.com/growgraph/ontocast/blob/main/README.md

Details on configuration options available through environment variables and CLI parameters.

```APIDOC
## Configuration System

OntoCast uses a hierarchical configuration system built on Pydantic BaseSettings:

### Environment Variables

| Variable |
| Description |
| Default |
| Required |
| `LLM_API_KEY` | API key for LLM provider | - | Yes |
| `LLM_PROVIDER` | LLM provider (openai, ollama) | openai | No |
| `LLM_MODEL_NAME` | Model name | gpt-4o-mini | No |
| `LLM_TEMPERATURE` | Temperature setting | 0.1 | No |
| `ONTOCAST_WORKING_DIRECTORY` | Working directory path | - | Yes |
| `ONTOCAST_ONTOLOGY_DIRECTORY` | Ontology files directory | - | No |
| `PORT` | Server port | 8999 | No |
| `MAX_VISITS` | Maximum visits per node | 3 | No |
| `SKIP_ONTOLOGY_DEVELOPMENT` | Skip ontology critique | false | No |
| `ONTOLOGY_MAX_TRIPLES` | Maximum triples allowed in ontology graph | 10000 | No |
| `SKIP_FACTS_RENDERING` | Skip facts rendering and go straight to aggregation | false | No |
| `ONTOCAST_CACHE_DIR` | Custom cache directory for LLM responses | Platform default | No |
| `WEB_SEARCH_ENABLED` | Enable optional web grounding (search runs only on node request) | false | No |
| `WEB_SEARCH_PROVIDER` | Web search provider | duckduckgo | No |
| `WEB_SEARCH_TOP_K` | Number of search results used per call | 3 | No |
| `WEB_SEARCH_ONTOLOGY_RENDER_ENABLED` | Allow search-eligible ontology render retries | true | No |
| `WEB_SEARCH_ONTOLOGY_CRITIC_ENABLED` | Allow search-eligible ontology critic retries | true | No |
| `WEB_SEARCH_FACTS_RENDER_ENABLED` | Allow search-eligible facts render retries | false | No |
| `WEB_SEARCH_FACTS_CRITIC_ENABLED` | Allow search-eligible facts critic retries | false | No |
| `WEB_SEARCH_PLANNER_ENABLED` | Use LLM planner for query decisioning | true | No |
| `WEB_SEARCH_PLANNER_MAX_QUERIES` | Maximum planned focused queries per node | 3 | No |
| `WEB_SEARCH_PLANNER_MIN_QUERY_CHARS` | Guardrail minimum query length | 12 | No |
| `WEB_SEARCH_PLANNER_MIN_CONFIDENCE` | Guardrail minimum planner confidence | 0.35 | No |
| `WEB_SEARCH_ALLOWED_DOMAINS` | Optional comma-separated allowlist domains | empty | No |
| `WEB_SEARCH_BLOCKED_DOMAINS` | Optional comma-separated blocklist domains | empty | No |

### Triple Store Configuration

```bash
# Fuseki (Preferred)
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:password
FUSEKI_DATASET=dataset_name

# Neo4j (Alternative)
NEO4J_URI=bolt://localhost:7689
NEO4J_AUTH=neo4j:password
```

### CLI Parameters

```bash
# Skip ontology critique step
ontocast --skip-ontology-critique

# Process only first N chunks (for testing)
ontocast --head-chunks 5
```
```

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

### Check OntoCast Server Health

Source: https://context7.com/growgraph/ontocast/llms.txt

Use curl to send a GET request to the /health endpoint to check the server's status and LLM provider information. The expected response includes status, version, and LLM provider.

```bash
curl -X GET http://localhost:8999/health
```

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

### Configure OntoCast for Fuseki

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/triple_stores.md

Set the FUSEKI_URI, FUSEKI_AUTH, and FUSEKI_DATASET environment variables in your .env file to connect OntoCast to a running Apache Fuseki instance.

```bash
# In your .env file
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:abc123-qwe
FUSEKI_DATASET=dataset_name
```

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

### Update ToolBox Initialization

Source: https://github.com/growgraph/ontocast/blob/main/CHANGELOG.md

ToolBox initialization has changed. It now accepts a configuration object directly instead of individual parameters.

```python
# Old way (no longer supported)
tools = ToolBox(
    llm_provider="openai",
    model_name="gpt-4",
    # ... many individual parameters
)

# New way
tools = ToolBox(config)
```

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

### Process JSON Document with User Instructions

Source: https://context7.com/growgraph/ontocast/llms.txt

Process a JSON document using the /process endpoint, providing user instructions for ontology and fact extraction via URL query parameters. The file is sent as form data.

```bash
curl -X POST "http://localhost:8999/process?ontology_user_instruction=Focus%20on%20extracting%20places&facts_user_instruction=Extract%20dates%20and%20events" \
  -F "file=@data.json"
```

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

### Server Configuration Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/configuration.md

Configure server-related settings such as port, recursion limits, rendering modes, and parallel processing parameters.

```bash
PORT=8999
BASE_RECURSION_LIMIT=1000
ESTIMATED_CHUNKS=30
MAX_VISITS=3                             # alias for max_visits_per_node
RENDER_MODE=ontology_and_facts           # ontology | facts | ontology_and_facts
ONTOLOGY_MAX_TRIPLES=50000               # empty/unset for unlimited
PARALLEL_WORKERS=4
PARALLEL_FACTS_RETRIES=3
PARALLEL_ONTOLOGY_RETRIES=3
ENABLE_ONTOLOGY_CONSOLIDATION=false
```

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

### Docker Build

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Command to build the Ontocast Docker image.

```APIDOC
## Docker Build

To build the OntoCast Docker image:

```bash
docker buildx build -t growgraph/ontocast:0.1.4 . 2>&1 | tee build.log
```
```

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

### Process with Chunk Limit using OntoCast CLI

Source: https://github.com/growgraph/ontocast/blob/main/docs/index.md

Process documents with a head chunk limit for testing purposes using the OntoCast CLI. Configuration is managed via the .env file.

```bash
ontocast --env-path .env --head-chunks 5
```

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

### Configure Triple Store with Environment Variables

Source: https://github.com/growgraph/ontocast/blob/main/docs/user_guide/triple_stores.md

Set environment variables in your .env file to configure the connection details for Fuseki or Neo4j triple stores. These variables define the URIs, authentication credentials, and dataset names.

```bash
# Fuseki Configuration (Preferred)
FUSEKI_URI=http://localhost:3032/test
FUSEKI_AUTH=admin:password
FUSEKI_DATASET=dataset_name

# Neo4j Configuration (Alternative)
NEO4J_URI=bolt://localhost:7689
NEO4J_AUTH=neo4j:password
```

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

### Initialize and Manage Agent State

Source: https://context7.com/growgraph/ontocast/llms.txt

Initializes agent state with file information, processing limits, rendering modes, and user instructions for ontology and facts. Tracks budget usage and applies graph updates.

```python
from ontocast.onto.state import AgentState, BudgetTracker
from ontocast.onto.enum import RenderMode, Status, FailureStage
from ontocast.onto.content_unit import ContentUnit
from rdflib import URIRef

# Initialize agent state
state = AgentState(
    files={"document.pdf": pdf_bytes},
    max_visits=3,
    max_chunks=10,
    render_mode=RenderMode.ONTOLOGY_AND_FACTS,
    ontology_max_triples=50000,
    dataset="my_dataset",
    ontology_user_instruction="Focus on extracting financial entities",
    facts_user_instruction="Extract dates and monetary amounts"
)

# Set input text and generate document hash
state.set_text("Apple Inc. was founded in 1976...")
print(f"Document IRI: {state.doc_iri}")
print(f"Document namespace: {state.doc_namespace}")

# Track budget usage
budget = state.budget_tracker
budget.add_usage(chars_sent=5000, chars_received=2000)
budget.add_ontology_update(num_operations=3, num_triples=45)
budget.add_facts_update(num_operations=5, num_triples=120)
print(budget.get_summary())
```

```python
from ontocast.onto.sparql_models import GraphUpdate, TripleOp

# Add ontology updates
update = GraphUpdate(
    triple_operations=[
        TripleOp(
            type="insert",
            prefixes={"ex": "https://example.org/"},
            graph=RDFGraph()  # Graph with triples to insert
        )
    ]
)
state.ontology_updates.append(update)
state.update_ontology()  # Apply updates to current_ontology

# Render updated ontology (creates new version with lineage)
updated_ontology = state.render_uptodate_ontology()

# Check progress
current, total = state.get_content_unit_progress_info()
print(f"Processing content unit {current}/{total}")

# Handle failures
state.set_failure(FailureStage.GENERATE_TTL_FOR_ONTOLOGY, "LLM timeout")
print(f"Failed at: {state.failure_stage}, reason: {state.failure_reason}")
state.clear_failure()
```

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

### Manage Triple Stores with Fuseki

Source: https://context7.com/growgraph/ontocast/llms.txt

Initializes a Fuseki triple store manager to interact with datasets for ontologies and facts. Fetches all available ontologies, displaying their IRI, version, and hash.

```python
import asyncio
from ontocast.tool.triple_manager.fuseki import FusekiTripleStoreManager
from ontocast.onto.ontology import Ontology
from ontocast.onto.rdfgraph import RDFGraph

# Initialize Fuseki manager
manager = FusekiTripleStoreManager(
    uri="http://localhost:3030",
    auth="admin:password",
    dataset="ontocast",
    ontologies_dataset="ontologies"
)

# Fetch all ontologies (returns latest version of each)
ontologies = await manager.afetch_ontologies()
for ont in ontologies:
    print(f"Ontology: {ont.iri} v{ont.version} (hash: {ont.hash[:16]}...)")
```