convez.ai
MCP ServerIntegração & APIsAvançado
leungBH

owl4agents

leungBH/owl4agents

Runtime OWL/RDF local com raciocínio semântico para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Runtime local de ontologias OWL/RDF com raciocínio semântico e servidor MCP para agentes IA. Importa, gerencia e realiza inferências sobre ontologias estruturadas, expondo essas capacidades via CLI e MCP server para enriquecimento semântico de agentes.

Instalação

$npx convez-ai leungBH/owl4agents

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.9.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Verificação de claims com raciocínio semântico em agentes
  • Integração de ontologias estruturadas como contexto para LLMs
  • Pesquisa em raciocínio automático e avaliação de reasoners

Veredito

Ferramenta técnica robusta para pesquisadores e desenvolvedores que precisam fundamentar raciocínio semântico em agentes IA. Exige domínio de ontologias OWL e oferece integração profunda via MCP, ideal para casos de uso onde contexto estruturado é crítico.

README

A tradução para o português deste README ainda está na fila.

owl4agents

Local OWL ontology runtime, reasoner integration, SPARQL query layer, and readonly MCP server for LLM agents.

owl4agents is a local-first OWL/RDF ontology runtime for researchers and agent developers. It imports, manages, reasons over, queries, and retrieves structured semantic context from OWL ontologies, then exposes those capabilities through both CLI commands and an MCP server.

Status: v0.6 research evaluation benchmarks and reasoner comparison. v0.6 adds experiment configuration, benchmark runner, QA evaluation, context-batch mode, evidence context JSONL export, and report generation with 4×4 confusion matrix and static reasoner version mapping.

v0.6 Quick Start

Requirements

  • Windows, macOS, or Linux
  • Java 22, with JAVA_HOME pointing to the JDK
  • Node.js 18+ for the npm launcher and MCP client entry point

On Windows, prefer JAVA_HOME over the Oracle javapath shim. The npm launcher uses JAVA_HOME\bin\java.exe when it is available. Note: java -jar owl4agents.jar may crash with ACCESS_VIOLATION on some Windows environments — use node tools/npm/bin/owl4agents.js or .\gradlew.bat run --args="..." instead.

From Clone to Smoke Test

# 1. Build and verify
.\gradlew.bat clean buildVerification
.\gradlew.bat :modules:ontology-cli:shadowJar

# 2. Check that your environment is ready
node tools/npm/bin/owl4agents.js setup --check

# 3. Initialize workspace and import onboarding fixtures
node tools/npm/bin/owl4agents.js setup --init

# 4. Run onboarding smoke test
node tools/npm/bin/owl4agents.js smoke

# 5. Generate MCP client configuration
node tools/npm/bin/owl4agents.js mcp-config --client claude

setup --check verifies Java, Gradle, source layout, workspace, npm launcher, and runtime jar. setup --init creates the workspace and imports the Pizza ontology and v0.3 claim-verification golden ontology. smoke runs a complete onboarding cycle: fixture import, ontology list, summary, reasoner list, classification, and claim verification. mcp-config --client claude prints a ready-to-paste JSON configuration for Claude Desktop.

All four commands are idempotent — rerunning them reports existing resources.

Try in 3 Minutes — v0.4 Example Packs

After building the jar, run any of these examples from the repository root:

# Claim verification — supported, contradicted, unknown, out_of_scope
node tools/npm/bin/owl4agents.js import test/corpus/golden/v0.3-claim-verification.owl v0.3-claim-verification --workspace claim-demo
node tools/npm/bin/owl4agents.js reason v0.3-claim-verification --workspace claim-demo
node tools/npm/bin/owl4agents.js verify-claim v0.3-claim-verification --claim test/fixtures/v0.3/claim-supported.json --workspace claim-demo --json

# Pizza reasoning — import, summary, classify
node tools/npm/bin/owl4agents.js import test/corpus/smoke/pizza.owl pizza --workspace pizza-demo
node tools/npm/bin/owl4agents.js summary pizza --workspace pizza-demo

# Biomedical grounding — disease hierarchy and claim verification
node tools/npm/bin/owl4agents.js import test/corpus/golden/v0.4-biomedical-grounding.owl v0.4-biomedical-grounding --workspace bio-demo
node tools/npm/bin/owl4agents.js reason v0.4-biomedical-grounding --workspace bio-demo
node tools/npm/bin/owl4agents.js verify-claim v0.4-biomedical-grounding --claim test/fixtures/v0.4/claim-bio-supported.json --workspace bio-demo --json

# v0.5 Batch workflow — verify-answer, evidence-context, review-answer
node tools/npm/bin/owl4agents.js import test/corpus/smoke/pizza.owl pizza-ontology --workspace workflow-demo
node tools/npm/bin/owl4agents.js reason pizza-ontology --workspace workflow-demo
node tools/npm/bin/owl4agents.js verify-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-supported.json --workspace workflow-demo
node tools/npm/bin/owl4agents.js review-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-mixed.json --policy strict --workspace workflow-demo --json

See examples/README.md for full step-by-step commands, expected output snippets, and troubleshooting.

v0.4-v0.6 Example Showcase

ExampleWhat it demonstratesInterfaceFixtureRun time
claim-verificationSupported, contradicted, unknown, and out_of_scope claim checkingCLItest/corpus/golden/v0.3-claim-verification.owl~5 seconds
pizza-reasoningOntology import, summary, hierarchy, restrictions, classificationCLItest/corpus/smoke/pizza.owl~10 seconds
agent-mcpMCP client configuration, readonly startup, tool list, tool-call samplesMCPNone (starts MCP server)~5 seconds
biomedical-groundingBiomedical-style grounding using a project-owned golden fixtureCLItest/corpus/golden/v0.4-biomedical-grounding.owl~5 seconds
Batch workflowverify-answer, evidence-context, review-answer with policyCLI/MCPtest/fixtures/v0.5/ claim batch fixtures~5 seconds
Agent skill packsCross-agent SOPs for claim verification, evidence-grounded answers, and scope checksReferencetools/skills/N/A (documentation)

All examples use node tools/npm/bin/owl4agents.js as the CLI entry point. See each example's README for prerequisites, commands, and expected output.

Verify Release from Fresh Checkout

.\gradlew.bat clean buildVerification
.\gradlew.bat :modules:ontology-cli:shadowJar
node tools/npm/test/launcher.test.js
node tools/npm/bin/owl4agents.js --version
node tools/npm/bin/owl4agents.js --help

Build the runnable CLI jar:

.\gradlew.bat :modules:ontology-cli:shadowJar

The runnable jar is generated at:

build/modules/ontology-cli/libs/owl4agents.jar

CLI from Source

Use the local npm launcher during v0.3.1 development:

node tools/npm/bin/owl4agents.js init
node tools/npm/bin/owl4agents.js import test/corpus/smoke/pizza.owl pizza
node tools/npm/bin/owl4agents.js list
node tools/npm/bin/owl4agents.js summary pizza
node tools/npm/bin/owl4agents.js search pizza Pizza
node tools/npm/bin/owl4agents.js entity pizza "http://www.co-ode.org/ontologies/pizza/pizza.owl#Pizza"
node tools/npm/bin/owl4agents.js query pizza --ask "ASK { ?s ?p ?o }"
node tools/npm/bin/owl4agents.js context pizza "Which toppings are related to pizza?"
node tools/npm/bin/owl4agents.js list-reasoners
node tools/npm/bin/owl4agents.js consistency pizza --reasoner hermit
node tools/npm/bin/owl4agents.js classify pizza --reasoner auto
node tools/npm/bin/owl4agents.js realize pizza --reasoner hermit

Note: reason, classify, realize, and consistency may recompute reasoner state for the current command. The reason command persists reasoning-report.json and inferred artifacts under the ontology workspace, so report can read the latest report in a later CLI or MCP process. Commands that need inferred facts still require reasoning artifacts to exist for the ontology.

v0.3 claim verification commands:

# Import and reason over the deterministic v0.3 claim-verification fixture
node tools/npm/bin/owl4agents.js import test/corpus/golden/v0.3-claim-verification.owl v0.3-claim-verification
node tools/npm/bin/owl4agents.js reason v0.3-claim-verification --reasoner hermit

# Verify supported, unknown, and out-of-scope claims
node tools/npm/bin/owl4agents.js verify-claim v0.3-claim-verification --claim test/fixtures/v0.3/claim-supported.json
node tools/npm/bin/owl4agents.js verify-claim v0.3-claim-verification --claim test/fixtures/v0.3/claim-unknown.json
node tools/npm/bin/owl4agents.js verify-claim v0.3-claim-verification --claim test/fixtures/v0.3/claim-real-out-of-scope.json

