Quick Start¶

This guide will help you get started with OntoCast quickly. We'll walk through a simple example of processing a document and viewing the results.

Prerequisites¶

OntoCast installed (see Installation)
A sample document to process (e.g., a pdf or a markdown file)

Basic Example¶

Query the Server¶

curl -X POST http://url:port/process -F "file=@sample.pdf"

curl -X POST http://url:port/process -F "file=@sample.json"

url would be localhost for a locally running server, default port is 8999

Running a Server¶

To start an OntoCast server:

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

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

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

Backend selection is fully automatic based on available configuration
No explicit backend flags needed - just provide the required credentials/paths in .env
All paths and directories are configured via .env file

Configuration¶

OntoCast uses a hierarchical configuration system with environment variables. Create a .env file in your project directory:

# 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=1
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
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)
# Fuseki for persistence; omit both for in-memory pyoxigraph (default)
FUSEKI_URI=http://localhost:3030
FUSEKI_AUTH=username:password
#FUSEKI_DATASET=ontocast--test--facts
#FUSEKI_ONTOLOGIES_DATASET=ontocast--test--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

Alternative: Ollama Configuration¶

# For Ollama
LLM_PROVIDER=ollama
LLM_BASE_URL=http://localhost:11434
LLM_MODEL_NAME=granite3.3

Alternative: Claude / Gemini¶

# Anthropic Claude
LLM_PROVIDER=anthropic
LLM_MODEL_NAME=claude-sonnet-4-20250514
LLM_API_KEY=your-anthropic-api-key

# Google Gemini
LLM_PROVIDER=google
LLM_MODEL_NAME=gemini-2.0-flash
LLM_API_KEY=your-google-api-key

CLI Parameters¶

You can use these CLI parameters:

# Use custom .env file
ontocast --env-path /path/to/custom.env

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

# Process only first 5 chunks (for testing)
ontocast --env-path .env --head-chunks 5

Note: All paths and directories are configured via the .env file - no CLI overrides needed.

Receive Results¶

After processing, the ontology and the facts graph are returned in turtle format

{
    "data": {
        "facts": "# facts in turtle format",
        "ontology": "# ontology in turtle format"
    }
  ...
}

Configuration System¶

OntoCast uses a hierarchical configuration system:

ToolConfig: Configuration for tools (LLM, triple stores, paths)
ServerConfig: Configuration for server behavior
Environment Variables: Override defaults via .env file or environment

Key Environment Variables¶

Variable	Description	Default
`LLM_API_KEY`	API key for LLM provider	Required
`LLM_PROVIDER`	LLM provider (openai, ollama)	openai
`LLM_MODEL_NAME`	Model name	gpt-4o-mini
`FUSEKI_URI` + `FUSEKI_AUTH`	Use Fuseki for persistent triple store	Omit for in-memory (default)
`ONTOCAST_ONTOLOGY_DIRECTORY`	Seed ontology TTL files	Optional bootstrap
`MAX_VISITS`	Maximum visits per node	1
`BASE_RECURSION_LIMIT`	Base recursion limit for workflow	1000
`ONTOLOGY_MAX_TRIPLES`	Maximum triples allowed in ontology graph	50000
`ENABLE_ONTOLOGY_CONSOLIDATION`	Run ontology consolidation pass	false

Next Steps¶

Now that you've processed your first document, you can:

Try processing different types of documents (PDF, Word)
Configure Fuseki for persistent triple storage (see Triple Stores)
Check the API Endpoints for REST usage
Explore the User Guide for advanced usage