TESTING_GUIDE.md

Testing Guide for Cogitare Link TS

This document provides guidance on how to test the Cogitare Link TypeScript implementation, including the linked data navigation CLI and LLM adapter utilities.

Documentation Reading Order

For a complete understanding of the project and its testing approach, read these documentation files in the following order:

1. README.md - Overview of the project architecture and components
2. CLAUDE.md - Project-specific instructions for Claude Code
3. LINKED_DATA_CLI.md - Testing instructions for the linked data navigation CLI
4. LLM_ADAPTER_GUIDE.md - Guide for using the LLM adapter utilities
5. DEVELOPER_GUIDE.md - Detailed information for developers extending the CLI

Build and Setup

Before testing, prepare your environment:

# Install dependencies
npm install

# Build the project
npm run build

Testing the Navigation CLI

Follow these steps to test the linked data navigation CLI:

1. Start with the basic vocabulary exploration:

# List available vocabularies
npm run navigate -- vocabs

# Explore a specific vocabulary
npm run navigate -- explore schema

2. Create and load a sample dataset:

# Create a mock dataset
npm run navigate -- create-mock --output test-dataset.jsonld

# Load the example dataset
npm run navigate -- load example/navigation-example.jsonld --vocab schema,dc,foaf,dcat

3. Navigate through the linked data:

# Navigate from a specific entity
npm run navigate -- navigate https://example.org/datasets/ldnb

# Run a SPARQL query
npm run navigate -- query "SELECT ?name WHERE { ?person a <https://schema.org/Person> ; <https://schema.org/name> ?name . }" --vocab schema

4. Run the interactive demo for a guided experience:

npm run demo:navigate

Testing the LLM Adapter Utilities

Follow these steps to test the LLM adapter utilities:

1. Create and load a sample dataset (if not already done):

npm run navigate -- create-mock --output test-dataset.jsonld
npm run navigate -- load test-dataset.jsonld --vocab schema,dc,foaf,dcat

2. Test the graph summarization for LLMs:

npm run navigate -- llm-summarize

3. Test vocabulary summarization for LLMs:

npm run navigate -- llm-vocab schema --max-terms 10

4. Extract a focused subgraph:

# First, find a dataset URI from your graph
npm run navigate -- query "SELECT ?dataset WHERE { ?dataset a <https://schema.org/Dataset> } LIMIT 1" --vocab schema

# Then extract a subgraph using that URI
npm run navigate -- llm-extract <DATASET_URI> --depth 2 --format turtle

5. Run the LLM adapter demo for a guided experience:

npm run demo:llm

Testing with Claude Code

To test with Claude Code, follow these steps:

1. Start a new Claude Code session to ensure a clean environment

2. Use these prompts in order:

   a. Understanding the project:

   I have a TypeScript project called cogitarelink-ts for linked data processing. It has a CLI for linked data navigation and utilities for LLM adaptation. Please help me understand its structure and capabilities.
   

   b. Testing the navigation CLI:

   Let's test the linked data navigation CLI. Please run the following commands:
   1. Build the project with `npm run build`
   2. List available vocabularies with `npm run navigate -- vocabs`
   3. Explore the schema.org vocabulary with `npm run navigate -- explore schema`
   

   c. Testing with sample data:

   Now, let's test with sample data:
   1. Create a mock dataset with `npm run navigate -- create-mock --output test-dataset.jsonld`
   2. Load the example dataset with `npm run navigate -- load example/navigation-example.jsonld --vocab schema,dc,foaf,dcat`
   3. Run a SPARQL query to find all persons in the dataset
   

   d. Testing the LLM adapter utilities:

   Let's test the LLM adapter utilities:
   1. Create a graph summary with `npm run navigate -- llm-summarize`
   2. Get a vocabulary summary with `npm run navigate -- llm-vocab schema --max-terms 10`
   3. Extract a subgraph from one of the dataset entities in the graph
   

3. For interactive demos, you may want to run these locally (Claude Code's interactive capabilities are limited):

   npm run demo:navigate
   npm run demo:llm

Expected Results

You should see:

1. Navigation CLI:

   • Vocabulary listings with prefixes and URIs
   • Detailed vocabulary information when exploring
   • Entity links and properties when navigating
   • SPARQL query results in tabular format

2. LLM Adapter:

   • Graph summaries with statistics and key nodes
   • Vocabulary summaries with important terms
   • Focused subgraphs in concise or Turtle format

Troubleshooting

If you encounter issues:

1. Ensure the project is built with npm run build
2. Check that all dependencies are installed correctly
3. Verify file paths in the commands match your environment
4. Look for error messages in the console output

Extending the Tests

To thoroughly test the system:

1. Create your own JSON-LD files with complex linked data
2. Write SPARQL queries that navigate through multiple links
3. Test with larger datasets to verify LLM adaptation capabilities
4. Create custom CLI commands using the developer guide