# Get evidence path for a verified claim
node tools/npm/bin/owl4agents.js evidence v0.3-claim-verification --claim test/fixtures/v0.3/claim-supported.json

# Explain why a claim is unknown
node tools/npm/bin/owl4agents.js explain-unknown v0.3-claim-verification --claim test/fixtures/v0.3/claim-unknown.json

# Detect missing or ambiguous entities in a claim
node tools/npm/bin/owl4agents.js missing-entities v0.3-claim-verification --claim test/fixtures/v0.3/claim-real-out-of-scope.json

# Counterexamples are available only when a claim verdict is contradicted
node tools/npm/bin/owl4agents.js counterexamples v0.3-claim-verification --claim test/fixtures/v0.3/claim-supported.json

v0.5 batch claim workflow commands (structured claim input required — v0.5 does not extract claims from free text):

# Import and reason over the Pizza ontology for v0.5 fixtures
node tools/npm/bin/owl4agents.js import test/corpus/smoke/pizza.owl pizza-ontology
node tools/npm/bin/owl4agents.js reason pizza-ontology --reasoner hermit

# Batch verify structured answer claims
node tools/npm/bin/owl4agents.js verify-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-supported.json

# Build compact evidence context for LLM agents
node tools/npm/bin/owl4agents.js evidence-context pizza-ontology --claims test/fixtures/v0.5/answer-claims-supported.json --max-context-tokens 500

# Review answer claims with handling guidance (strict, conservative, or report-only policy)
node tools/npm/bin/owl4agents.js review-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-mixed.json --policy strict
node tools/npm/bin/owl4agents.js review-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-mixed.json --policy conservative
node tools/npm/bin/owl4agents.js review-answer pizza-ontology --claims test/fixtures/v0.5/answer-claims-mixed.json --policy report-only

v0.6 benchmark and evaluation commands:

# Import and reason over the Pizza ontology for benchmark experiments
node tools/npm/bin/owl4agents.js import test/corpus/smoke/pizza.owl pizza-benchmark
node tools/npm/bin/owl4agents.js reason pizza-benchmark --reasoner hermit

# Run a benchmark experiment from config YAML
node tools/npm/bin/owl4agents.js benchmark-run test/fixtures/v0.6/configs/pizza-small.yaml

# Evaluate QA results with accuracy, false support rate, and confusion matrix
node tools/npm/bin/owl4agents.js eval-qa results/pizza-small-output.jsonl --json

# Build evidence context for a question set (context-batch mode)
node tools/npm/bin/owl4agents.js context-batch test/fixtures/v0.6/question-sets/pizza-50.jsonl --ontology pizza-benchmark --max-context-tokens 500

# Export evidence context as JSONL with truncation metadata
node tools/npm/bin/owl4agents.js evidence-context pizza-benchmark --claims test/fixtures/v0.5/answer-claims-supported.json --format jsonl --max-context-tokens 500

Or run the fat jar directly (Linux and macOS):

java -jar build/modules/ontology-cli/libs/owl4agents.jar init
java -jar build/modules/ontology-cli/libs/owl4agents.jar import test/corpus/smoke/pizza.owl pizza
java -jar build/modules/ontology-cli/libs/owl4agents.jar summary pizza
java -jar build/modules/ontology-cli/libs/owl4agents.jar consistency pizza --reasoner hermit

Windows limitation: java -jar owl4agents.jar may crash with ACCESS_VIOLATION on some Windows environments. This is a known JVM/OWL API interaction issue. On Windows, prefer node tools/npm/bin/owl4agents.js <command> or .\gradlew.bat run --args="<command>" instead. CI runs java -jar on Ubuntu without issues.

To keep a workspace outside the default user home location:

$env:OWL4AGENTS_HOME="D:\owl4agents-workspace"
node tools/npm/bin/owl4agents.js init

The default workspace is:

~/.owl4agents/workspaces/default/

Deploy for Local Agents

For v0.3, the supported deployment mode is source checkout plus local launcher. The npm bin entry is present so the local launcher can be exercised from this repository and packaged later, but publishing a self-contained npm registry package is planned for a later release.

  1. Clone or copy this repository.
  2. Install Java 22 and Node.js 18+.
  3. Run .\gradlew.bat clean buildVerification.
  4. Run .\gradlew.bat :modules:ontology-cli:shadowJar.
  5. Import at least one ontology into the workspace.
  6. Point your MCP client to node tools/npm/bin/owl4agents.js mcp --readonly.

Example:

$env:OWL4AGENTS_HOME="D:\owl4agents-workspace"
node tools/npm/bin/owl4agents.js init
node tools/npm/bin/owl4agents.js import D:\ontologies\pizza.owl pizza
node tools/npm/bin/owl4agents.js mcp --readonly

MCP Client Configuration

The recommended way to configure MCP clients is the mcp-config command, which generates a ready-to-paste JSON configuration with the correct command, args, and environment for your client. For a complete MCP demo with config snippets and a sanitized tool-call transcript, see examples/agent-mcp/.

# Generate Claude Desktop config
node tools/npm/bin/owl4agents.js mcp-config --client claude

# Generate generic config (any stdio-based MCP client)
node tools/npm/bin/owl4agents.js mcp-config --client generic

# Generate Cursor config
node tools/npm/bin/owl4agents.js mcp-config --client cursor

# Override workspace location
node tools/npm/bin/owl4agents.js mcp-config --client claude --workspace-home D:/owl4agents-workspace

# Write config to file
node tools/npm/bin/owl4agents.js mcp-config --client claude --out claude-mcp-config.json

Note: codex and codex-cli config templates are deferred until their public client naming and configuration format stabilize. They are not advertised as supported clients in v0.3.1.

The generated config uses the source-checkout npm launcher and sets OWL4AGENTS_HOME to your workspace. Unknown client names are rejected with a supported-client list.

Alternatively, you can write the config manually. Use this form for MCP clients that accept a JSON server config, such as Claude Desktop, Cursor-style MCP configuration, or other local agent runtimes:

{
  "mcpServers": {
    "owl4agents": {
      "command": "node",
      "args": [
        "D:/path/to/owl4agents/tools/npm/bin/owl4agents.js",
        "mcp",
        "--readonly"
      ],
      "env": {
        "OWL4AGENTS_HOME": "D:/owl4agents-workspace"
      }
    }
  }
}

On Windows, if your client has trouble with stdin/stdout through Node, use the bundled command wrapper. This wrapper runs MCP directly through Java in classpath mode (java -cp), bypassing Node's stdin forwarding issues and the java -jar ACCESS_VIOLATION crash:

{
  "mcpServers": {
    "owl4agents": {
      "command": "D:/path/to/owl4agents/tools/bin/owl4agents-mcp.cmd",
      "args": ["--readonly"],
      "env": {
        "OWL4AGENTS_HOME": "D:/owl4agents-workspace"
      }
    }
  }
}

v0.3 MCP is readonly. Import ontologies with the CLI first, then let agents query, reason, verify structured claims, and retrieve evidence through MCP.

Useful v0.3 MCP tools include the inherited readonly query/reasoning surface plus the new claim verification surface. The v0.3 acceptance gate verifies 16 representative MCP tools: 11 inherited core/reasoning tools plus 5 new claim verification and evidence grounding tools.

ToolPurpose
ontology_listList imported ontologies
ontology_summaryReturn ontology IRI, profile, imports, and entity counts
ontology_search_entitiesSearch classes, properties, and individuals
ontology_get_class_contextInspect class hierarchy, equivalent classes, disjoint classes, and restrictions
ontology_get_object_property_contextInspect object property domain, range, inverse properties, and hierarchy
ontology_get_data_property_contextInspect data property domain, range, datatype, and hierarchy
ontology_get_individual_contextInspect individual types and assertions
ontology_validate_sparqlValidate a SPARQL query without execution
ontology_sparql_selectExecute readonly SELECT
ontology_sparql_askExecute readonly ASK
ontology_sparql_constructExecute readonly CONSTRUCT
ontology_sparql_describeExecute readonly DESCRIBE
ontology_get_qa_contextBuild ontology-grounded context for an agent question
ontology_list_reasonersList available reasoners and capabilities
ontology_run_reasonerRun selected reasoning tasks
ontology_check_consistencyCheck ontology consistency with a reasoner
ontology_classifyCompute inferred class hierarchy
ontology_realize_instancesInfer individual class memberships
ontology_get_inferred_factsReturn inferred facts for an entity or graph scope
ontology_check_entailmentCheck whether a supported structured OWL axiom is entailed
ontology_get_class_restrictionsInspect class restrictions
ontology_get_property_characteristicsInspect property characteristics
ontology_get_datatype_constraintsInspect datatype facets and constraints
ontology_validate_literalValidate a literal against datatype and known constraints
ontology_check_class_compatibilityCheck whether two classes can overlap or conflict
ontology_check_individual_membershipCheck explicit or inferred individual class membership
ontology_check_relation_assertionCheck explicit or inferred object property assertions

