This project is a TypeScript implementation that mirrors a Python RDF stack. It uses the mature RDF/JS ecosystem to enable parsing, signing, validating, and querying RDF data without reinventing plumbing.
- ✅ Debug logging utility (cog:*)
- ✅ LRU cache with TTL and memoization
- ✅ Vocabulary registry with JSON-LD context handling
- ✅ Vocabulary collision resolution
- ✅ Context composition
- ✅ JSON-LD context utilities (with JSON-LD 1.1 support)
- ✅ Entity management
- ✅ RDF graph operations
- ✅ Entity processing
- ✅ Signing and verification (implementation complete, tests passing)
- ✅ SHACL validation (implementation complete, tests passing)
- ✅ Command-line interface for navigation
- ✅ LLM adapter for processing linked data
The following issues were identified during testing and have been fixed:
- ✅ Fixed TypeScript build errors related to JSON-LD property access
- ✅ Fixed null checks in LLM commands to prevent runtime errors
- ✅ Fixed SPARQL queries returning 0 results despite having data loaded
- ✅ Fixed duplicate command output in CLI
- ✅ Fixed ES module compatibility issues
- 🔄 In progress: Fix navigator command returning 0 links
- ⏳ Pending: Fix import extensions (.js) for proper ES module resolution
cogitarelink-ts/
├─ src/
│ ├─ core/
│ │ ├─ debug.ts - Debug logging utility
│ │ ├─ cache.ts - LRU + TTL caching utility
│ │ ├─ context.ts - JSON-LD context utilities
│ │ ├─ entity.ts - Entity representation
│ │ ├─ graph.ts - RDF graph management
│ │ └─ processor.ts - Entity processing
│ ├─ vocab/
│ │ ├─ registry.ts - Vocabulary registry
│ │ ├─ collision.ts - Vocabulary collision resolution
│ │ ├─ composer.ts - Context composition
│ │ └─ ttl-to-context.ts - Convert Turtle to JSON-LD context
│ ├─ verify/
│ │ ├─ signer.ts - RDF data signing and verification
│ │ └─ validator.ts - SHACL validation
│ ├─ cli/
│ │ ├─ index.ts - CLI entry point
│ │ ├─ linked-data-navigator.ts - Navigation commands
│ │ └─ llm-command.ts - LLM-related commands
│ ├─ utils/
│ │ ├─ context-cache.ts - Local caching of contexts
│ │ ├─ uri-helper.ts - URI/CURIE handling utilities
│ │ ├─ graph-helper.ts - Graph utility functions
│ │ └─ llm-adapter.ts - LLM-focused data processing
│ ├─ integration-tests/
│ │ ├─ vocab-processing.test.ts - Real vocabulary testing
│ │ ├─ follow-your-nose.test.ts - Linked data navigation tests
│ │ ├─ rdf-vocabulary-support.test.ts - RDF vocab support tests
│ │ └─ sosa-vocabulary.test.ts - SOSA vocab tests
│ └─ types/
│ ├─ jsonld.d.ts - JSON-LD type definitions
│ ├─ rdf.d.ts - RDF type definitions
│ └─ n3.d.ts - N3 type definitions
├─ bin/
│ └─ cogitare-navigator.js - CLI executable
├─ data/
│ ├─ registry_data.json - Vocabulary registry data
│ ├─ collision_data.json - Vocabulary collision strategies
│ └─ context-cache/ - Local cache for vocabularies
├─ example/
│ ├─ cli-example.js - CLI usage example
│ ├─ llm-adapter-demo.js - LLM adapter example
│ ├─ navigation-demo.js - Navigation API example
│ └─ navigation-example.jsonld - Example navigation data
├─ scripts/
│ └─ prepare-context-cache.ts - Cache preparation script
├─ CLAUDE.md - Instructions for Claude Code
├─ TESTING_GUIDE.md - Guide for testing the project
└─ test files and configuration
- Node.js (v18 or later for Web Crypto API support)
- npm
-
Clone the repository
git clone https://github.com/LA3D/cogitarelink-ts.git cd cogitarelink-ts -
Install dependencies
npm install
This project includes several demos:
# Core functionality demo
npm run dev
# Navigation demo
npm run demo:navigate
# LLM adapter demo
npm run demo:llm
For debug logging, add the DEBUG environment variable:
DEBUG=cog:* npm run dev
The project includes a command-line interface for linked data navigation:
# Run the CLI
npm run navigate -- --help
# Load a JSON-LD file
npm run navigate -- load example/navigation-example.jsonld
# List available commands
npm run navigate -- help
This project uses Vitest for testing. There are two categories of tests:
Run standard unit tests with:
npm test
For watching mode:
npm run test:watch
Integration tests perform "follow your nose" linked data operations with real-world vocabularies:
npm run test:integration
These tests actually attempt to fetch and process real vocabularies from their published URLs, demonstrating our ability to navigate through linked data relationships.
Run both unit and integration tests with:
npm run test:all
For more reliable integration testing, especially in CI/CD environments or with limited connectivity, you can prepare a local context cache:
npm run prepare-cache
This downloads all vocabulary contexts defined in the registry and caches them locally.
Each component has its own test file:
src/core/*.test.ts- Core component testssrc/vocab/*.test.ts- Vocabulary management testssrc/verify/*.test.ts- Signing and validation testssrc/integration-tests/vocab-processing.test.ts- Real vocabulary fetching and processingsrc/integration-tests/follow-your-nose.test.ts- Linked data navigationsrc/integration-tests/rdf-vocabulary-support.test.ts- RDF vocabulary supportsrc/integration-tests/sosa-vocabulary.test.ts- SOSA vocabulary tests
For testing with real-world vocabularies, use:
npm run test:real
This runs special test scripts that process Schema.org and other vocabularies, creating entities with proper contexts and running SPARQL queries to validate linked data navigation.
- Debug Utility: Provides namespaced logging for debugging.
- Cache Utility: Implements an LRU cache with TTL for function memoization.
- Context: Utilities for working with JSON-LD contexts.
- Entity: Represents a JSON-LD entity with vocabulary context.
- Graph Manager: Manages an RDF dataset and provides SPARQL query capabilities.
- Entity Processor: Processes and manages entities, with tracking of vocabulary usage.
- Registry: Manages vocabulary entries with their metadata.
- Collision Resolution: Handles conflicts between vocabularies.
- Context Composer: Composes contexts from multiple vocabularies.
- TTL to Context: Converts Turtle RDF to JSON-LD contexts.
- Signer: Signs and verifies RDF data using Ed25519 signatures.
- Validator: Validates RDF data against SHACL shapes.
- Navigator: Command-line interface for navigating linked data.
- LLM Commands: Special commands for processing data for LLMs.
- URI Helper: Utilities for handling URIs, CURIEs, and namespaces.
- Graph Helper: Helper functions for working with RDF graphs.
- LLM Adapter: Specialized tools for adapting linked data for LLM consumption.
This project was built incrementally, following a Jeremy Howard-style exploratory approach:
- Set up the basic project structure
- Implement core utilities first (debug, cache)
- Build vocabulary management layer
- Create context and entity handling
- Implement graph management
- Add entity processing
- Integrate verification components
- Add CLI for linked data navigation
- Implement LLM adapter utilities
Each step includes tests to ensure components work as expected.
The project includes several utilities designed specifically for working with LLMs:
- Entity Chunking: Break large entities into smaller chunks for LLM processing
- Graph Summarization: Create compact representations of graphs for LLM context windows
- Vocabulary Summarization: Extract key terms and definitions from vocabularies
- Subgraph Extraction: Focus on relevant portions of a knowledge graph
- RDF Streaming: Process large datasets incrementally
- Triple Formatting: Convert RDF to LLM-friendly formats
- Complete the navigation command functionality to return proper links
- Implement RDF/XML → context derivation
- Add protected-term heuristic inside collision resolver
- Develop advanced query/partition helpers for complex data
- Create comprehensive documentation and tutorials
- Implement performance optimizations for large datasets
- Add support for more RDF serialization formats
ISC License