v0.3 Claim Verification and Evidence Grounding Tools

ToolPurpose
ontology_verify_claimVerify a structured claim and return verdict: supported, contradicted, unknown, or out_of_scope
ontology_get_evidence_pathAssemble evidence path with inferred facts and reasoning report for a verified claim
ontology_find_counterexamplesFind counterexamples for a contradicted claim
ontology_explain_unknownExplain why a claim received an unknown verdict with reason category and suggested action
ontology_detect_missing_entitiesDetect matched, ambiguous, missing, and out-of-scope entities in a claim

v0.5 Batch Claim Workflow Tools

ToolPurpose
ontology_verify_claims_batchVerify a structured batch of answer claims and return per-claim verdicts plus aggregate status
ontology_build_evidence_contextBuild compact evidence context for LLM agents from workflow reports
ontology_review_answer_claimsReview answer claims with strict, conservative, or report-only handling guidance

v0.5 workflow tools require structured claim input (batch JSON with answerId, claims[], and per-claim id, type, subject, predicate, object). They do not extract claims from free text. See tools/skills/ for SOP packs.

v0.6 Research Evaluation and Benchmark Tools

ToolPurpose
ontology_benchmark_runRun a benchmark experiment from a YAML configuration, producing JSONL results with per-question verdicts, accuracy, and timing
ontology_eval_qaEvaluate benchmark results: compute accuracy, false support rate, unresolved rate, verification coverage, and 4×4 confusion matrix
ontology_context_batchBuild evidence context for a question set, with character-based truncation metadata for LLM agent prompts
ontology_build_evidence_context (format=jsonl)Export evidence context as streamable JSONL with truncation metadata (budgetCharsUsed, totalAvailableEvidenceChars)

v0.6 tools are readonly. They require pre-imported ontologies and structured claim inputs. Experiment configs use YAML with required fields (name, ontologyIds, questionSetPath, reasoners, outputPath). repeatCount is rejected. False support rate and unresolved rate are separate metrics, not combined as hallucination rate.

Why owl4agents

Large language model agents are good at natural language reasoning, but they often lack explicit, inspectable, and reproducible semantic grounding. OWL ontologies provide structured domain knowledge, constraints, class hierarchies, property semantics, and machine-checkable reasoning.

owl4agents aims to connect these two worlds:

Domain OWL/RDF ontologies
  -> OWL API loading and normalization
  -> mature reasoners such as HermiT, ELK, Openllet
  -> entity search and semantic context retrieval
  -> CLI and MCP tools
  -> ontology-grounded LLM agents

The project is not trying to implement a new OWL reasoner. It is an integration and runtime layer around mature Semantic Web tooling, with special attention to local agent workflows and reproducible research.

Target Users

  • Researchers studying ontology-enhanced LLMs and agents
  • Developers building domain knowledge enhanced agents
  • Knowledge engineers managing local OWL/RDF ontologies
  • Advanced users who want local agents to call ontology reasoning tools

Planned Features

  • Import and manage local OWL/RDF ontologies
  • Run OWL reasoners such as HermiT, ELK, and Openllet
  • Check consistency, classify ontologies, and infer instance types
  • Search ontology entities by label, comment, IRI, and alias
  • Build ontology-grounded QA context for LLM agents
  • Expose ontology tools through CLI and MCP
  • Keep all data local by default
  • Record snapshots and audit logs for write operations
  • Support research workflows such as context export, benchmark runs, and reasoner comparison
  • Provide an npm launcher for simple installation while keeping the semantic runtime in Java

Core Design Decisions

Integrate before reinventing

owl4agents should prefer mature open-source libraries whenever they already solve a problem well. The project should focus on orchestration, consistent local workflows, MCP tool design, reproducibility, and agent-oriented context construction.

Do not rebuild these foundations unless there is a strong reason:

CapabilityPreferred open-source foundation
OWL loading, editing, serializationOWL API
OWL 2 DL reasoningHermiT
OWL 2 EL classificationELK
Inconsistency explanation / Pellet-style workflowsOpenllet
RDF graph handling and SPARQLApache Jena ARQ
Ontology workflow ideasROBOT
CLI frameworkPicocli
MCP protocol integrationProject-local JSON-RPC stdin/stdout adapter
Packaging Java runtimejlink / jpackage

The local code should mostly provide adapters, stable service contracts, permission boundaries, workspace conventions, indexes, audit logs, and research-friendly context builders.

Java semantic runtime

Java is the planned core runtime because the mature OWL ecosystem already lives there:

  • OWL API for OWL 2 loading, editing, serialization, and profile checks
  • HermiT for OWL 2 DL reasoning
  • ELK for high-performance OWL 2 EL classification
  • Openllet for Pellet-style DL reasoning and explanation workflows
  • Apache Jena ARQ for RDF and SPARQL support
  • Picocli for CLI implementation
  • Project-local JSON-RPC stdin/stdout adapter for exposing MCP-compatible tools to local agents

npm as installer, not reasoning runtime

The desired future user experience is:

npx -y owl4agents mcp

In v0.3, use the local launcher from a source checkout after building the runnable jar:

./gradlew :modules:ontology-cli:shadowJar
node tools/npm/bin/owl4agents.js mcp --readonly

Node.js only acts as the launcher and distribution entry point. The actual ontology management, indexing, SPARQL, and MCP tool behavior runs inside the Java runtime.

One service layer for CLI and MCP

CLI and MCP should share the same application service:

OntologyService
  -> CLI Adapter
  -> MCP Adapter
  -> Optional HTTP Adapter

This keeps behavior, tests, errors, permissions, and reasoning results consistent across interfaces.

Troubleshooting

Missing fat jar

If node tools/npm/bin/owl4agents.js exits with a "runtime not found" error, the runnable jar has not been built:

.\gradlew.bat :modules:ontology-cli:shadowJar

The jar is generated at build/modules/ontology-cli/libs/owl4agents.jar (approximately 46 MB). The launcher looks for this jar relative to the npm script directory, so it must exist under the project root.

Java not found or wrong version

owl4agents requires Java 22 (as configured in the Gradle toolchain). If java -version reports a different version or java is not on PATH:

  1. Install JDK 22 and set JAVA_HOME to the JDK directory.
  2. On Windows, prefer JAVA_HOME\bin\java.exe over the Oracle javapath shim, which may point to an older JDK.
  3. Verify: "$env:JAVA_HOME\bin\java.exe" -version should report 22.

If JAVA_HOME is not set, the launcher falls back to java on PATH, then to the Gradle wrapper as a last resort (which does not support MCP stdin).

Reasoner selection

  • HermiT: OWL 2 DL reasoning - consistency, classification, realization. Does not support explanation.
  • ELK: OWL 2 EL reasoning - fast classification and consistency for EL-profile ontologies. Does not support explanation.
  • Openllet: Explanation-oriented workflows - inconsistency explanation, unsatisfiable class explanation. Supports all OWL 2 DL reasoning tasks.
  • auto: Profile-based selection - OWL 2 EL -> ELK, OWL 2 DL -> HermiT, explanation requested -> Openllet.

MCP stdio issues on Windows

The MCP protocol uses stdin/stdout for JSON-RPC. On Windows, Node's execSync with stdio: 'inherit' may not forward stdin correctly for MCP sessions. The bundled tools/bin/owl4agents-mcp.cmd wrapper runs MCP directly through Java in classpath mode (java -cp), bypassing Node's forwarding issues and the java -jar ACCESS_VIOLATION crash. Use this wrapper when MCP clients have trouble connecting through the npm launcher.

Launcher startup failures

The npm launcher follows a deterministic runtime discovery order:

  1. OWL4AGENTS_RUNTIME env var (explicit override, supports .js scripts for testing)
  2. build/modules/ontology-cli/libs/owl4agents.jar (shadow jar from Gradle build)
  3. build/modules/ontology-cli/libs/ontology-cli-all.jar (fat jar)
  4. build/modules/ontology-distribution/libs/ontology-distribution.jar
  5. JAVA_HOME\bin\java with classpath mode
  6. java on PATH
  7. Gradle wrapper (last resort; MCP stdin not supported)

If none of these paths are available, the launcher exits with code 2 and prints actionable guidance including the shadowJar build command and Java version requirement.

Setup check failures

setup --check validates six environment prerequisites. If any check fails:

  • Java not found: Install Java 22 and set JAVA_HOME. See the "Java not found" section above.
  • Gradle wrapper missing: Ensure gradlew or gradlew.bat exists in the project root. Clone the full repository rather than a partial copy.
  • Source layout missing: The project expects modules/ and tools/npm/ directories under the project root. Run from within the cloned repository.
  • Workspace not writable: The default workspace is ~/.owl4agents/workspaces/default/. Ensure the parent directory exists and is writable, or set OWL4AGENTS_HOME to a writable location.
  • npm launcher files missing: Ensure tools/npm/bin/owl4agents.js and tools/npm/package.json exist under the project root.
  • Runtime jar missing: Run .\gradlew.bat :modules:ontology-cli:shadowJar to build the fat jar. See the "Missing fat jar" section above.

setup --check --dry-run reports planned remediation actions without modifying any files.

Smoke test failures

smoke runs a full onboarding cycle. Common failure causes:

  • Fixture import fails: The smoke test imports test/corpus/smoke/pizza.owl and test/corpus/golden/v0.3-claim-verification.owl. If these files are missing, the smoke test fails. Clone the full repository or download the fixtures.
  • Workspace not writable: smoke defaults to a temporary workspace. If the system temp directory is not writable, use --workspace <path> to specify an explicit home directory. The workspace will be created under <path>/workspaces/default/. If you pass a path that already ends with workspaces/default, the parent directory is used automatically.
  • Claim verification fails: The smoke test verifies a supported claim and an out-of-scope claim. If the golden ontology or claim fixtures are missing or corrupted, verification fails. Check test/fixtures/v0.3/claim-smoke-supported.json and test/fixtures/v0.3/claim-real-out-of-scope.json.

mcp-config failures

  • Unknown client: mcp-config --client unknown exits nonzero and prints a list of supported clients (claude, cursor, generic).
  • Generated JSON has empty command: Ensure the project root is discoverable (contains build.gradle.kts and settings.gradle.kts) so the launcher path can be resolved.
  • Write flags in generated config: The generated config never includes --allow-write. If you see write flags, you are using a manually constructed config, not the output of mcp-config.

Release asset verification

Download the jar, checksum, and release notes from the GitHub Actions artifact or release page:

Windows note: The release jar is a runnable fat jar on Linux and macOS. On Windows, it may crash with ACCESS_VIOLATION when invoked as java -jar owl4agents.jar. Use the npm launcher (node tools/npm/bin/owl4agents.js) instead.

# Verify checksum
$hash = (Get-FileHash owl4agents.jar -Algorithm SHA256).Hash
$expected = (Get-Content owl4agents.jar.sha256 -Raw).Trim().Split()[0]
if ($hash -eq $expected) { "Checksum OK" } else { "Checksum MISMATCH" }

Planned Architecture

+------------------------------------------------------------------+
|                         npm package                              |
|                    owl4agents launcher                           |
+-------------------------------+----------------------------------+
                                |
                                v
+------------------------------------------------------------------+
|                    owl4agents Java Runtime                       |
|                                                                  |
|  +----------------------+      +-------------------------------+ |
|  | CLI Adapter          |      | MCP Server Adapter             | |
|  | Picocli              |      | JSON-RPC stdio adapter        | |
|  +----------+-----------+      +---------------+---------------+ |
|             |                                  |                 |
|             +----------------+-----------------+                 |
|                              v                                   |
|                 Ontology Application Service                     |
|                              |                                   |
|  +---------------------------+--------------------------------+  |
|  |                           |                                |  |
|  v                           v                                v  |
| OWL API Facade          Query / SPARQL Layer          Retrieval Layer
|  |                           |                                |  |
|  v                           v                                v  |
| Reasoner Layer          Validation Layer              QA Context Builder
|  |                           |                                |  |
|  +---------------------------+----------------+---------------+  |
|                                              v                  |
|                         Evidence / Provenance Layer             |
|                                              |                  |
|                                              v                  |
|                Workspace / Storage / Index / Snapshot / Logs    |
+------------------------------------------------------------------+

The architecture separates concerns so new features can be added without changing every interface:

  • OWL API Facade handles ontology loading, saving, entity resolution, axioms, profiles, and format conversion.
  • Query / SPARQL Layer handles RDF graph access through Apache Jena ARQ.
  • Reasoner Layer handles HermiT, ELK, Openllet, and future reasoner adapters.
  • Retrieval Layer handles entity matching, graph neighborhoods, and context ranking.
  • Validation Layer checks entailment, compatibility, constraints, and claim support.
  • Evidence / Provenance Layer records why a result was returned, which axioms or triples support it, and which reasoner or graph produced it.
  • Workspace / Storage Layer keeps local files, indexes, inferred graphs, snapshots, and audit logs.

Technology Stack

LayerTechnologyPurpose
Main runtimeJava 22Unified semantic runtime for CLI, MCP, reasoning, and indexing
Build toolGradle Kotlin DSLMulti-module project management
OWL coreOWL APIOWL 2 loading, editing, saving, profile checks
Ontology workflowROBOT coreReusable ideas and potential JVM integration for ontology workflows
DL reasonerHermiTOWL 2 DL consistency, classification, realization
EL reasonerELKFast classification for large OWL 2 EL ontologies
Explanation / compatibilityOpenlletInconsistency explanation and Pellet-style capabilities
RDF / SPARQLApache Jena ARQRDF graph handling and SPARQL queries
CLIPicocliJava command-line interface
MCPProject-local JSON-RPC stdin/stdout adapterMCP-compatible server for local agent clients
Local storageFilesystem + JSONLPortable, inspectable workspace, indexes, logs
Distributionnpm launcher + jlink / jpackageSimple npm entry point with self-contained Java runtime
TestingJUnit 5Unit, integration, and reasoner comparison tests

Pinned Dependency Versions

v0.3 pins the Semantic Web and runtime dependencies that affect parser, reasoner, verification, launcher, and MCP compatibility:

ComponentMaven / tool coordinateVersionUsed by
Java toolchainJDK22All Java modules
Gradle wrappergradle-8.14-bin.zip8.14Build and verification
OWL APInet.sourceforge.owlapi:owlapi-distribution5.1.20OWL loading, profiles, axioms, serialization
HermiTnet.sourceforge.owlapi:org.semanticweb.hermit1.4.5.519OWL 2 DL consistency, classification, realization
ELK OWL APIio.github.liveontologies:elk-owlapi0.6.0OWL 2 EL classification and consistency
Openllet OWL APIcom.github.galigator.openllet:openllet-owlapi2.6.5Explanation-oriented DL workflows
Apache Jenaorg.apache.jena:apache-jena-libs5.3.0RDF graph handling and SPARQL
Picocliinfo.picocli:picocli / picocli-codegen4.7.7CLI commands and help
Gsoncom.google.code.gson:gson2.13.1JSON-RPC and structured payloads
Shadow plugincom.github.johnrengelman.shadow8.1.1Runnable fat jar generation
JUnitorg.junit:junit-bom5.12.2Unit, integration, and acceptance tests
Node.jsnpm launcher runtime18+Local launcher and MCP client entry point

The reasoner module excludes transitive OWL API dependencies from HermiT, ELK, and Openllet so the project uses the pinned OWL API 5.1.20 consistently. This avoids the HermiT/OWL API method mismatch found during v0.2 acceptance testing.

Delivery Gate

owl4agents treats implementation, testing, build verification, and acceptance reporting as one delivery package. A version is not considered complete when code is merely written or tests merely exist. It is complete only after the required commands run successfully and a timestamped acceptance report is produced.

For every version or OpenSpec change, developers must provide:

  • A reproducible build command that works from a fresh checkout.
  • A reproducible test command that runs the required unit, integration, contract, and acceptance tests.
  • A completed acceptance report with date/time, environment, fixture list, scenario status, failures, skipped scenarios, and re-test notes.
  • Evidence that CLI and MCP behavior are checked through the same service contracts where both interfaces expose the same capability.
  • Evidence that required fixtures are present and missing required fixtures fail the test run.

The default verification command should be:

.\gradlew.bat clean buildVerification

To run the CLI or MCP launcher from source after a clean checkout, also build the runnable fat jar:

.\gradlew.bat :modules:ontology-cli:shadowJar

The Gradle wrapper is part of the delivery contract. The repository must include gradlew, gradlew.bat, gradle/wrapper/gradle-wrapper.jar, and gradle/wrapper/gradle-wrapper.properties unless the project explicitly replaces Gradle with another documented build entry point.

Release Checklist

Before releasing any version, verify each step:

  1. Build: .\gradlew.bat clean buildVerification exits 0
  2. Shadow jar: .\gradlew.bat :modules:ontology-cli:shadowJar produces build/modules/ontology-cli/libs/owl4agents.jar
  3. Unit and contract tests: .\gradlew.bat test exits 0
  4. Launcher tests: node tools/npm/test/launcher.test.js exits 0 when launcher changes are included
  5. Smoke commands: node tools/npm/bin/owl4agents.js --help, --version, and list-reasoners all work
  6. v0.3 claim fixtures: supported, contradicted, unknown, out-of-scope, malformed, unsupported-type, and unknown-ontology fixtures pass their expected gates
  7. v0.4 example validation: each required example pack (claim-verification, pizza-reasoning, agent-mcp, biomedical-grounding) passes manifest, fixture, execution, sanitization, and drift checks
  8. Example manifest checks: every examples/*/example.yaml contains required fields (id, title, description, interfaces, fixtures, commands, expectedOutputs, ciRequired, attribution) and fixture paths reference existing files
  9. README link checks: root README links to every required example and MCP section references examples/agent-mcp/; no stale or broken links
  10. Fixture attribution checks: test/corpus/README.md documents source, attribution, and license for every required fixture
  11. CLI/MCP parity: overlapping v0.3 tools return equivalent verdicts, evidence shapes, and error codes
  12. Version alignment: Gradle version, npm package.json version, Picocli version attribute, and MCP serverInfo.version all match
  13. Acceptance report: Timestamped report under test/reports/acceptance/ with environment, commands, gate results, defects, retest notes, skipped scenarios, and verdict
  14. Git hygiene: required source, tests, contracts, fixtures, and examples are tracked; local reports, OpenSpec files, private ontologies, generated classes, build outputs, and temp/examples/ are ignored
  15. Git tag: Tag the release commit, for example v0.4.0
  16. Push: Push the commit and tag to the remote

Acceptance reports are stored locally under:

test/reports/acceptance/

This directory is intentionally ignored by Git so local test evidence and environment details are preserved without being published to GitHub.

Definition of Done

A change or version cannot be marked done unless all of the following are true:

  • The canonical build/test command exits successfully.
  • Required acceptance fixtures are present; missing required fixtures fail the run instead of being silently skipped.
  • Tests fail on placeholder success responses, empty MCP payloads, broken catalog readback, and unsupported command paths.
  • CLI and MCP parity tests pass for overlapping readonly operations.
  • npm launcher smoke tests pass for help output, version output, command forwarding, exit code semantics, runtime discovery, and MCP startup path verification.
  • The acceptance report records all failures and skipped scenarios explicitly.
  • The final report path and command output summary are included in the handoff.

Planned Modules

modules/
  ontology-core/
  ontology-owlapi/
  ontology-reasoner/
  ontology-query/
  ontology-retrieval/
  ontology-validation/
  ontology-benchmark/
  ontology-provenance/
  ontology-storage/
  ontology-cli/
  ontology-mcp/
  ontology-distribution/

tools/
  skills/
  npm/
    package.json
    bin/owl4agents.js
    platform-packages/
  bin/
    owl4agents-mcp.cmd
ModuleResponsibility
ontology-coreDomain model, application service interfaces, result and error models
ontology-owlapiOWL API wrapper for loading, saving, entity resolving, profile checks, axiom editing
ontology-reasonerUnified adapters for HermiT, ELK, and Openllet
ontology-queryApache Jena ARQ query execution, SPARQL validation, graph scope selection
ontology-retrievalEntity search, graph neighborhood, hierarchy context, relation context, QA context construction
ontology-validationEntailment checks, class compatibility, literal validation, claim verification, and evidence grounding
ontology-benchmarkExperiment configuration, benchmark runner, QA evaluation, context-batch, evidence context JSONL, report generation
ontology-provenanceSource tracking, reasoning reports, support/contradiction traces (future: extended provenance)
ontology-storageLocal workspace, catalog, metadata, snapshots, indexes, audit logs
ontology-cliPicocli-based command adapter
ontology-mcpMCP-compatible JSON-RPC stdin/stdout tool adapter
ontology-distributionjlink / jpackage packaging
npmnpm launcher and platform package entry points

Planned CLI

The first stable CLI should look like this:

owl4agents init
owl4agents import ./medical.owl --name medical
owl4agents list
owl4agents summary medical
owl4agents search medical "myocardial infarction"
owl4agents entity medical "ex:MyocardialInfarction"
owl4agents neighborhood medical "ex:MyocardialInfarction" --depth 2
owl4agents reason medical --reasoner auto
owl4agents consistency medical --reasoner hermit
owl4agents explain medical --entity ex:MyocardialInfarction
owl4agents context medical "What symptoms are associated with myocardial infarction?"
owl4agents export medical --format ttl --out ./medical.ttl
owl4agents mcp --workspace default --readonly

Command groups:

workspace:
  init
  workspace list
  workspace use
  workspace remove

ontology:
  import
  list
  summary
  export
  diff
  snapshot
  rollback

entity:
  search
  entity
  classes
  properties
  individuals
  neighborhood

reasoning:
  reason
  consistency
  classify
  realize
  entailment
  explain

agent:
  context
  verify-answer
  evidence-context
  review-answer
  mcp
  inspect-tools

debug:
  doctor
  version
  env

Planned MCP Tools

The initial MCP server should be read-only by default:

owl4agents mcp --readonly

The MCP surface should be broad enough for real agent workflows, but staged carefully. The long-term tool design is organized by semantic layer, not by implementation module. That keeps the protocol stable while internals evolve.

Tool design principles

  • Prefer precise tools for common agent reasoning tasks, not only generic SPARQL.
  • Keep SPARQL available as an escape hatch for advanced graph queries.
  • Separate read tools, reasoning tools, verification tools, and write tools.
  • Return structured evidence whenever possible: source axioms, triples, inferred facts, graph scope, and reasoner metadata.
  • Distinguish supported, contradicted, unknown, and out_of_scope instead of forcing a false boolean.
  • Make write tools unavailable unless the server is started with --allow-write.

Agent anti-hallucination loop

The intended agent workflow is:

User question
  -> retrieve candidate entities and ontology context
  -> inspect class/property/individual semantics
  -> run SPARQL or reasoner checks when needed
  -> draft answer
  -> verify claims against ontology evidence
  -> return answer with supported claims, uncertainty, and evidence paths

The most important tools for reducing hallucinations are not only context retrieval tools. They are entailment, compatibility, constraint, and claim verification tools.

Workspace and ontology tools

ToolStageDescription
ontology_listv0.1List local ontologies in a workspace
ontology_summaryv0.1Return ontology metadata, profile, imports, and entity counts
ontology_get_metadatav0.1Return ontology IRI, version IRI, source path, canonical path, and timestamps
ontology_get_importsv0.2Inspect import closure and imported ontology metadata
ontology_get_profilev0.1Return OWL profile information and profile violations
ontology_list_graphsv0.1 to v0.2List queryable graph scopes (explicit in v0.1; adds inferred, union in v0.2)

Class tools

These tools cover taxonomy and class-level axioms.

ToolStageDescription
ontology_get_classesv0.1List or filter classes
ontology_get_class_contextv0.1Return labels, comments, parents, children, equivalent classes, disjoint classes, and restrictions
ontology_get_subclassesv0.1Return direct or transitive subclasses
ontology_get_superclassesv0.1Return direct or transitive superclasses
ontology_get_equivalent_classesv0.1Return equivalent class axioms
ontology_get_disjoint_classesv0.1Return disjoint class axioms
ontology_get_class_restrictionsv0.2Return someValuesFrom, allValuesFrom, cardinality, hasValue, and datatype restrictions
ontology_check_class_compatibilityv0.2Check whether two classes can overlap or are disjoint / unsatisfiable together
ontology_get_unsat_classesv0.2Return unsatisfiable classes after reasoning
ontology_explain_unsat_classv0.2Explain why a class is unsatisfiable

Object property tools

Object properties are essential for relation correctness. They prevent agents from inventing relations or reversing relation direction.

ToolStageDescription
ontology_get_object_propertiesv0.1List object properties
ontology_get_object_property_contextv0.1Return labels, comments, domain, range, hierarchy, inverse properties, and characteristics
ontology_get_property_domain_rangev0.1Return domain and range for object or data properties
ontology_get_inverse_propertiesv0.1Return inverse object property axioms
ontology_get_equivalent_propertiesv0.2Return equivalent property axioms
ontology_get_disjoint_propertiesv0.2Return disjoint property axioms
ontology_get_property_characteristicsv0.2Return functional, inverse functional, transitive, symmetric, asymmetric, reflexive, and irreflexive flags
ontology_get_property_chain_axiomsv0.7Return property chain axioms
ontology_find_relations_between_entitiesv0.2Find object property relations between two entities or individuals

Data property and datatype tools

Data properties help agents avoid wrong values, wrong units, invalid datatypes, and invented measurements.

ToolStageDescription
ontology_get_data_propertiesv0.1List data properties
ontology_get_data_property_contextv0.1Return labels, comments, domain, range, datatype, and hierarchy
ontology_get_datatype_constraintsv0.2Return datatype facets such as min/max, pattern, enumeration, and cardinality constraints
ontology_get_data_property_assertionsv0.2Return literal values for an individual
ontology_validate_literalv0.2Validate a literal against datatype, range, and known constraints
ontology_find_individuals_by_data_propertyv0.7Find individuals by data property value or value range

Individual and assertion tools

Individuals are where many agent claims become concrete and checkable.

ToolStageDescription
ontology_get_individualsv0.1List or filter individuals
ontology_get_individual_contextv0.1Return labels, comments, explicit types, inferred types, object property assertions, and data property assertions
ontology_get_individual_typesv0.1Return explicit and inferred class memberships
ontology_get_object_property_assertionsv0.2Return object property facts for an individual
ontology_get_same_individualsv0.2Return owl:sameAs individuals
ontology_get_different_individualsv0.2Return owl:differentFrom individuals
ontology_check_individual_membershipv0.2Check whether an individual belongs to a class
ontology_check_relation_assertionv0.2Check whether a relation between two individuals is asserted or entailed

SPARQL and RDF tools

SPARQL should be part of the MCP design from the beginning, because many ontology users need direct graph queries beyond prebuilt context tools.

ToolStageDescription
ontology_sparql_selectv0.1Run a read-only SPARQL SELECT query over explicit, inferred, or union graph
ontology_sparql_askv0.1Run a SPARQL ASK query
ontology_sparql_constructv0.1Run a SPARQL CONSTRUCT query and return RDF triples
ontology_sparql_describev0.1Run a SPARQL DESCRIBE query for one or more resources
ontology_validate_sparqlv0.1Parse and validate a SPARQL query before execution

SPARQL safety rules:

  • v0.1 allows read-only query forms only: SELECT, ASK, CONSTRUCT, DESCRIBE
  • Update operations such as INSERT, DELETE, LOAD, CLEAR, CREATE, DROP, and MOVE are blocked
  • Query execution must support timeout and result limits
  • File access from SPARQL must be disabled unless explicitly designed later

Reasoning tools

ToolStageDescription
ontology_list_reasonersv0.2List installed reasoners and capabilities
ontology_run_reasonerv0.2Run selected reasoning tasks
ontology_check_consistencyv0.1 to v0.2Check ontology consistency (v0.2: extended with reasoner integration)
ontology_classifyv0.2Compute inferred class hierarchy
ontology_realize_instancesv0.2Infer individual class memberships
ontology_check_entailmentv0.2Check whether a supported structured OWL axiom is entailed
ontology_get_inferred_factsv0.2Return inferred axioms or triples for an entity or graph scope
ontology_explain_entailmentv0.7Explain why a conclusion is entailed
ontology_explain_inconsistencyv0.2Explain inconsistent axioms
ontology_get_reasoning_reportv0.2Return the latest reasoning report

Validation and anti-hallucination tools

These are the tools that turn ontology access into answer verification.

ToolStageDescription
ontology_verify_claimv0.3 releasedVerify one structured claim as supported, contradicted, unknown, or out_of_scope
ontology_verify_claims_batchv0.5Verify a structured batch of answer claims and return per-claim verdicts plus aggregate status
ontology_build_evidence_contextv0.5Build compact evidence context for LLM agents from workflow reports
ontology_find_counterexamplesv0.3 releasedFind facts or axioms that contradict a claim
ontology_check_constraintsv0.7Validate data with SHACL or ontology-derived constraints
ontology_explain_unknownv0.3 releasedExplain why a claim cannot be verified
ontology_review_answer_claimsv0.5Review answer claims with strict/conservative/report-only handling guidance
ontology_benchmark_runv0.6Run benchmark experiment from YAML config, produce JSONL results
ontology_eval_qav0.6Evaluate benchmark results with accuracy, false support rate, unresolved rate, and 4×4 confusion matrix
ontology_context_batchv0.6Build per-question evidence context for question sets with truncation metadata

Retrieval and QA context tools

ToolStageDescription
ontology_search_entitiesv0.1Search classes, properties, and individuals
ontology_get_entity_contextv0.1Return labels, comments, class/property/individual context, and related facts
ontology_get_graph_neighborhoodv0.1Return local graph neighborhood around an entity
ontology_get_qa_contextv0.1Build ontology-grounded context for an agent question
ontology_get_evidence_pathv0.3 releasedReturn the path from matched entities to supporting facts
ontology_get_scopev0.2Describe ontology domain coverage and known limitations
ontology_detect_missing_entitiesv0.3 releasedFind terms in a question that are not covered by the ontology

Editing, snapshot, and audit tools

These tools require --allow-write.

ToolStageDescription
ontology_importv0.8Import an ontology into a workspace through write-enabled MCP
ontology_exportv0.8Export ontology in a selected format
ontology_edit_axiomv0.8Apply structured ontology edits
ontology_diffv0.8Show differences between snapshots or ontology versions
ontology_snapshotv0.8Create a named snapshot
ontology_rollbackv0.8Roll back to a snapshot
ontology_get_audit_logv0.8Inspect write operations and MCP tool calls

Example MCP client configuration:

{
  "mcpServers": {
    "owl4agents": {
      "command": "npx",
      "args": ["-y", "owl4agents", "mcp", "--readonly"]
    }
  }
}

Local Workspace Design

The default workspace should be inspectable and reproducible:

~/.owl4agents/
  config.yaml
  workspaces/
    default/
      workspace.yaml
      catalog.json
      ontologies/
        medical/
          source/original.owl
          canonical/ontology.owl
          inferred/
            hermit.owl
            elk.owl
            openllet.owl
            reasoning-report.json
          index/
            entities.jsonl
            labels.jsonl
            hierarchy.jsonl
            class-axioms.jsonl
            properties.jsonl
            property-axioms.jsonl
            individual-assertions.jsonl
            inferred-facts.jsonl
            evidence-paths.jsonl
          snapshots/
          metadata.json
      logs/
        cli-operations.jsonl
        mcp-tool-calls.jsonl

Storage principles:

  • Original files are never overwritten
  • Canonical files, inferred graphs, and indexes are rebuildable
  • Write operations create snapshots
  • Agent writes are audit logged
  • MCP tools must not expose unrestricted file reads

Research Workflow

owl4agents should help researchers compare agent behavior with and without ontology grounding.

For anti-hallucination work, tool results should encourage agents to answer with an explicit verification state:

{
  "answer": "...",
  "claims": [
    {
      "text": "Myocardial infarction is a cardiovascular disease.",
      "status": "supported",
      "evidence": [
        {
          "type": "inferred_axiom",
          "value": "SubClassOf(ex:MyocardialInfarction ex:CardiovascularDisease)",
          "reasoner": "hermit"
        }
      ]
    },
    {
      "text": "The ontology proves every symptom of myocardial infarction.",
      "status": "unknown",
      "explanation": "The ontology has related symptom properties, but it does not contain a complete closure axiom for all symptoms."
    }
  ]
}

This is the practical goal: the agent should not merely receive more context. It should be able to check whether its claims are supported, contradicted, unknown, or outside the ontology scope.

Example experiment dimensions:

  • No ontology context
  • Explicit ontology context only
  • Explicit + inferred ontology context
  • HermiT vs ELK vs Openllet generated context
  • Different context compression strategies
  • Different entity retrieval and ranking methods

Planned context export:

owl4agents context-batch medical ./questions.jsonl \
  --reasoner hermit \
  --out ./contexts.jsonl

Example output:

{
  "questionId": "q001",
  "question": "What symptoms are associated with myocardial infarction?",
  "matchedEntities": [],
  "context": "...",
  "reasoner": "hermit",
  "includeInferred": true
}

Test Corpus

owl4agents uses a layered OWL/RDF test corpus. No single ontology covers all OWL 2 constructs, reasoning behavior, ABox assertions, SPARQL, realistic labels, and agent QA context, so the corpus is split by purpose.

Corpus Layout

test/corpus/
  smoke/
  golden/
  conformance/owl2/
  constructs/
  realworld/
  benchmarks/
  large/
SuitePurposeRun frequency
SmokeSmall public ontologies for import/search/context sanity checksEvery commit
GoldenHand-made deterministic OWL feature tests with expected JSONEvery commit
ConformanceW3C OWL 2 semantics, entailment, consistency, and profile testsSelected subset
ConstructsOWL language construct coverage, including properties and restrictionsSelected subset
RealworldPublic scientific ontology import/search/context testsNightly or release
BenchmarksOWL2Bench, LUBM, and ORE-style performance and scale testsManual or benchmark
LargeGO/HPO/Mondo/Uberon/ChEBI full-size stress testsManual

Included Public Fixtures

The following small smoke fixtures have been downloaded locally:

FilePurpose
test/corpus/smoke/pizza.owlClass hierarchy, object properties, restrictions, equivalent/disjoint classes
test/corpus/smoke/bfo.owlUpper ontology, imports/profile/top-level hierarchy smoke test
test/corpus/benchmarks/lubm/univ-bench.owlUniversity-domain classes, object properties, data properties, benchmark schema
test/corpus/benchmarks/owl2bench/UNIV-BENCH-OWL2DL.owlOWL 2 DL construct-rich TBox for reasoner and axiom coverage
test/corpus/benchmarks/owl2bench/UNIV-BENCH-OWL2EL.owlOWL 2 EL profile TBox for profile and EL reasoner tests
test/corpus/benchmarks/owl2bench/UNIV-BENCH-OWL2QL.owlOWL 2 QL profile TBox for profile tests
test/corpus/benchmarks/owl2bench/UNIV-BENCH-OWL2RL.owlOWL 2 RL profile TBox for profile tests

Golden Ontologies

The most stable acceptance tests should be hand-made golden ontologies. Each file should have a matching .expected.json.

01-subclass-transitive.owl
02-equivalent-classes.owl
03-disjoint-classes-inconsistent.owl
04-unsatisfiable-class.owl
05-object-property-domain-range.owl
06-data-property-domain-range.owl
07-inverse-property.owl
08-transitive-property.owl
09-functional-object-property.owl
10-functional-data-property.owl
11-cardinality-restriction.owl
12-some-values-from.owl
13-all-values-from.owl
14-has-value.owl
15-same-individual.owl
16-different-individuals.owl
17-negative-object-property-assertion.owl
18-negative-data-property-assertion.owl
19-datatype-restriction.owl
20-import-closure.owl

External Corpus Sources

SourceSuggested locationUse
W3C OWL 2 Test Case Repositorytest/corpus/conformance/owl2/Standard OWL 2 conformance, entailment, consistency
OWL2Benchtest/corpus/benchmarks/owl2bench/OWL 2 construct coverage, ABox scale, query performance
LUBMtest/corpus/benchmarks/lubm/ABox assertions, SPARQL, university-domain benchmark
GO basictest/corpus/realworld/go-basic.owlLarge class hierarchy and labels
HPOtest/corpus/realworld/hp.owlPhenotype search and biomedical QA context
OBItest/corpus/realworld/obi.owlScientific investigation workflow context
ORE 2015test/corpus/large/ore/Reasoner benchmark; large/manual
Mondo / Uberon / ChEBItest/corpus/large/Large biomedical stress tests; manual

Use the helper script for supported downloads:

.\scripts\download-test-corpus.ps1 -Suite smoke
.\scripts\download-test-corpus.ps1 -Suite realworld-small
.\scripts\download-test-corpus.ps1 -Suite benchmarks
.\scripts\download-test-corpus.ps1 -Suite all -IncludeLarge

Large downloads are opt-in because some resources are hundreds of MB or more.

Roadmap

The roadmap is organized by user-visible capability. Version numbers start at v0.1 so each milestone can be treated as a publishable project state.

After the v0.1 to v0.3 releases, the roadmap intentionally prioritizes adoption before deeper feature expansion. Reasoning, claim verification, and evidence grounding now exist; the next releases should lower installation and MCP-configuration friction, provide benchmark examples that show the platform's value, and then expand into agent workflows, evaluation, ontology workflow integrations, and controlled write operations. Major feature releases should be followed by a small hardening release when the new surface affects CLI/MCP contracts, launcher behavior, evidence payloads, or acceptance gates.

v0.1 Local Ontology Reader and Readonly MCP

Goal: make a local OWL/RDF ontology inspectable by both CLI and MCP.

Planned support:

  • Java 22 + Gradle multi-module skeleton
  • Integration checks for OWL API, HermiT, Apache Jena ARQ, Picocli, and the MCP-compatible JSON-RPC adapter
  • Local workspace and ontology catalog
  • OWL/RDF import through OWL API
  • Ontology summary: IRI, version IRI, imports, profile, entity counts
  • Entity search by IRI, prefixed name, label, comment, and alias
  • Class context: subclasses, superclasses, equivalent classes, disjoint classes
  • Object property context: domain, range, inverse properties, hierarchy
  • Data property context: domain, range, datatype, hierarchy
  • Individual context: explicit types, labels, comments, basic assertions
  • Readonly SPARQL tools: SELECT, ASK, CONSTRUCT, DESCRIBE
  • SPARQL validation, timeout, graph scope, and result limit controls
  • Basic QA context generation from class/property/individual context
  • CLI commands: init, import, list, summary, search, entity, query, context, mcp
  • Readonly MCP server exposing v0.1 tools
  • Initial npm launcher for local runtime invocation

v0.2 Reasoning and Semantic Expansion

Goal: add mature OWL reasoning and expose inferred semantic structure.

Released support:

  • HermiT consistency checking, classification, and realization
  • ELK adapter for OWL 2 EL classification
  • Openllet adapter for explanation-oriented workflows
  • auto reasoner selection based on OWL profile and requested task
  • Inferred graph and inferred fact result models
  • Reasoning reports with reasoner, profile, timings, warnings, and inferred axiom counts
  • Unsatisfiable class detection
  • Structured entailment checks for supported OWL axiom types
  • Class compatibility checks based on disjointness and satisfiability
  • Individual realization and inferred individual types
  • Relation assertion checks for object properties
  • Data property literal validation against datatype and known constraints
  • Reasoner and v0.1 regression acceptance tests

v0.2.1 Stabilization and Release Hardening

Goal: make v0.2 easier to install, debug, and maintain without expanding the feature surface.

Released support:

  • Review and classify Gradle deprecation warnings; all accepted (shadow plugin + OWL API deprecation + unchecked generics)
  • Improved launcher error messages with deterministic exit codes for missing runtime, missing jar, missing Java
  • --version support in npm launcher reading from package.json
  • Strict npm launcher smoke tests for help, version, runtime discovery, exit code preservation, and MCP startup path
  • Dependency matrix validation: OWL API 5.1.20, HermiT 1.4.5.519, ELK (liveontologies) 0.6.0, Openllet 2.6.5, Jena 5.3.0, Picocli 4.7.7, Gson 2.13.1
  • Release checklist covering build, shadowJar, launcher smoke tests, acceptance report, tag, and push
  • Troubleshooting for Java, JAVA_HOME, missing fat jar, reasoner selection, MCP stdio, and launcher failures
  • v0.1 and v0.2 regression gates remain green

v0.3 Claim Verification and Evidence Grounding

Goal: turn ontology access into anti-hallucination verification tools.

Released support:

  • Structured claim schema for subclass, membership, relation, consistency, property domain/range, and literal validation claims
  • Claim-level verification built on v0.2 entailment, membership, relation, compatibility, literal validation, and scope primitives
  • ontology_verify_claim returning supported, contradicted, unknown, or out_of_scope
  • Evidence path generation for supported claims using source axioms, explicit triples, inferred facts, and reasoner metadata
  • Counterexample search for contradicted claims
  • Unknown explanation for missing entities, missing relations, unsupported profiles, or insufficient axioms
  • Missing entity detection with matched, ambiguous, missing, and out-of-scope classifications
  • Evidence truncation using maxEvidence option
  • CLI commands: verify-claim, evidence, counterexamples, explain-unknown, missing-entities
  • MCP tools: ontology_verify_claim, ontology_get_evidence_path, ontology_find_counterexamples, ontology_explain_unknown, ontology_detect_missing_entities
  • CLI and MCP parity for claim verification results
  • No free-text claim parsing in v0.3; agents must pass structured claims
  • No ontology write operations in v0.3

v0.3.1 Usability and Release Hardening

Goal: let a new GitHub user run owl4agents and connect MCP in minutes.

Released support:

  • One-command local setup for Windows, macOS, and Linux source checkouts (setup --check, setup --init)
  • Launcher flow that can build, locate, or diagnose owl4agents.jar predictably (setup --check validates runtime jar)
  • MCP configuration generator for common local agent clients (mcp-config --client claude/cursor/generic)
  • First-run workspace initialization and smoke test (setup --init, smoke)
  • Example ontology bootstrap using Pizza and the v0.3 claim verification fixture (setup --init imports both)
  • Productized diagnostics for Java version, JAVA_HOME, missing jar, stale workspace state, and MCP stdio issues (setup --check covers all six checks)
  • GitHub Actions CI for build, unit tests, launcher smoke tests, and release-readiness checks
  • GitHub Release assets for runnable jar, checksum, and release notes
  • Public acceptance report template and automated release checklist
  • Keep v0.3.1 free of new OWL feature surface, SHACL, ROBOT integration, and write operations

v0.4 Benchmark Examples and Demo Packs

Goal: make owl4agents easy to understand, demo, and promote through copy-pasteable scenarios before adding deeper product surface.

Released support:

  • examples/ directory with runnable CLI and MCP demos
  • examples/claim-verification showing hallucination checking with supported, contradicted, unknown, and out_of_scope claims
  • examples/pizza-reasoning showing class hierarchy, restrictions, disjointness, and inferred facts
  • examples/agent-mcp showing Claude/Cursor/generic MCP configuration and sanitized tool-call transcript samples
  • examples/biomedical-grounding showing disease hierarchy and claim verification using project-owned golden fixture
  • Each example includes manifest (example.yaml), README, commands, claim JSON or references, expected output assertions, and run scripts
  • README front page links to "Try in 3 minutes" examples and showcase table
  • Demo validation tests (manifest, fixture, drift, sanitization) to keep examples from drifting
  • CI runs v0.4 example validation as a release gate
  • No CLI examples/demo discovery command — examples are script-driven (deferred to future release)
  • No write operations; examples remain reproducible and readonly
  • No large external ontology downloads required for default CI — biomedical fixture is project-owned

v0.5 Agent Claim Workflow

Goal: move from individual tools to repeatable agent workflows for structured claim handoff, verification, and evidence-grounded answers. v0.5 does not extract claims from free text — agents must submit structured claims.

Released support:

  • Batch claim verification for answer-level checking (structured claim input required — v0.5 does not extract claims from free text)
  • Evidence compact context format optimized for LLM consumption with deterministic 4 * maxContextTokens character budget
  • Agent self-check workflow: verify claims, explain unknowns, cite evidence, and refuse out-of-scope claims (claim preparation is manual — agents must submit structured claims)
  • Answer verification reports with per-claim verdicts, aggregate status, and evidence summaries
  • Workflow CLI commands: verify-answer, evidence-context, and review-answer with --policy support
  • Readonly MCP workflow tools: ontology_verify_claims_batch, ontology_build_evidence_context, and ontology_review_answer_claims
  • Public skills/ SOP packs for claim verification, evidence-grounded answering, and ontology scope checks
  • File-level workflow prompt templates; protocol-level MCP prompt listing deferred (absent in current adapter)
  • Regression fixtures for supported, contradicted, unknown, out_of_scope, partially_verified, mixed, optional-claim, malformed, and v0.3-wrapped batches
  • Clear failure modes for malformed claims, unsupported natural-language extraction, and missing ontology scope
  • Natural-language-to-structured-claim handoff schema (deferred — v0.5 requires structured claim input; extraction from free text is future work)

v0.6 Research Evaluation and Benchmarks

Goal: prove and compare the value of ontology grounding with reproducible experiments. Lessons from v0.5: structured claim input works well for deterministic workflows; natural-language claim extraction should be added here as an optional LLM-assisted step, not as a required pipeline stage.

Released support:

  • Experiment configuration parser with YAML input, defaults, and validation (rejects repeatCount, non-boolean hallucinationDetection, invalid edgeCasePolicy)
  • Hand-built benchmark question sets: pizza-50.jsonl, owl2bench-30.jsonl, out-of-scope-cross.jsonl (source: owl4agents, license: Apache-2.0)
  • Benchmark runner with two-tier validation (Tier 1: INVALID_CLAIM_SCHEMA blocks execution; Tier 2: reviewStatus: pending allows execution but excludes metrics), NL-only rejection, per-question timeout
  • QA evaluation with accuracy, false support rate (separate), unresolved rate (separate, NOT combined), verification coverage, and 4×4 expected-vs-actual confusion matrix
  • Context-batch mode: per-question EvidenceContext with character-based truncation metadata (budgetCharsUsed, totalAvailableEvidenceChars, omittedEvidenceCount, omittedClaimCount)
  • Evidence context JSONL export: streamable, independently parseable, truncation metadata present even with zero values
  • Benchmark report generator with Markdown and JSON formats, reasoner comparison (timing delta, agreement/disagreement classification), reproducibility metadata (static REASONER_VERSIONS: hermit 1.4.5.519, elk 0.6.0, openllet 2.6.5)
  • CLI commands: benchmark-run, eval-qa, context-batch, evidence-context --format jsonl
  • Readonly MCP tools: ontology_benchmark_run, ontology_eval_qa, ontology_context_batch, ontology_build_evidence_context format=jsonl
  • NL-to-claim extraction schema document (decomposition rules from NL question types to 14 claim types)
  • Error handling: INVALID_EXPERIMENT_CONFIG, QUESTION_SET_NOT_FOUND, RESULTS_NOT_FOUND, EMPTY_RESULTS, INVALID_QUESTION_SET

Deferred:

  • Natural-language-to-structured-claim extraction (optional, agent-side) — completing the deferred v0.5 handoff item (v0.7 scope)
  • External dataset integration (v0.7 scope)
  • Large-ontology context-batch (v0.7 scope)

v0.7 External Datasets, NL-Claim Extraction, and Ontology Workflow Integrations

Goal: add external dataset support, complete the NL-to-claim extraction pipeline, and evaluate optional ontology workflow integrations.

Planned support:

  • Natural-language-to-structured-claim extraction (optional, agent-side) — completing the deferred v0.5/v0.6 handoff item
  • External dataset integration for large-scale benchmark experiments (GO, HPO, Mondo, Uberon, ChEBI)
  • Large-ontology context-batch with streaming and incremental processing
  • Evaluate optional ROBOT integration for reusable ontology workflow operations and benchmark preprocessing
  • Evaluate SHACL support for explicit constraint validation workflows
  • Property chain inspection and advanced OWL axiom browsing
  • Ontology preprocessing pipeline for imports, subsets, profile checks, and benchmark packs
  • Import closure management and ontology diff planning

v0.8 Controlled Editing, Snapshots, and Audit

Goal: safely allow controlled ontology updates from CLI and MCP after readonly reasoning, verification, examples, and evaluation are stable.

Planned support:

  • Controlled import/export workflows
  • Structured ontology edit operations for classes, properties, individuals, labels, comments, and axioms
  • Add/remove subclass, equivalent class, disjoint class, domain, range, and assertion axioms
  • Snapshot generation before every write
  • Diff between snapshots or ontology versions
  • Rollback to a previous snapshot
  • MCP --allow-write mode with explicit opt-in
  • Dry-run mode for proposed edits
  • Write audit log for CLI operations and MCP tool calls
  • Security tests for readonly mode, write mode, file access limits, dry-run, and rollback behavior

v1.0 Stable Release

Goal: provide a stable local ontology runtime for agent developers and researchers.

Planned support:

  • Stable CLI command surface
  • Stable MCP tool schemas
  • Complete user documentation
  • Complete developer documentation
  • npm launcher package
  • Platform runtime packages
  • Windows, macOS, and Linux support
  • Example datasets and ontologies
  • Paper / experiment reproduction templates
  • Release automation
  • Backward compatibility policy for workspace format and MCP schemas

Long-Term Ideas

  • Optional HTTP API adapter over the same OntologyService
  • Optional Jena TDB2-backed large RDF graph mode
  • Better ontology context compression strategies
  • Entity linking and alias expansion for noisy user questions
  • Reasoning cache invalidation strategy
  • Graph visualization export
  • Integration examples for Claude Desktop, Cursor, and local agent frameworks
  • Domain-specific benchmark packs, such as biomedical, legal, industrial, and research ontologies

Repository Contents

README.md
build.gradle.kts
settings.gradle.kts
gradlew / gradlew.bat
gradle/wrapper/
modules/
  ontology-core/
  ontology-owlapi/
  ontology-query/
  ontology-retrieval/
  ontology-storage/
  ontology-cli/
  ontology-mcp/
  ontology-distribution/
  ontology-validation/
  ontology-benchmark/
tools/
  skills/
    README.md
    _shared/references/   (verdict-policy, claim-batch-schema, evidence-citation-policy, refusal-scope-policy, answer-review-sop)
    owl4agents-claim-verification/SKILL.md
    owl4agents-evidence-grounded-answer/SKILL.md
    owl4agents-ontology-scope-check/SKILL.md
  npm/
    bin/owl4agents.js
    test/launcher.test.js
  bin/
    owl4agents-mcp.cmd
  scripts/
    download-test-corpus.ps1
test/
  corpus/
  contracts/
  fixtures/v0.5/   (batch claim fixtures for v0.5 workflow)
  fixtures/v0.6/   (benchmark configs, question sets, and results fixtures)

Local OpenSpec, design notes, acceptance reports, and temporary retrospectives may exist in this workspace, but they are intentionally ignored by Git for public release workflows.

License

Apache License 2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados