\nCover Material, Copyright, and License

This eBook will be updated occasionally so please check the leanpub.com web page for this book periodically for updates.

Please visit the author’s website.

",{"_303":304,"_38":39,"_42":43,"_40":41,"_61":62,"_305":306,"_367":301},"previewContent","

\n Cover Material, Copyright, and License\n
\n Preface\n
- \n Requests from the Author\n
- \n Clojure, With Some Java and Python\n
- \n Personal Artificial Intelligence Journey: or, Life as a Lisp Developer\n
- \n Acknowledgements\n
\n
\n Deep Learning Using Deeplearning4j\n
- \n Feed Forward Classification Networks\n
- \n Optional Material: Documentation for Other Types of DeepLearning4J Built-in Layers\n
- \n Deep Learning Wrap Up\n
\n
\n Natural Language Processing Using OpenNLP\n
- \n Using the Clojure and Java Wrappers for OpenNLP\n
\n
\n Anomaly Detection Machine Learning Example\n
- \n Motivation for Anomaly Detection\n
- \n Math Primer for Anomaly Detection\n
- \n AnomalyDetection Utility Class Written in Java\n
- \n Clojure Experiment for the University of Wisconsin Cancer Data Using Java Anomaly Detection Code\n
\n
\n Web Scraping\n
- \n Web Scraping Using the jsoup Library\n
\n
\n Using the Brave Search APIs\n
- \n Setting an Environment Variable for the Access Key for Brave Search APIs\n
- \n Using the Brave Search API\n
- \n Wrap-up\n
\n
\n Background Material for the Semantic Web and Knowledge Graphs\n
- \n Learning Plan\n
- \n Available Tools\n
- \n RDF: The Universal Data Format\n
- \n Extending RDF with RDF Schema\n
- \n The SPARQL Query Language\n
- \n OWL: The Web Ontology Language\n
- \n Semantic Web Wrap-up\n
\n
\n Clojure Wrapper for the Jena RDF and SPARQL Library\n
\n Simple RDF Datastore and Partial SPARQL Query Processor\n
- \n Implementing a Simple RDF Datastore\n
- \n Querying the RDF Datastore\n
- \n Implementing a Partial SPARQL Query Processor\n
- \n Putting It All Together: Running Example Queries\n
- \n Summary\n
\n
\n Knowledge Graph Navigator\n
- \n Entity Types Handled by KGN\n
- \n KGN Implementation\n
\n
\n Using the OpenAI APIs\n
\n Using the Google Gemini 2.5 Flash APIs\n
- \n Test Code for REST Interface and Sample Test Output\n
- \n Gemini API Library Implementation for REST Interface\n
- \n (New) Gemini Client Library Using Google’s Java SDK for Gemini\n
- \n Gemini APIs Wrap Up\n
\n
\n Question Answering Using OpenAI APIs and a Local Embeddings Vector Database\n
\n
\n Running LLMs Locally Using Ollama\n
- \n Running the Example Tests\n
- \n Clojure Client Library for the Ollama Service REST APIs\n
\n
\n Using Moonshot’s Kimi K2 Model with Built In $web_search Tool Support\n
\n
\n Conclusions\n

\nCover Material, Copyright, and License

\n\n

This eBook will be updated occasionally so please check the leanpub.com web page for this book periodically for updates.

\n\n

Please visit the author’s website.

\n\n

\nPreface

\n\n

I have been developing commercial Artificial Intelligence (AI) tools and applications since the 1980s and I usually use the Lisp languages Common Lisp, Clojure, Racket Scheme, and Gambit Scheme. The exception to my Lisp language preferences is that I use Python for my deep learning work. This book contains code that I wrote for myself and I am wrapping it in a book in the hopes that my code and this book will also be useful to you, dear reader.

\n\n

If you read my eBooks free online then please consider tipping me https://markwatson.com/#tip.

\n\n

The latest update to this book (May 2023) features more OpenAI API examples using Large Language Models (LLMs) and local document search using local text embedding data stores. I removed the chapter on Clojure/Python interoperation because of reported difficulties in configuring a Linux system to get the examples working. I copied the entire text for this deleted chapter to the README file https://github.com/mark-watson/Clojure-AI-Book-Code/nlp_libpython if you would like to use this material.

\n\n\n

\n\n\n

I wrote this book for both professional programmers and home hobbyists who already know how to program in Clojure and who want to learn practical AI programming and information processing techniques. I have tried to make this an enjoyable book to work through. In the style of a “cook book,” the chapters can be studied in any order.

\n\n

This book uses two of the examples in my Java AI book that is also available to read free online or for purchase at Leanpub.com. I replicate these two bits of Java code in the GitHub repository:

\n\n

https://github.com/mark-watson/Clojure-AI-Book-Code

\n\n

Git pull requests with code improvements will be appreciated by me and the readers of this book.

\n\n

\nRequests from the Author

\n\n

This book will always be available to read free online at https://leanpub.com/clojureai/read.

\n\n

That said, I appreciate it when readers purchase my books because the income enables me to spend more time writing.

\n\n

\nHire the Author as a Consultant

\n\n

I am available for short consulting projects. Please see https://markwatson.com.

\n\n

\nClojure, With Some Java and Python

\n\n

I like Common Lisp slightly more than Clojure, even though Clojure is a beautifully designed modern language and Common Lisp is ancient and has defects. Then why do I use Clojure? The Java ecosystem is huge and Clojure takes full advantage of Java interoperability, its elegant collections data types, and inline JSON literals. Just as I sometimes need access to the rich Java ecosystem I also need Python libraries for some of my projects. Here we will use the libpython-clj library for that. I also like the language Hy that has a Clojure-like syntax and wraps the Python language. If you use Python then my book A Lisp Programmer Living in Python-Land: The Hy Programming Language might be of interest.

\n\n

Using the Java ecosystem is an important aspect of Clojure development and in the few cases where I use Java libraries from my Java AI book, my Clojure examples illustrate how to convert Clojure seq data to Java arrays, handle returned Java data values, etc.

\n\n

\nPersonal Artificial Intelligence Journey: or, Life as a Lisp Developer

\n\n

I have been interested in AI since reading Bertram Raphael’s excellent book Thinking Computer: Mind Inside Matter in the early 1980s. I have also had the good fortune to work on many interesting AI projects including the development of commercial expert system tools for the Xerox LISP machines and the Apple Macintosh, development of commercial neural network tools, application of natural language and expert systems technology, medical information systems, application of AI technologies to Nintendo and PC video games, and the application of AI technologies to the financial markets. I have also applied statistical natural language processing techniques to analyzing social media data from Twitter and Facebook. I worked at Google on their Knowledge Graph and I managed a deep learning team at Capital One where I was awarded 55 US patents. In recent years most of my work has been centered around creating deep learning models for specific applications and the use of Large Language Models for Natural Language Processing (NLP) and extracting semantic information from text.

\n\n

I enjoy AI programming, and hopefully this enthusiasm will also infect you, dear reader.

\n\n

\nAcknowledgements

\n\n

I produced the manuscript for this book using the leanpub.com publishing system and I recommend leanpub.com to other authors.

\n\n

Editor: Carol Watson

\n\n

Thanks to Alex Ott who rewrote a few of the example programs with a better Clojure style.

\n\n

Thanks to the following people who found typos in this and earlier book editions: Roger Erens

\n\n\n

\nDeep Learning Using Deeplearning4j

\n\n

In the last ten years Deep Learning has been so successful for solving difficult problems in areas like image understanding and natural language processing (NLP) that many people now equate Deep Learning with AI. While I think this is a false equivalence, I have often used both plain old-fashioned neural networks and Deep Learning models in my work. In this chapter we implement a fairly simple feed forward using the general purpose Deeplearning4j (DL4J) library. I implement neural networks “from scratch” in Java and Common Lisp in other books that you can read free online at https://leanpub.com/u/markwatson.

\n\n

One limitation of conventional back propagation neural networks is that they are limited to the number of neuron layers that can be efficiently trained (the vanishing gradients problem).

\n\n

Deep learning uses computational improvements to mitigate the vanishing gradient problem like using ReLu activation functions rather than the more traditional Sigmoid function, and networks called “skip connections” where some layers are initially turned off with connections skipping to the next active layer.

\n\n

Modern deep learning frameworks like DeepLearning4j, TensorFlow, and PyTorch are easy to use and efficient. We use DeepLearning4j in this chapter because it is written in Java and easy to use with Clojure. In a later chapter we will use the Clojure library libpython-clj to access other deep learning-based tools like the Hugging Face Transformer models for question answering systems as well as the spaCy Python library for NLP.

\n\n

I have used GAN (generative adversarial networks) models for synthesizing numeric spreadsheet data, LSTM (long short term memory) models to synthesize highly structured text data like nested JSON, and for NLP (natural language processing). Several of my 55 US patents use neural network and Deep Learning technology.

\n\n

The Deeplearning4j.org Java library supports many neural network algorithms. We will look at one simple example so you will feel comfortable integrating Deeplearning4j with your Clojure projects, and a later optional-reading section details other available types of models. Note that I will often refer to Deeplearning4j as DL4J.

\n\n

We start with a simple example of a feed forward network using the same University of Wisconsin cancer database that we will also use later in the chapter on anomaly detection.

\n\n

There is a separate repository of DL4J examples that you might want to look at since any of these Java examples that look useful for your projects can be used in Clojure using the example here to get started.

\n\n

\nFeed Forward Classification Networks

\n\n

Feed forward classification networks are a type of deep neural network that can contain multiple hidden neuron layers. In the example here the adjacent layers are fully connected (all neurons in adjacent layers are connected). The DL4J library is written to scale to large problems and to use GPUs if you have them available.

\n\n

In general, simpler network architectures that can solve a problem are better than unnecessarily complicated architectures. You can start with simple architectures and add layers, different layer types, and parallel models as needed. For feed forward networks model complexity has two dimensions: the numbers of neurons in hidden layers, and the number of hidden layers. If you put too many neurons in hidden layers then the training data is effectively memorized and this will hurt performance on data samples not used in training (referred to as out of sample data). In practice, I “starve the network” by reducing the number of hidden neurons until the model has reduced accuracy on independent test data. Then I slightly increase the number of neurons in hidden layers. This technique helps avoid models simply memorizing training data (the over fitting problem).

\n\n

Our example here reads the University of Wisconsin cancer training and testing data sets (lines 37-53), creates a model (lines 53-79), trains it (line 81) and tests it (lines 82-94).

\n\n

You can increase the number of hidden units per layer in line 23 (something that you might do for more complex problems). To add a hidden layer you can repeat lines 68-75 (and incrementing the layer index from 1 to 2). Note that in this example, we are mostly working with Java data types, not Clojure types. In a later chapter that uses the Jena RDF/SPARQL library, we convert Java values to Clojure values.

\n\n

 1 (ns deeplearning-dl4j-clj.wisconsin-data\n 2   (:import [org.datavec.api.split FileSplit]\n 3            [org.deeplearning4j.datasets.datavec \n 4             RecordReaderDataSetIterator]\n 5            [org.datavec.api.records.reader.impl.csv\n 6             CSVRecordReader]\n 7            [org.deeplearning4j.nn.conf\n 8             NeuralNetConfiguration$Builder]\n 9            [org.deeplearning4j.nn.conf.layers\n10             OutputLayer$Builder DenseLayer$Builder]\n11            [org.deeplearning4j.nn.weights WeightInit]\n12            [org.nd4j.linalg.activations Activation]\n13            [org.nd4j.linalg.lossfunctions\n14             LossFunctions$LossFunction]\n15            [org.deeplearning4j.optimize.listeners\n16             ScoreIterationListener]\n17            [org.deeplearning4j.nn.multilayer\n18             MultiLayerNetwork]\n19            [java.io File]\n20            [org.nd4j.linalg.learning.config Adam Sgd\n21             AdaDelta AdaGrad AdaMax Nadam NoOp]))\n22 \n23 (def numHidden 3)\n24 (def numOutputs 1)\n25 (def batchSize 64)\n26 \n27 (def initial-seed (long 33117))\n28 \n29 (def numInputs 9)\n30 (def labelIndex 9)\n31 (def numClasses 2)\n32 \n33 \n34 (defn -main\n35   \"Using DL4J with Wisconsin data\"\n36   [& args]\n37   (let [recordReader (new CSVRecordReader)\n38         _ (. recordReader\n39             initialize\n40             (new FileSplit\n41              (new File \"data/\", \"training.csv\")))\n42         trainIter\n43         (new RecordReaderDataSetIterator\n44           recordReader batchSize labelIndex numClasses)\n45         recordReaderTest (new CSVRecordReader)\n46         _ (. recordReaderTest\n47             initialize\n48              (new FileSplit\n49               (new File \"data/\", \"testing.csv\")))\n50         testIter\n51         (new RecordReaderDataSetIterator\n52            recordReaderTest batchSize labelIndex\n53            numClasses)\n54         conf (->\n55                (new NeuralNetConfiguration$Builder)\n56                (.seed initial-seed)\n57                (.activation Activation/TANH)\n58                (.weightInit (WeightInit/XAVIER))\n59                (.updater (new Sgd 0.1))\n60                (.l2 1e-4)\n61                (.list)\n62                (.layer\n63                  0,\n64                  (-> (new DenseLayer$Builder)\n65                      (.nIn numInputs)\n66                      (.nOut numHidden)\n67                      (.build)))\n68                (.layer\n69                  1,\n70                  (-> (new OutputLayer$Builder\n71                        LossFunctions$LossFunction/MCXENT)\n72                      (.nIn numHidden)\n73                      (.nOut numClasses)\n74                      (.activation Activation/SOFTMAX)\n75                      (.build)))\n76                (.build))\n77         model (new MultiLayerNetwork conf)\n78         score-listener (ScoreIterationListener. 100)]\n79     (. model init)\n80     (. model setListeners (list score-listener))\n81     (. model fit trainIter 10)\n82     (while (. testIter hasNext)\n83       (let [ds (. testIter next)\n84             features (. ds getFeatures)\n85             labels (. ds getLabels)\n86             predicted (. model output features false)]\n87         ;; 26 test samples in data/testing.csv:\n88         (doseq [i (range 0 52 2)]\n89           (println\n90             \"desired output: [\" (. labels getDouble i)\n91             (. labels getDouble (+ i 1)) \"]\"\n92             \"predicted output: [\"\n93             (. predicted getDouble i)\n94             (. predicted getDouble (+ i 1)) \"]\"))))))\n

\n\n\n\n

Notice that we have separate training and testing data sets. It is very important to not use training data for testing because performance on recognizing training data should always be good assuming that you have enough memory capacity in a network (i.e., enough hidden units and enough neurons in each hidden layer).

\n\n

The following program output shows the target (correct output) and the output predicted by the trained model:

\n\n

target: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.39 0.61 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.91 0.09 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.96 0.04 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.95 0.05 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.95 0.05 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.21 0.79 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.94 0.06 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.92 0.08 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.94 0.06 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.96 0.04 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.17 0.83 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.17 0.83 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 0.0 1.0 ] predicted : [ 0.16 0.84 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.95 0.05 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.94 0.06 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.92 0.08 ]\ntarget: [ 1.0 0.0 ] predicted : [ 0.96 0.04 ]\n

\n\n\n\n

This is a simple example but is hopefully sufficient to get you started if you want to use DL4J in your Clojure projects. An alternative approach would be writing your model code in Java and embedding the Java code in your Clojure projects - we will see examples of this in later chapters.

\n\n

\nOptional Material: Documentation for Other Types of DeepLearning4J Built-in Layers

\n\n

The documentation for the built-in layer classes in DL4J is probably more than you need for now so let’s review the most other types of layers that I sometimes use. In the simple example we used in the last section we used two types of layers:

\n\n

\norg.deeplearning4j.nn.conf.layers.DenseLayer - maintains connections to all neurons in the previous and next layer, or it is “fully connected.”
\norg.deeplearning4j.nn.conf.layers.OutputLayer - has built-in behavior for starting the back propagation calculations back through previous layers.

\n\n

As you build more deep learning enabled applications, depending on what requirements you have, you will likely need to use at least some of the following Dl4J layer classes:

\n\n

\norg.deeplearning4j.nn.conf.layers.AutoEncoder - often used to remove noise from data. Autoencoders work by making the target training output values equal to the input training values while reducing the number of neurons in the AutoEncoding layer. The layer learns a concise representation of data, or “generalizes” data by learning which features are important.
\norg.deeplearning4j.nn.conf.layers.CapsuleLayer - Capsule networks are an attempt to be more efficient versions of convolutional models. Convolutional networks discard position information of detected features while capsule models maintain and use this information.
\norg.deeplearning4j.nn.conf.layers.Convolution1D - one-dimensional convolutional layers learn one-dimensional feature detectors. Trained layers learn to recognize features but discard the information of where the feature is located. These are often used for data input streams like signal data and word tokens in natural language processing.
\norg.deeplearning4j.nn.conf.layers.Convolution2D - two-dimensional convolutional layers learn two-dimensional feature detectors. Trained layers learn to recognize features but discard the information of where the feature is located. These are often used for recognizing if a type of object appears inside a picture. Note that features, for example, representing a nose or a mouth, are recognized but their location in an input picture does not matter. For example, you could cut up an image of someone’s face, moving the ears to the picture center, the mouth to the upper left corner, etc., and the picture would still be predicted to contain a face with some probability because using soft max output layers produces class labels that can be interpreted as probabilities since the values over all output classes sum to the value 1.
\norg.deeplearning4j.nn.conf.layers.EmbeddingLayer - embedding layers are used to transform input data into integer data. My most frequent use of embedding layers is word embedding where each word in training data is assigned an integer value. This data can be “one hot encoded” and in the case of processing words, if there are 5000 unique words in the training data for a classifier, then the embedding layer would have 5001 neurons, one for each word and one to represent all words not in the training data. If the word index (indexing is zero-based) is, for example 117, then the activation value for neuron at index 117 is set to one and all others in the layer are set to zero.
\norg.deeplearning4j.nn.conf.layers.FeedForwardLayer - this is a super class for most specialized types of feed forward layers so reading through the class reference is recommended.
\norg.deeplearning4j.nn.conf.layers.DropoutLayer - dropout layers are very useful for preventing learning new input patterns from making the network forget previously learned patterns. For each training batch, some fraction of neurons in a dropout layer are turned off and don’t update their weights during a training batch cycle. The development of using dropout was key historically for getting deep learning networks to work with many layers and large amounts of training data.
\norg.deeplearning4j.nn.conf.layers.LSTM - LSTM layers are used to extend the temporal memory of what a layer can remember. LSTM are a refinement of RNN models that use an input window to pass through a data stream and the RNN model can only use what is inside this temporal sampling window.
\norg.deeplearning4j.nn.conf.layers.Pooling1D - a one-dimensional pooling layer transforms a longer input to a shorter output by downsampling, i.e., there are fewer output connections than input connections.
\norg.deeplearning4j.nn.conf.layers.Pooling2D - a two-dimensional pooling layer transforms a larger two-dimensional array of data input to a smaller output two-dimensional array by downsampling.

\n\n

\nDeep Learning Wrap Up

\n\n

I first used neural networks in the late 1980s for phoneme (speech) recognition, specifically using time delay neural networks and I gave a talk about it at IEEE First Annual International Conference on Neural Networks San Diego, California June 21-24, 1987. In the following year I wrote the Backpropagation neural network code that my company used in a bomb detector that we built for the FAA. Back then, neural networks were not widely accepted but in the present time Google, Microsoft, and many other companies are using deep learning for a wide range of practical problems. Exciting work is also being done in the field of natural language processing.

\n\n

Later we will look at an example calling directly out to Python code using the libpython-clj library to use the spaCy natural language processing library. You can also use the libpython-clj library to access libraries like TensorFlow, PyTorch, etc. in your Clojure applications.

\n\n\n

\nNatural Language Processing Using OpenNLP

\n\n

Here we use the Apache OpenNLP project written in Java. OpenNLP has pre-trained models for tokenization, sentence segmentation, part-of-speech tagging, named entity extraction, chunking, parsing, and coreference resolution. Here we use a subset of OpenNLP’s functionality. My Java AI book has a more complete treatment, including building custom classification models and performing chunk-parsing of sentence structure.

\n\n

Currently, OpenNLP has support for Danish, German, English, Spanish, Portuguese, and Swedish. I include in the github repository pre-trained models for English in the directory models.

\n\n

\nUsing the Clojure and Java Wrappers for OpenNLP

\n\n

I won’t list the simple Java wrapper code in the directory src-java here. You might want to open the files NLP.java and Pair.java for reference:

\n\n

src-java\n└── main\n    ├── java\n    │   └── com\n    │       └── markwatson\n    │           └── opennlp\n    │               ├── NLP.java\n    │               └── Pair.java\n    └── resources\n        └── log4j.xml\n

\n\n\n\n

The project.clj file shows the setup for incorporating Java code into a Clojure project:

\n\n

(defproject opennlp-clj \"0.1.0-SNAPSHOT\"\n  :description \"Example using OpenNLP with Clojure\"\n  :url \"http://markwatson.com\"\n  :license\n  {:name\n   \"EPL-2.0 OR GPL-2+ WITH Classpath-exception-2.0\"\n   :url \"https://www.eclipse.org/legal/epl-2.0/\"}\n  :source-paths      [\"src\"]\n  :java-source-paths [\"src-java\"]\n  :javac-options     [\"-target\" \"1.8\" \"-source\" \"1.8\"]\n\n  :dependencies [[org.clojure/clojure \"1.10.1\"]\n                 ;from my Java AI book:\n                 ;[com.markwatson/opennlp \"1.0-SNAPSHOT\"]\n                 [opennlp/tools \"1.5.0\"]]\n  :repl-options {:init-ns opennlp-clj.core})\n

\n\n\n\n

Note the use of :java-source-paths to specify where the Java codes are stored in the project. When you use lein run to try the example, both the Java and Clojure code are compiled. When I first wrote this example, I used the maven output target for the OpenNLP example in my Java AI book. I left the dependency in this project.clj file commented out and instead added the two Java source files to this project. Copying the code into this project should make it easier for you to run this example.

\n\n

In the following listing, notice that I have two versions of tokenization functions:tokenize->java returns Java data structures andtokenize->seq returns a Clojure seq. The other example wrapper functions take a Java array of tokens as an argument.

\n\n

 1 (ns opennlp-clj.core\n 2   (:import (com.markwatson.opennlp NLP)))\n 3 \n 4 (defn sentence-splitter\n 5   \"tokenize entire sentences\"\n 6   [string-input]\n 7   (seq (NLP/sentenceSplitter string-input)))\n 8 \n 9 (defn tokenize->seq\n10   \"tokenize words to Clojure seq\"\n11   [string-input]\n12   (seq (NLP/tokenize string-input)))\n13 \n14 (defn tokenize->java\n15   \"tokenize words to Java array\"\n16   [string-input]\n17   (NLP/tokenize string-input))\n18 \n19 ;; Word analysis:\n20 \n21 (defn POS\n22   \"part of speech\"\n23   [java-token-array]\n24   (seq (NLP/POS java-token-array)))\n25 \n26 ;; Entities:\n27 \n28 (defn company-names\n29   [java-token-array]\n30   (seq (NLP/companyNames java-token-array)))\n31 \n32 (defn location-names\n33   [java-token-array]\n34   (seq (NLP/locationNames java-token-array)))\n35 \n36 (defn person-names\n37   [java-token-array]\n38   (seq (NLP/personNames java-token-array)))\n

\n\n\n\n

Here I tokenize text into a Java array that is used to call the Java OpenNLP code (in the directory src-java). The first operation that you will usually start with for processing natural language text is breaking input text into individual words and sentences.

\n\n

The test code for this project shows how to use these APIs:

\n\n

 1 (ns opennlp-clj.core-test\n 2   (:require [clojure.test :as test])\n 3   (:require [opennlp-clj.core :as onlp]))\n 4 \n 5 (def\n 6   test-text\n 7   \"The cat chased the mouse around the tree while Mary Smith (who works at IBM in Sa\\\n 8 n Francisco) watched.\")\n 9 \n10 (test/deftest pos-test\n11   (test/testing \"parts of speech\"\n12     (let [token-java-array (onlp/tokenize->java test-text)\n13           token-clojure-seq (onlp/tokenize->seq test-text)\n14           words-pos (onlp/POS token-java-array)\n15           companies (onlp/company-names token-java-array)\n16           places (onlp/location-names token-java-array)\n17           people (onlp/person-names token-java-array)]\n18       (println \"Input text:\\n\" test-text)\n19       (println \"Tokens as Java array:\\n\" token-java-array)\n20       (println \"Tokens as Clojure seq:\\n\"\n21                token-clojure-seq)\n22       (println \"Part of speech tokens:\\n\" words-pos)\n23       (println \"Companies:\\n\" companies)\n24       (println \"Places:\\n\" places)\n25       (println \"People:\\n\" people)\n26       (test/is (= (first words-pos) \"DT\")))))\n

\n\n\n\n

Here is the test output:

\n\n

Input text:\nThe cat chased the mouse around the tree while Mary Smith (who works at IBM in San F\\\nrancisco) watched.\nTokens as Java array:\n #object[[Ljava.lang.String; 0x2f04105 [Ljava.lang.String;@2f04105]\nTokens as Clojure seq:\n (The cat chased the mouse around the tree while Mary Smith ( who works at IBM in Sa\\\nn Francisco ) watched .)\nPart of speech tokens:\n (DT NN VBD DT NN IN DT NN IN NNP NNP -LRB- WP VBZ IN NNP IN NNP NNP -RRB- VBD .)\nCompanies:\n (IBM)\nPlaces:\n (San Francisco)\nPeople:\n (Mary Smith)\n

\n\n\n\n

The part of speech tokens like DT (determiner), NN (noun), etc. are defined in the README file for this project.

\n\n

Note: My Java AI book covers OpenNLP in more depth, including how to train your own classification models.

\n\n

We take a different approach to NLP in the next chapter: using the libpython-clj library to call Python NLP libraries and pre-trained deep learning models. The Python models have more functionality but the OpenNLP library is much easier to setup and use with Clojure.

\n\n\n

\nAnomaly Detection Machine Learning Example

\n\n

Anomaly detection models are used in one very specific class of use cases: when you have many negative (non-anomaly) examples and relatively few positive (anomaly) examples. We can refer to this as an unbalanced training set. To try an experiment with anomaly detection we can reuse the Wisconsin data. For training we will ignore positive examples in the original data, create a model of “how things should be,” and hopefully be able to detect anomalies different from the original negative (non-malignant) examples (i.e., data samples indicating cancer malignancy).

\n\n

Anomaly detection is a difficult problem. The simple approach we use assumes that each data feature has a Gaussian distribution, or can be made to look like Gaussian distribution using a data transformation; this is often done by taking the logarithm of features, as needed.

\n\n

If you have a large training set of both negative and positive examples then do not use anomaly detection models. If your training examples are balanced then use a classification model as we saw earlier in the chapter Deep Learning Using Deeplearning4j.

\n\n

\nMotivation for Anomaly Detection

\n\n

When should we use anomaly detection? This is important so I am going to repeat my suggestion that you should use supervised learning algorithms like neural networks and logistic classification when there are roughly an equal number of available negative and positive examples in the training data. The University of Wisconsin cancer data set is fairly evenly split between negative and positive examples so I artificially fudged it for this example.

\n\n

Anomaly detection should be used when you have many negative (“normal”) examples and relatively few positive (“anomaly”) examples. For the example in this chapter we will simulate scarcity of positive (“anomaly”) results by preparing the data using the Wisconsin cancer data as follows:

\n\n

We will split the data into training (60%), cross validation (20%) and testing (20%).
For the training data, we will discard all but two positive (“anomaly”) examples. We do this to simulate the real world test case where some positive examples are likely to end up in the training data in spite of the fact that we would prefer the training data to only contain negative (“normal”) examples.
We will use the cross validation data to find a good value for the epsilon meta parameter.
After we find a good epsilon value, we will calculate the F1 measurement for the model.

\n\n

\nMath Primer for Anomaly Detection

\n\n

We are trying to model “normal” behavior and we do this by taking each feature and fitting a Gaussian (bell curve) distribution to each feature. The learned parameters for a Gaussian distribution are the mean of the data (where the bell shaped curve is centered) and the variance. You might be more familiar with the term standard deviation, \$\\sigma\$. Variance is defined as \$ \\sigma ^2\$.

\n\n

We will need to calculate the probability of a value x given the mean and variance of a probability distribution: \$P(x : \\mu, \\sigma ^2)\$ where \$\\mu\$ is the mean and \$ \\sigma ^2\$\n is the squared variance:

\n\n\n$$\nP(x : \\mu, \\sigma ^2) = \\frac{1}{{\\sigma \\sqrt {2\\pi } }}e^{{{ - \\left( {x - \\mu } \\right)^2 } \\mathord{\\left/ {\\vphantom {{ - \\left( {x - \\mu } \\right)^2 } {2\\sigma ^2 }}} \\right. \\kern-\\nulldelimiterspace} {2\\sigma ^2 }}}\n$$\n\n

where \$x_i\$ are the samples and we can calculate the squared variance as:

\n\n\n$$\n\\sigma^2 = \\frac{\\displaystyle\\sum_{i=1}^{m}(x_i - \\mu)^2} {m}\n$$\n\n

We calculate the parameters of \$\\mu\$ and \$ \\sigma ^2\$ for each feature. A bell shaped distribution in two dimensions is easy to visualize as is an inverted bowl shape in three dimensions. What if we have many features? Well, the math works and don’t worry about not being able to picture it in your mind!

\n\n

\nAnomalyDetection Utility Class Written in Java

\n\n

The class AnomalyDetection (from my Java AI book) in the directory src-java is fairly general purpose. I won’t list the Java code in the file AnomalyDetection.java here but please do open it in a text editor to refer to while reading this section. This Java class processes a set of training examples and for each feature calculates \$\\mu\$ and \$ \\sigma ^2\$. We are also training for a third parameter: an epsilon “cutoff” value: if for a given input vector \$P(x : \\mu, \\sigma ^2)\$ evaluates to a value greater than epsilon then the input vector is “normal”, less than epsilon implies that the input vector is an “anomaly.” The math for calculating these three features from training data is fairly easy but the code is not: we need to organize the training data and search for a value of epsilon that minimizes the error for a cross validation data set.

\n\n

To be clear: we separate the input examples into three separate sets of training, cross validation, and testing data. We use the training data to set the model parameters, use the cross validation data to learn an epsilon value, and finally use the testing data to get precision, recall, and F1 scores that indicate how well the model detects anomalies in data not used for training and cross validation.

\n\n

If you are interested in the Java implementation either read the source code or for more detail read the code description in my Java AI book.

\n\n

\nClojure Experiment for the University of Wisconsin Cancer Data Using Java Anomaly Detection Code

\n\n

The example in this section loads the University of Wisconsin data and uses the Java class AnomalyDetection described in the last section to find anomalies, which for this example will be input vectors that represented malignancy in the original data. We don’t train on the non-malignancy samples.

\n\n

The Wisconsin data has 9 input features and one target output. Optionally the example program can use Incanter to plot the distribution of input variables. For of these plots are shown here:

\n\n\n

\"Distributions — Distributions for 4 of the 9 input features

\n\n\n

Let’s start by looking at the project file project.clj:

\n\n

 1 (defproject anomaly_detection_clj \"0.1.0-SNAPSHOT\"\n 2   :description \"Anomaly Detection code\"\n 3   :url \"https://markwatson.com\"\n 4   :license\n 5   {:name\n 6    \"EPL-2.0 OR GPL-2+ WITH Classpath-exception-2.0\"\n 7    :url \"https://www.eclipse.org/legal/epl-2.0/\"}\n 8   :dependencies [[org.clojure/clojure \"1.10.1\"]\n 9                  [org.apache.commons/commons-io \"1.3.2\"]\n10                  [org.clojure/data.csv \"1.0.0\"]\n11                  [incanter \"1.9.3\"]]\n12   :source-paths      [\"src\"]\n13   :java-source-paths [\"src-java\"]\n14   :javac-options     [\"-target\" \"1.8\" \"-source\" \"1.8\"]\n15   :main ^:skip-aot anomaly-detection-clj.core\n16   :target-path \"target/%s\"\n17   :profiles\n18   {:uberjar\n19       {:aot :all\n20        :jvm-opts\n21        [\"-Dclojure.compiler.direct-linking=true\"]}})\n

\n\n\n\n

The example code in src/anomaly_detection/core.clj is formatted for page width in the following listing:

\n\n

 1 (ns anomaly-detection-clj.core\n 2   (:gen-class)\n 3   (:require clojure.pprint)\n 4   (:require (incanter core stats charts))\n 5   (:require [clojure.data.csv :as csv])\n 6   (:require [clojure.java.io :as io])\n 7   (:require [clojure.data.csv :as csv]))\n 8 \n 9 (import\n10  (com.markwatson.anomaly_detection AnomalyDetection))\n11 \n12 (def GENERATE_PLOTS false)\n13 \n14 (defn print-histogram [title values-2d index-to-display]\n15   (println \"** plotting:\" title)\n16   (let [column (for [row values-2d]\n17                  (nth row index-to-display))]\n18     (incanter.core/view\n19       (incanter.charts/histogram column\n20                                  :title title))))\n21 \n22 (defn data->gausian\n23   \"separate labeled output and then make the data look\n24    more like a Gausian (bell curve shaped) distribution\"\n25   [vector-of-numbers-as-strings]\n26   (let [v (map read-string vector-of-numbers-as-strings)\n27         training-data0 (map\n28                          (fn [x]\n29                            (Math/log\n30                              (+ (* 0.1 x) 1.2)))\n31                          (butlast v))\n32         ; target output should be [0,1] instead of [2,4]:\n33         target-output (* 0.5 (- (last v) 2))\n34         vmin (apply min training-data0)\n35         vmax (apply max training-data0)\n36         training-data (map\n37                         (fn [x]\n38                           (/\n39                             (- x vmin)\n40                             (+ 0.0001 (- vmax vmin))))\n41                         training-data0)]\n42     (concat training-data [target-output])))\n43 \n44 (defn testAD []\n45   (let [ad (AnomalyDetection.)\n46         cdata\n47         (map\n48           data->gausian\n49           (with-open\n50             [reader\n51               (io/reader\n52                \"data/cleaned_wisconsin_cancer_data.csv\")]\n53             (doall\n54               (csv/read-csv reader))))]\n55     (if GENERATE_PLOTS\n56       (do\n57         (print-histogram \"Clump Thickness\" cdata 0)\n58         (print-histogram\n59           \"Uniformity of Cell Size\" cdata 1)\n60         (print-histogram\n61           \"Uniformity of Cell Shape\" cdata 2)\n62         (print-histogram \"Marginal Adhesion\" cdata 3)\n63         (print-histogram\n64           \"Single Epithelial Cell Size\" cdata 4)\n65         (print-histogram \"Bare Nuclei\" cdata 5)\n66         (print-histogram \"Bland Chromatin\" cdata 6)\n67         (print-histogram \"Normal Nucleoli\" cdata 7)\n68         (print-histogram \"Mitoses\" cdata 8)))\n69     ;; get best model parameters:\n70     (let [java-cdata (into-array (map double-array cdata))\n71           detector\n72           (new AnomalyDetection\n73             10 (- (count cdata) 1) java-cdata)]\n74       (. detector train)\n75       (let [test_malignant\n76             (double-array [0.5 1 1 0.8 0.5 0.5 0.7 1 0.1])\n77             test_benign\n78             (double-array\n79              [0.5 0.4 0.5 0.1 0.8 0.1 0.3 0.6 0.1])\n80             malignant_result\n81             (. detector isAnamoly test_malignant)\n82             benign_result\n83             (. detector isAnamoly test_benign)]\n84         (if malignant_result\n85           (println \"malignant_result true\")\n86           (println \"malignant_result false\"))\n87         (if benign_result\n88           (println \"benign_result true\")\n89           (println \"benign_result false\"))\n90 \n91         ))))\n92         \n93 (defn -main [& _]\n94   (testAD))\n

\n\n\n\n

Data used by an anomaly detection model should have (roughly) a Gaussian (bell curve shape) distribution. What form does the cancer data have? Unfortunately, each of the data features seems to either have a greater density at the lower range of feature values or large density at the extremes of the data feature ranges. This will cause our model to not perform as well as we would like.

\n\n

I won’t do it in this example, but the feature “Bare Nuclei” should be removed because it is not even close to being a bell-shaped distribution. Another thing that you can do (recommended by Andrew Ng in his Coursera Machine Learning class) is to take the log of data and otherwise transform it to something that looks more like a Gaussian distribution.

\n\n

In a real application you would drop features that you can not transform to something like a Gaussian distribution.

\n\n

Here are the results of running the code as it is in the GitHub repository for this book (with some verbose output removed for brevity):

\n\n

   cross_validation_error_count = 75.0 for epsilon = 0.05\n   cross_validation_error_count = 75.0 for epsilon = 0.07\n   cross_validation_error_count = 75.0 for epsilon = 0.08\n   cross_validation_error_count = 68.0 for epsilon = 0.14\n   cross_validation_error_count = 113.0 for epsilon = 0.24\n   cross_validation_error_count = 113.0 for epsilon = 0.25\n   cross_validation_error_count = 113.0 for epsilon = 0.38\n   cross_validation_error_count = 113.0 for epsilon = 0.39\n   cross_validation_error_count = 113.0 for epsilon = 0.4\n   cross_validation_error_count = 113.0 for epsilon = 0.41\n   cross_validation_error_count = 113.0 for epsilon = 0.42\n   cross_validation_error_count = 113.0 for epsilon = 0.43\n   cross_validation_error_count = 113.0 for epsilon = 0.44\n\n**** Best epsilon value = 0.15000000000000002\n   cross_validation_error_count = 63.0 for epsilon = 0.15000000000000002\n\n -- best epsilon = 0.15000000000000002\n -- number of test examples = 66\n -- number of false positives = 0.0\n -- number of true positives = 8.0\n -- number of false negatives = 11.0\n -- number of true negatives = 47.0\n -- precision = 1.0\n -- recall = 0.42105263157894735\n -- F1 = 0.5925925925925926\nmalignant_result true\nbenign_result false\n

\n\n\n\n

How do we evaluate these results? The precision value of 1.0 means that there were no false positives. False positives are predictions of a true result when it should have been false. The value 0.421 for recall means that of all the samples that should have been classified as positive, we only predicted about 42% of them. The F1 score is calculated as two times the product of precision and recall, divided by the sum of precision plus recall.

\n\n

We used a simple approach here that has the benefit of working with small data sets. Ideally, even with highly unbalanced data sets, we would have sufficient positive examples to use deep learning to model features, data transformations, and a classification model. In many real-world problems with unbalanced data sets, sufficient data is not available.

\n\n\n

\nWeb Scraping

\n\n

I often write software to automatically collect and use data from the web and other sources. As a practical matter, much of the data that many people use for machine learning comes from either the web or from internal data sources. This section provides some guidance and examples for getting text data from the web.

\n\n

Before we start a technical discussion about web scraping I want to point out that much of the information on the web is copyright and the first thing that you should do is to read the terms of service for web sites to insure that your use of “scraped” or “spidered” data conforms with the wishes of the persons or organizations who own the content and pay to run scraped web sites.

\n\n

\nWeb Scraping Using the jsoup Library

\n\n

We will use the MIT licensed Java library jsoup. One reason I selected jsoup for the examples in this chapter out of many fine libraries that provide similar functionality is the particularly nice documentation, especially The jsoup Cookbook which I urge you to bookmark as a general reference. In this chapter I will concentrate on just the most frequent web scraping use cases that I use in my own work: getting all plain text and links from a web site. It should be straightforward for you to take the following example and extend it with whatever else you may need from the jsoup Cookbook.

\n\n

We need to require the jsoup dependency in the project file:

\n\n

 1 (defproject webscraping \"0.1.0-SNAPSHOT\"\n 2   :description \"Demonstration of using Java Jsoup library\"\n 3   :url \"http://markwatson.com\"\n 4   :license\n 5   {:name\n 6    \"EPL-2.0 OR GPL-2+ WITH Classpath-exception-2.0\"\n 7    :url \"https://www.eclipse.org/legal/epl-2.0/\"}\n 8   :dependencies [[org.clojure/clojure \"1.10.1\"]\n 9                  [org.jsoup/jsoup \"1.7.2\"]]\n10   :repl-options {:init-ns webscraping.core})\n

\n\n\n\n

The example code for this chapter uses jsoup to get the complete plain text and also the anchor (<a href=…) data for a web page. In reading the following code let’s start at the end: lines 28-35 where we fetch data from a web site as a jsoup document object. Once we have this document object, we use the Java method text on to get plain text. On line 37 we use the utility function get-html-anchors that is defined in lines 6-23. On line 8 we search for all anchor patterns “a[href]”. For each anchor, we construct the full target URI. Lines 17-21 handle the corner case of URIs like:

\n\n

1 https://example/com#faq\n

\n\n\n\n

where we need to use a check to see if a URI starts with “http” in which case we just use the URI as is. Otherwise, treat the URI as a partial like “#faq” that is added to the base URI.

\n\n

 1 (ns webscraping.core\n 2   (:require [clojure.string :as str]))\n 3 \n 4 (import (org.jsoup Jsoup))\n 5 \n 6 (defn get-html-anchors [jsoup-web-page-contents]\n 7   (let [anchors\n 8         (. jsoup-web-page-contents select \"a[href]\")]\n 9     (for [anchor anchors]\n10       (let [anchor-text\n11             (. (first (. anchor childNodes)) text)\n12             anchor-uri-base\n13             (. (first (. anchor childNodes)) baseUri)\n14             href-attribute\n15             (. (. anchor attributes) get \"href\")\n16             anchor-uri\n17             (if (str/starts-with? href-attribute \"http\")\n18               href-attribute\n19               (str/join \"\"\n20                  [anchor-uri-base\n21                   (. (. anchor attributes) get \"href\")]))\n22             furi (first (. anchor childNodes))]\n23         {:text (str/trim anchor-text) :uri anchor-uri}))))\n24 \n25 (defn fetch-web-page-data\n26   \"Get the <a> anchor data and full text from a web URI\"\n27   [a-uri]\n28   (let [doc\n29         (->\n30           (. Jsoup connect a-uri)\n31           (.userAgent\n32             \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.0; rv:77.0) Gecko/20100101 Fi\\\n33 refox/77.0\")\n34           (.timeout 20000)\n35           (.get))\n36         all-page-text (. doc text)\n37         anchors (get-html-anchors doc)]\n38     {:page-text all-page-text :anchors anchors}))\n

\n\n\n\n

On lines 32-33 I am setting the same user agent as my local web browser. In principle I would prefer making up a user agent name that contains my name and why I am spidering data, but in practice some web sites refuse requests from non-standard agents.

\n\n

Let’s look at the test code for an example of fetching the text and links from my personal web site:

\n\n

 1 (ns webscraping.core-test\n 2   (:require [clojure.test :refer :all]\n 3             [clojure.pprint :as pp]\n 4             [webscraping.core :refer :all]))\n 5 \n 6 (deftest a-test\n 7   (testing\n 8     \"Fetch my website and check number of results\"\n 9     (let [page-data\n10          (fetch-web-page-data \"https://markwatson.com\")]\n11       (pp/pprint page-data)\n12       (is (= (count page-data) 2)))))\n

\n\n\n\n

Output might look like (most of the output is not shown):

\n\n

{:page-text\n \"Mark Watson: AI Practitioner and Lisp Hacker ...\",\n :anchors\n ({:text \"Read my Blog\",\n   :uri \"https://mark-watson.blogspot.com\"}\n  {:text \"Fun stuff\",\n   :uri \"https://markwatson.com#fun\"}\n  {:text \"My Books\",\n   :uri \"https://markwatson.com#books\"}\n  {:text \"My Open Source Projects\",\n   :uri \"https://markwatson.com#opensource\"}\n ...\n  {:text \"leanpub\",\n   :uri \"https://leanpub.com/u/markwatson\"}\n  {:text \"GitHub\",\n   :uri \"https://github.com/mark-watson\"}\n  {:text \"LinkedIn\",\n   :uri \"https://www.linkedin.com/in/marklwatson/\"}\n  {:text \"Twitter\",\n   :uri \"https://twitter.com/mark_l_watson\"}\n... )}\n

\n\n\n\n

For training data for machine learning it is useful to just grab all text on a web page and assume that common phrases dealing with web navigation, etc., will be dropped from learned models because they occur in many different training examples for different classifications.

\n\n

I find the jsoup library to be robust for fetching and parsing HTML data from web pages. As we have seen, it is straightforward to use jsoup in Clojure projects.

\n\n\n

\nUsing the Brave Search APIs

\n\n

Note: I started using the Brave search APIs in June 2024 and replaced the Microsoft Bing search chapter in previous editions with the following material.

\n\n

You will need to get a free API key at https://brave.com/search/api/ to use the following code examples. You can use the search API 2000 times a month for free or pay $5/month to get 20 million API calls a month.

\n\n

\nSetting an Environment Variable for the Access Key for Brave Search APIs

\n\n

Once you get a key for https://brave.com/search/api/ set the following environment variable:

\n\n

export BRAVE_SEARCH_API_KEY=BSGhQ-Nd-......\n

\n\n\n\n

That is not my real subscription key!

\n\n

\nUsing the Brave Search API

\n\n

The following shows the file brave_search.clj:

\n\n

It takes very little code to access the Brave search APIs. Here we define a function named brave-search that takes one parameter query. We get the API subscription ket from an enironment variable, define the URI for the Brave search endpoint, and set up an HTTP request to this endpoint. I encourgae you, dear reader, to experiment with printing out the HTTP response to see all data returned from the Brave search API. Here we only collect the tile, URL, and description for each search result:

\n\n

(ns brave-search.core \n  (:require [clj-http.client :as client]\n             [cheshire.core :as json]\n             [clojure.pprint :refer [pprint]]))\n\n;; define the environment variable \"BRAVE_SEARCH_API_KEY\" with the value of your Bra\\\nve search API key\n\n(defn brave-search [query]\n  (let [subscription-key (System/getenv \"BRAVE_SEARCH_API_KEY\")\n        endpoint \"https://api.search.brave.com/res/v1/web/search\"\n        params {:q query}\n        headers {\"X-Subscription-Token\" subscription-key}\n\n        ;; Call the API\n        response (client/get endpoint {:headers headers\n                                       :query-params params})\n\n        ;; Pull out results\n        results (get-in (json/parse-string (:body response) true) [:web :results])\n\n        ;; Create a vector of vectors containing title, URL, and description\n        res (mapv (fn [result]\n                    [(:title result)\n                     (:url result)\n                     (:description result)])\n                  results)]\n\n    ;; Return the results\n    res))\n

\n\n\n\n

You can use search hints like “site:wikidata.org” to only search specific web sites. In the following example I use the search query:

\n\n

1 \"site:wikidata.org Sedona Arizona\"\n

\n\n\n\n

The example call from the unit test function:

\n\n

  (brave-search \"Sedona Arizona\")]\n  (println results)\n

\n\n\n\n

produces the output (edited for brevity):

\n\n

[[\"Visit Sedona | The official site of the Sedona Tourism Bureau\"\n  \"https://visitsedona.com\"\n  \"The official site of the <strong>Sedona</strong>, AZ tourism bureau. Find out the\\\n best places to stay, eat, and relax in our beautiful central <strong>Arizona</stron\\\ng> resort town.\"]\n\n ... ]\n

\n\n\n\n

\nWrap-up

\n\n

In addition to using automated web scraping to get data for my personal research, I often use automated web search. I find the Brave search APIs are the most convenient to use and I like paying for services that I use. The search engine Duck Duck Go also provides free search APIs but even though I use Duck Duck Go for 90% of my manual web searches, when I build automated systems I prefer to rely on services that I pay for.

\n\n\n

\nBackground Material for the Semantic Web and Knowledge Graphs

\n\n

We will start with a tutorial on Semantic Web data standards like RDF, RDFS, and OWL, then implement a wrapper for the Apache Jena library in the next chapter, and finally take a deeper dive into an example application in the chapter Knowledge Graph Navigator.

\n\n

The scope of the Semantic Web is comprised of all public data sources on the Internet that follow specific standards like RDF. Knowledge Graphs may be large scale, as the graphs that drive Google’s and Facebook’s businesses, or they can be specific to an organization.

\n\n

Notes:

\n\n

The material in this chapter is background material. If you want to jump right into code examples then proceed to the next two chapters.
Much of the material here was derived from a similar chapter in my Java AI book.

\n\n

\nLearning Plan

You will learn how to do the following:

\n\n

Understand RDF data formats.
Understand SPARQL queries for RDF data stores (both local and remote).
Use the Apache Jena library (covered in the next chapter) to use local RDF data and perform SPARQL queries.
Use the Apache Jena library to query remote SPARQL endpoints like DBPedia and WikiData.
Use the Apache Derby relational database to cache SPARQL remote queries for both efficiency and for building systems that may have intermittent access to the Internet (covered in the next chapter).
Take a quick look at RDF, RDFS, and OWL reasoners.

\n\n

The Semantic Web is intended to provide a massive linked set of data for use by software systems just as the World Wide Web provides a massive collection of linked web pages for human reading and browsing. The Semantic Web is like the web in that anyone can generate any content that they want. This freedom to publish anything works for the web because we use our ability to understand natural language to interpret what we read – and often to dismiss material that based upon our own knowledge we consider to be incorrect.

\n\n

Semantic Web and linked data technologies are also useful for smaller amounts of data, an example being a Knowledge Graph containing information for a business. We will further explore Knowledge Graphs in the next two chapters.

\n\n

The core concept for the Semantic Web is data integration and use from different sources. As we will soon see, the tools for implementing the Semantic Web are designed for encoding data and sharing data from many different sources.

\n\n

I cover the Semantic Web in this book because I believe that Semantic Web technologies are complementary to AI systems for gathering and processing data on the web. As more web pages are generated by applications (as opposed to simply showing static HTML files) it becomes easier to produce both HTML for human readers and semantic data for software agents.

\n\n

There are several very good Semantic Web toolkits for the Java language and platform. Here we use Apache Jena because it is what I often use in my own work and I believe that it is a good starting technology for your first experiments with Semantic Web technologies. This chapter provides an incomplete coverage of Semantic Web technologies and is intended as a gentle introduction to a few useful techniques and how to implement those techniques in Clojure (using the Java Jena libraries).

\n\n

This material is just the start of a journey in understanding the technology that I think is as important as technologies like deep learning that get more public mindshare.

\n\n

The following figure shows a layered hierarchy of data models that are used to implement Semantic Web applications. To design and implement these applications we need to think in terms of physical models (storage and access of RDF, RDFS, and perhaps OWL data), logical models (how we use RDF and RDFS to define relationships between data represented as unique URIs and string literals and how we logically combine data from different sources) and conceptual modeling (higher level knowledge representation and reasoning using OWL). Originally RDF data was serialized as XML data but other formats have become much more popular because they are easier to read and manually create. The top three layers in the figure might be represented as XML, or as LD-JSON (linked data JSON) or formats like N-Triples and N3 that we will use later.

\n\n\n

RDF data is the bedrock of the Semantic Web and Knowledge Graphs.

\n\n

\nAvailable Tools

\n\n

Previously for Java-based semantic web projects I used the open source Sesame library for managing and querying RDF Data. Sesame is now called RDF4J and is part of the Eclipse organization’s projects.

\n\n

I decided to use the Apache Jena project in this new edition because I think Jena is slightly easier to set up a lightweight development environment. If you need to set up an RDF server I recommend using the open source Fuseki server which is part of the Apache Jena project. For experimenting with local Knowledge Graphs I also use the free version of GraphDB. For client applications, in the next chapter we will use a Clojure wrapper for the Jena library that works with RDF and performing SPARQL queries.

\n\n

\nRDF: The Universal Data Format

\n\n

The Resource Description Framework (RDF) is used to encode information and the RDF Schema (RDFS) facilitates using data with different RDF encodings without the need to convert one set of schemas to another. Later, using OWL, we can simply declare that one predicate is the same as another; that is, one predicate is a sub-predicate of another (e.g., a property containsCity can be declared to be a sub-property of containsPlace so if something contains a city then it also contains a place), etc. The predicate part of an RDF statement often refers to a property.

\n\n

RDF data was originally encoded as XML and intended for automated processing. In this chapter we will use two simple to read formats called “N-Triples” and “N3.” Apache Jena can be used to convert between all RDF formats so we might as well use formats that are easier to read and understand. RDF data consists of a set of triple values:

\n\n

subject
predicate
object

\n\n

Some of my work with Semantic Web technologies deals with processing news stories, extracting semantic information from the text, and storing it in RDF. I will use this application domain for the examples in this chapter and the next chapter when we implement code to automatically generate RDF for Knowledge Graphs. I deal with triples like:

\n\n

subject: a URL (or URI) of a news article.
predicate: a relation like “containsPerson”.
object: a literal value like “Bill Clinton” or a URI representing Bill Clinton.

\n\n

In the next chapter we will use the entity recognition library we developed in an earlier chapter to create RDF from text input.

\n\n

We will use either URIs or string literals as values for objects. We will always use URIs for representing subjects and predicates. In any case URIs are usually preferred to string literals. We will see an example of this preferred use but first we need to learn the N-Triple and N3 RDF formats.

\n\n

I proposed the idea that RDF was more flexible than Object Modeling in programming languages, relational databases, and XML with schemas. If we can tag new attributes on the fly to existing data, how do we prevent what I might call “data chaos” as we modify existing data sources? It turns out that the solution to this problem is also the solution for encoding real semantics (or meaning) with data: we usually use unique URIs for RDF subjects, predicates, and objects, and usually with a preference for not using string literals. The definitions of predicates are tied to a namespace and later with OWL we will state the equivalence of predicates in different namespaces with the same semantic meaning. I will try to make this idea more clear with some examples and Wikipedia has a good writeup on RDF.

\n\n

Any part of a triple (subject, predicate, or object) is either a URI or a string literal. URIs encode namespaces. For example, the containsPerson predicate in the last example could be written as:

\n\n

http://knowledgebooks.com/ontology/#containsPerson\n

\n\n\n\n

The first part of this URI is considered to be the namespace for this predicate “containsPerson.” When different RDF triples use this same predicate, this is some assurance to us that all users of this predicate understand the same meaning. Furthermore, we will see later that we can use RDFS to state equivalency between this predicate (in the namespace http://knowledgebooks.com/ontology/) with predicates represented by different URIs used in other data sources. In an “artificial intelligence” sense, software that we write does not understand predicates like “containsCity”, “containsPerson”, or “isLocation” in the way that a human reader can by combining understood common meanings for the words “contains”, “city”, “is”, “person”, and “location” but for many interesting and useful types of applications that is fine as long as the predicate is used consistently. We will see that we can define abbreviation prefixes for namespaces which makes RDF and RDFS files shorter and easier to read.

\n\n

The Jena library supports most serialization formats for RDF:

\n\n

Turtle
N3
N-Triples
NQuads
TriG
JSON-LD
RDF/XML
RDF/JSON
TriX
RDF Binary

\n\n

A statement in N-Triple format consists of three URIs (two URIs and a string literals for the object) followed by a period to end the statement. While statements are often written one per line in a source file they can be broken across lines; it is the ending period which marks the end of a statement. The standard file extension for N-Triple format files is *.nt and the standard format for N3 format files is *.n3.

\n\n

My preference is to use N-Triple format files as output from programs that I write to save data as RDF. N-Triple files don’t use any abbreviations and each RDF statement is self-contained. I often use tools like the command line commands in Jena or RDF4J to convert N-Triple files to N3 or other formats if I will be reading them or even hand editing them. Here is an example using the N3 syntax:

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#>\n\n<http://news.com/201234/> kb:containsCountry \"China\" .\n

\n\n\n\n

The N3 format adds prefixes (abbreviations) to the N-Triple format. In practice it would be better to use the URI http://dbpedia.org/resource/China instead of the literal value “China.”

\n\n

Here we see the use of an abbreviation prefix “kb:” for the namespace for my company KnowledgeBooks.com ontologies. The first term in the RDF statement (the subject) is the URI of a news article. The second term (the predicate) is “containsCountry” in the “kb:” namespace. The last item in the statement (the object) is a string literal “China.” I would describe this RDF statement in English as, “The news article at URI http://news.com/201234 mentions the country China.”

\n\n

This was a very simple N3 example which we will expand to show additional features of the N3 notation. As another example, let’s look at the case of this news article also mentioning the USA. Instead of adding a whole new statement like this we can combine them using N3 notation. Here we have two separate RDF statements:

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#> .\n\n<http://news.com/201234/>\n  kb:containsCountry\n  <http://dbpedia.org/resource/China>  .\n  \n<http://news.com/201234/>\n  kb:containsCountry\n  <http://dbpedia.org/resource/United_States>  .\n

\n\n\n\n

We can collapse multiple RDF statements that share the same subject and optionally the same predicate:

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#> .\n\n<http://news.com/201234/>\n  kb:containsCountry\n    <http://dbpedia.org/resource/China> ,\n    <http://dbpedia.org/resource/United_States>  .\n

\n\n\n\n

The indentation and placement on separate lines is arbitrary - use whatever style you like that is readable. We can also add in additional predicates that use the same subject (I am going to use string literals here instead of URIs for objects to make the following example more concise but in practice prefer using URIs):

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#> .\n\n<http://news.com/201234/>\n        kb:containsCountry \"China\" ,\n                           \"USA\" .\n        kb:containsOrganization \"United Nations\" ;\n        kb:containsPerson \"Ban Ki-moon\" , \"Gordon Brown\" ,\n                          \"Hu Jintao\" , \"George W. Bush\" ,\n                          \"Pervez Musharraf\" ,\n                          \"Vladimir Putin\" , \n                          \"Mahmoud Ahmadinejad\" .\n

\n\n\n\n

This single N3 statement represents ten individual RDF triples. Each section defining triples with the same subject and predicate have objects separated by commas and ending with a period. Please note that whatever RDF storage system you use (we will be using Jena) it makes no difference if we load RDF as XML, N-Triple, or N3 format files: internally subject, predicate, and object triples are stored in the same way and are used in the same way. RDF triples in a data store represent directed graphs that may not all be connected.

\n\n

I promised you that the data in RDF data stores was easy to extend. As an example, let us assume that we have written software that is able to read online news articles and create RDF data that captures some of the semantics in the articles. If we extend our program to also recognize dates when the articles are published, we can simply reprocess articles and for each article add a triple to our RDF data store using a form like:

\n\n

1 @prefix kb:  <http://knowledgebooks.com/ontology#> .\n2 \n3 <http://news.com/201234/>\n4   kb:datePublished\n5   \"2008-05-11\" .\n

\n\n\n\n

Note that I split one RDF statement across three lines (3-5) here to fit page width. The RDF statement on lines 3-5 is legal and will be handled correctly by RDF parsers. Here we just represent the date as a string. We can add a type to the object representing a specific date:

\n\n

@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n@prefix kb:  <http://knowledgebooks.com/ontology#> .\n \n <http://news.com/201234/>\n   kb:datePublished\n   \"2008-05-11\"^^xsd:date .\n

\n\n\n\n

Furthermore, if we do not have dates for all news articles, that is often acceptable because when constructing SPARQL queries you can match optional patterns. If for example you are looking up articles on a specific subject then some results may have a publication date attached to the results for that article and some might not. In practice RDF supports types and we would use a date type as seen in the last example, not a string. However, in designing the example programs for this chapter I decided to simplify our representation of URIs and often use string literals as simple Java strings.

\n\n

\nExtending RDF with RDF Schema

\n\n

RDF Schema (RDFS) supports the definition of classes and properties based on set inclusion. In RDFS classes and properties are orthogonal. Let’s start with looking at an example using additional namespaces:

\n\n

@prefix kb:   <http://knowledgebooks.com/ontology#> .\n@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix dbo:  <http://dbpedia.org/ontology/> .\n\n<http://news.com/201234/>\n  kb:containsCountry\n  <http://dbpedia.org/resource/China>  .\n  \n<http://news.com/201234/>\n  kb:containsCountry\n  <http://dbpedia.org/resource/United_States>  .\n  \n<http://dbpedia.org/resource/China>\n  rdfs:label \"China\"@en,\n  rdf:type dbo:Place ,\n  rdf:type dbo:Country .\n

\n\n\n\n

Because the Semantic Web is intended to be processed automatically by software systems it is encoded as RDF. There is a problem that must be solved in implementing and using the Semantic Web: everyone who publishes Semantic Web data is free to create their own RDF schemas for storing data. For example, there is usually no single standard RDF schema definition for topics like news stories and stock market data. The SKOS is a namespace containing standard schemas and the most widely used standard is schema.org. Understanding the ways of integrating different data sources using different schemas helps to understand the design decisions behind the Semantic Web applications. In this chapter I often use my own schemas in the knowledgebooks.com namespace for the simple examples you see here. When you build your own production systems part of the work is searching through schema.org and SKOS to use standard name spaces and schemas when possible because this facilitates linking your data to other RDF Data on the web. The use of standard schemas helps when you link internal proprietary Knowledge Graphs used in organization with public open data from sources like WikiData and DBPedia.

\n\n

Let’s consider an example: suppose that your local Knowledge Graph referred to President Joe Biden in which case we could “mint” our own URI like:

\n\n

1 https://knowledgebooks.com/person#Joe_Biden\n

\n\n\n\n

In this case users of the local Knowledge Graph could not take advantage of connected data. For example, the DBPedia and WikiData URIs for How Biden are:

\n\n

Both of these URIs can be followed by clicking on the links if you are reading a PDF copy of this book. Please “follow your nose” and see how both of these URIs resolve to human-readable web pages.

\n\n

After telling you, dear reader, to always try to use public and standard URIs like the above examples for Joe Biden, I will now revert to using simple made-up URIs for the following discussion.

\n\n

We will start with an example that is an extension of the example in the last section that also uses RDFS. We add a few additional RDF statements:

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#> .\n@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .\n\nkb:containsCity rdfs:subPropertyOf kb:containsPlace .\nkb:containsCountry rdfs:subPropertyOf kb:containsPlace .\nkb:containsState rdfs:subPropertyOf kb:containsPlace .\n

\n\n\n\n

The last three lines declare that:

\n\n

The property containsCity is a sub-property of containsPlace.
The property containsCountry is a sub-property of containsPlace.
The property containsState is a sub-property of containsPlace.

\n\n

Why is this useful? For at least two reasons:

\n\n

You can query an RDF data store for all triples that use property containsPlace and also match triples with properties equal to containsCity, containsCountry, or containsState. There may not even be any triples that explicitly use the property containsPlace.
Consider a hypothetical case where you are using two different RDF data stores that use different properties for naming cities: cityName and city. You can define cityName to be a sub-property of city and then write all queries against the single property name city. This removes the necessity to convert data from different sources to use the same Schema. You can also use OWL to state property and class equivalency.

\n\n

In addition to providing a vocabulary for describing properties and class membership by properties, RDFS is also used for logical inference to infer new triples, combine data from different RDF data sources, and to allow effective querying of RDF data stores. We will see examples of all of these features of RDFS when we later start using the Jena libraries to perform SPARQL queries.

\n\n

\nThe SPARQL Query Language

\n\n

SPARQL is a query language used to query RDF data stores. While SPARQL may initially look like SQL, we will see that there are some important differences like support for RDFS and OWL inferencing and graph-based instead of relational matching operations. We will cover the basics of SPARQL in this section and then see more examples later when we learn how to embed Jena in Java applications, and see more examples in the last chapter Knowledge Graph Navigator.

\n\n

We will use the N3 format RDF file test_data/news.n3 for the examples. I created this file automatically by spidering Reuters news stories on the news.yahoo.com web site and automatically extracting named entities from the text of the articles. We saw techniques for extracting named entities from text in earlier chapters. In this chapter we use these sample RDF files.

\n\n

You have already seen snippets of this file and I list the entire file here for reference, edited to fit line width: you may find the file news.n3 easier to read if you are at your computer and open the file in a text editor so you will not be limited to what fits on a book page:

\n\n

@prefix kb:  <http://knowledgebooks.com/ontology#> .\n@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .\n\nkb:containsCity rdfs:subPropertyOf kb:containsPlace .\n\nkb:containsCountry rdfs:subPropertyOf kb:containsPlace .\n\nkb:containsState rdfs:subPropertyOf kb:containsPlace .\n\n<http://yahoo.com/20080616/usa_flooding_dc_16/>\n        kb:containsCity \"Burlington\" , \"Denver\" ,\n                        \"St. Paul\" ,\" Chicago\" ,\n                        \"Quincy\" , \"CHICAGO\" ,\n                        \"Iowa City\" ;\n        kb:containsRegion \"U.S. Midwest\" , \"Midwest\" ;\n        kb:containsCountry \"United States\" , \"Japan\" ;\n        kb:containsState \"Minnesota\" , \"Illinois\" , \n                         \"Mississippi\" , \"Iowa\" ;\n        kb:containsOrganization \"National Guard\" ,\n                         \"U.S. Department of Agriculture\",\n                         \"White House\" ,\n                         \"Chicago Board of Trade\" ,\n                         \"Department of Transportation\" ;\n        kb:containsPerson \"Dena Gray-Fisher\" ,\n                          \"Donald Miller\" ,\n                          \"Glenn Hollander\" ,\n                          \"Rich Feltes\" ,\n                          \"George W. Bush\" ;\n        kb:containsIndustryTerm \"food inflation\", \"food\",\n                                \"finance ministers\" ,\n                                \"oil\" .\n\n<http://yahoo.com/78325/ts_nm/usa_politics_dc_2/>\n        kb:containsCity \"Washington\" , \"Baghdad\" ,\n                        \"Arlington\" , \"Flint\" ;\n        kb:containsCountry \"United States\" ,\n                           \"Afghanistan\" ,\n                           \"Iraq\" ;\n        kb:containsState \"Illinois\" , \"Virginia\" ,\n                         \"Arizona\" , \"Michigan\" ;\n        kb:containsOrganization \"White House\" ,\n                                \"Obama administration\" ,\n                                \"Iraqi government\" ;\n        kb:containsPerson \"David Petraeus\" ,\n                          \"John McCain\" ,\n                          \"Hoshiyar Zebari\" ,\n                          \"Barack Obama\" ,\n                          \"George W. Bush\" ,\n                          \"Carly Fiorina\" ;\n        kb:containsIndustryTerm \"oil prices\" .\n\n<http://yahoo.com/10944/ts_nm/worldleaders_dc_1/>\n        kb:containsCity \"WASHINGTON\" ;\n        kb:containsCountry \"United States\" , \"Pakistan\" ,\n                           \"Islamic Republic of Iran\" ;\n        kb:containsState \"Maryland\" ;\n        kb:containsOrganization \"University of Maryland\" ,\n                                \"United Nations\" ;\n        kb:containsPerson \"Ban Ki-moon\" , \"Gordon Brown\" ,\n                          \"Hu Jintao\" , \"George W. Bush\" ,\n                          \"Pervez Musharraf\" ,\n                          \"Vladimir Putin\" ,\n                          \"Steven Kull\" ,\n                          \"Mahmoud Ahmadinejad\" .\n\n<http://yahoo.com/10622/global_economy_dc_4/>\n        kb:containsCity \"Sao Paulo\" , \"Kuala Lumpur\" ;\n        kb:containsRegion \"Midwest\" ;\n        kb:containsCountry \"United States\" , \"Britain\" ,\n                           \"Saudi Arabia\" , \"Spain\" ,\n                           \"Italy\" , India\" , \n                           \"\"France\" , \"Canada\" ,\n                           \"Russia\", \"Germany\", \"China\",\n                           \"Japan\" , \"South Korea\" ;\n        kb:containsOrganization \"Federal Reserve Bank\" ,\n                                \"European Union\" ,\n                                \"European Central Bank\" ,\n                                \"European Commission\" ;\n        kb:containsPerson \"Lee Myung-bak\" , \"Rajat Nag\" ,\n                          \"Luiz Inacio Lula da Silva\" ,\n                          \"Jeffrey Lacker\" ;\n        kb:containsCompany\n            \"Development Bank Managing\" ,\n            \"Reuters\" ,\n            \"Richmond Federal Reserve Bank\";\n        kb:containsIndustryTerm \"central bank\" , \"food\" ,\n                                \"energy costs\" ,\n                                \"finance ministers\" ,\n                                \"crude oil prices\" ,\n                                \"oil prices\" ,\n                                \"oil shock\" ,\n                                \"food prices\" ,\n                                \"Finance ministers\" ,\n                                \"Oil prices\" , \"oil\" .\n

\n\n\n\n

Please note that in the above RDF listing I took advantage of the free form syntax of N3 and Turtle RDF formats to reformat the data to fit page width.

\n\n

In the following examples, I used the library developed in the next chapter that allows us to load multiple RDF input files and then to use SPARQL queries.

\n\n

We will start with a simple SPARQL query for subjects (news article URLs) and objects (matching countries) with the value for the predicate equal to containsCountry. Variables in queries start with a question mark character and can have any names:

\n\n

SELECT ?subject ?object\n  WHERE {\n   ?subject\n   <http://knowledgebooks.com/ontology#containsCountry>\n   ?object .\n}\n

\n\n\n\n

It is important for you to understand what is happening when we apply the last SPARQL query to our sample data. Conceptually, all the triples in the sample data are scanned, keeping the ones where the predicate part of a triple is equal to http://knowledgebooks.com/ontology#containsCountry. In practice RDF data stores supporting SPARQL queries index RDF data so a complete scan of the sample data is not required. This is analogous to relational databases where indices are created to avoid needing to perform complete scans of database tables.

\n\n

In practice, when you are exploring a Knowledge Graph like DBPedia or WikiData (that are just very large collections of RDF triples), you might run a query and discover a useful or interesting entity URI in the triple store, then drill down to find out more about the entity. In a later chapter Knowledge Graph Navigator we attempt to automate this exploration process using the DBPedia data as a Knowledge Graph.

\n\n

We will be using the same code to access the small example of RDF statements in our sample data as we will for accessing DBPedia or WikiData.

\n\n

We can make this last query easier to read and reduce the chance of misspelling errors by using a namespace prefix:

\n\n

PREFIX kb:  <http://knowledgebooks.com/ontology#>\nSELECT ?subject ?object\n  WHERE {\n      ?subject kb:containsCountry ?object .\n  }\n

\n\n\n\n

We could have filtered on any other predicate, for instance containsPlace. Here is another example using a match against a string literal to find all articles exactly matching the text “Maryland.”

\n\n

PREFIX kb:  <http://knowledgebooks.com/ontology#>\nSELECT ?subject WHERE { ?subject kb:containsState \"Maryland\" . }\n

\n\n\n\n

The output is:

\n\n

http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n

\n\n\n\n

We can also match partial string literals against regular expressions:

\n\n

PREFIX kb: <http://knowledgebooks.com/ontology#>\nSELECT ?subject ?object\n       WHERE {\n         ?subject\n         kb:containsOrganization\n         ?object FILTER regex(?object, \"University\") .\n       }\n

\n\n\n\n

The output is:

\n\n

http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/ \n   \"University of Maryland\"\n

\n\n\n\n

We might want to return all triples matching a property of containing an organization and where the object is a string containing the substring “University.” The matching statement after the FILTER check matches every triple that matches the subject in the first pattern:

\n\n

PREFIX kb: <http://knowledgebooks.com/ontology#>\nSELECT DISTINCT ?subject ?a_predicate ?an_object\n WHERE {\n    ?subject kb:containsOrganization ?object .\n       FILTER regex(?object,\"University\") .\n    ?subject ?a_predicate ?an_object .\n}\nORDER BY ?a_predicate ?an_object\nLIMIT 10\nOFFSET 5\n

\n\n\n\n

When WHERE clauses contain more than one triple pattern to match, this is equivalent to a Boolean “and” operation. The DISTINCT clause removes duplicate results. The ORDER BY clause sorts the output in alphabetical order: in this case first by predicate (containsCity, containsCountry, etc.) and then by object. The LIMIT modifier limits the number of results returned and the OFFSET modifier sets the number of matching results to skip.

\n\n

The output is:

\n\n

 1 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n 2 \t http://knowledgebooks.com/ontology#containsOrganization\n 3    \"University of Maryland\" .\n 4 \n 5 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n 6 \t http://knowledgebooks.com/ontology#containsPerson,\n 7 \t \"Ban Ki-moon\" .\n 8 \t \n 9 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n10 \t http://knowledgebooks.com/ontology#containsPerson\n11 \t \"George W. Bush\" .\n12 \n13 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n14 \t http://knowledgebooks.com/ontology#containsPerson\n15 \t \"Gordon Brown\" .\n16 \n17 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n18 \t http://knowledgebooks.com/ontology#containsPerson\n19 \t \"Hu Jintao\" .\n20 \n21 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n22 \t http://knowledgebooks.com/ontology#containsPerson\n23 \t \"Mahmoud Ahmadinejad\" .\n24 \n25 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n26 \t http://knowledgebooks.com/ontology#containsPerson\n27 \t \"Pervez Musharraf\" .\n28 \n29 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n30 \t http://knowledgebooks.com/ontology#containsPerson\n31 \t \"Steven Kull\" .\n32 \n33 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n34 \t http://knowledgebooks.com/ontology#containsPerson\n35 \t \"Vladimir Putin\" .\n36 \n37 http://news.yahoo.com/s/nm/20080616/ts_nm/worldleaders_trust_dc_1/\n38 \t http://knowledgebooks.com/ontology#containsState\n39 \t \"Maryland\" .\n

\n\n\n\n

We are finished with our quick tutorial on using the SELECT query form. There are three other query forms that I am not covering in this chapter:

\n\n

\nCONSTRUCT – returns a new RDF graph of query results
\nASK – returns Boolean true or false indicating if a query matches\nany triples
\nDESCRIBE – returns a new RDF graph containing matched resources

\n\n

A common SELECT matching pattern that I don’t cover in this chapter is optional.

\n\n

\nOWL: The Web Ontology Language

\n\n

We have already seen a few examples of using RDFS to define sub-properties in this chapter. The Web Ontology Language (OWL) extends the expressive power of RDFS. We now look at a few OWL examples and then look at parts of the Java unit test showing three SPARQL queries that use OWL reasoning. The following RDF data stores support at least some level of OWL reasoning:

\n\n

ProtegeOwlApis - compatible with the Protege Ontology editor
Pellet - DL reasoner
Owlim - OWL DL reasoner compatible with some versions of Sesame
Jena - General purpose library
OWLAPI - a simpler API using many other libraries
Stardog - a commercial OWL and RDF reasoning system and datastore
Allegrograph - a commercial RDF+ and RDF reasoning system and datastore

\n\n

OWL is more expressive than RDFS in that it supports cardinality, richer class relationships, and Descriptive Logic (DL) reasoning. OWL treats the idea of classes very differently than object oriented programming languages like Java and Smalltalk, but similar to the way PowerLoom (see chapter on Reasoning) uses concepts (PowerLoom’s rough equivalent to a class). In OWL, instances of a class are referred to as individuals and class membership is determined by a set of properties that allow a DL reasoner to infer class membership of an individual (this is called entailment.)

\n\n

We saw an example of expressing transitive relationships when we were using PowerLoom in the chapter on Reasoning where we defined a PowerLoom rule to express that the relation “contains” is transitive. We will now look at a similar example using OWL.

\n\n

We have been using the RDF file news.n3 in previous examples and we will layer new examples by adding new triples that represent RDF, RDFS, and OWL. We saw in news.n3 the definition of three triples using rdfs:subPropertyOf properties to create a more general kb:containsPlace property:

\n\n

kb:containsCity rdfs:subPropertyOf kb:containsPlace .\nkb:containsCountry rdfs:subPropertyOf kb:containsPlace .\nkb:containsState rdfs:subPropertyOf kb:containsPlace .\n\nkb:containsPlace rdf:type owl:transitiveProperty .\n\nkbplace:UnitedStates kb:containsState kbplace:Illinois .\nkbplace:Illinois kb:containsCity kbplace:Chicago .\n

\n\n\n\n

We can also infer that:

\n\n

kbplace:UnitedStates kb:containsPlace kbplace:Chicago .\n

\n\n\n\n

We can also model inverse properties in OWL. For example, here we add an inverse property kb:containedIn, adding it to the example in the last listing:

\n\n

kb:containedIn owl:inverseOf kb:containsPlace .\n

\n\n\n\n

Given an RDF container that supported extended OWL DL SPARQL queries, we can now execute SPARQL queries matching the property kb:containedIn and “match” triples in the RDF triple store that have never been asserted but are inferred by the OWL reasoner.

\n\n

OWL DL is a very large subset of full OWL. From reading the chapter on Reasoning and the very light coverage of OWL in this section, you should understand the concept of class membership not by explicitly stating that an object (or individual) is a member of a class, but rather because an individual has properties that can be used to infer class membership.

\n\n

The World Wide Web Consortium has defined three versions of the OWL language that are in increasing order of complexity: OWL Lite, OWL DL, and OWL Full. OWL DL (supports Description Logic) is the most widely used (and recommended) version of OWL. OWL Full is not computationally decidable since it supports full logic, multiple class inheritance, and other things that probably make it computationally intractable for all but smaller problems.

\n\n

\nSemantic Web Wrap-up

\n\n

Writing Semantic Web applications and building Knowledge Graphs is a very large topic, worthy of an entire book. I have covered in this chapter the background material for the next two chapters: writing Clojure wrappers for using the Jena library and the Knowledge Graph Navigator application.

\n\n\n

\nClojure Wrapper for the Jena RDF and SPARQL Library

\n\n

If you read through the optional background material in the last chapter you have some understanding of RDF Data and SPARQL queries. If you skipped the last chapter you can still follow along with the code here.

\n\n

When querying remote SPARQL endpoints like DBPedia and WikiData I often find that I repeatedly make some of the same queries many times, especially during development and testing. I have found that by caching SPARQL query results that I can greatly improve my developer experience. We will use the Apache Derby relational database (pure Java code and easy to embed in applications) for query caching.

\n\n

We declare both Jena and the Derby relational database libraries as dependencies in our project file:

\n\n

 1 (defproject semantic_web_jena_clj \"0.1.0-SNAPSHOT\"\n 2   :description \"Clojure Wrapper for Apache Jena\"\n 3   :url \"https://markwatson.com\"\n 4   :license\n 5   {:name \"EPL-2.0 OR GPL-2+ WITH Classpath-exception-2.0\"\n 6    :url \"https://www.eclipse.org/legal/epl-2.0/\"}\n 7   :source-paths      [\"src\"]\n 8   :java-source-paths [\"src-java\"]\n 9   :javac-options     [\"-target\" \"1.8\" \"-source\" \"1.8\"]\n10   :dependencies [[org.clojure/clojure \"1.11.1\"]\n11                  [org.apache.derby/derby \"10.15.2.0\"]\n12                  [org.apache.derby/derbytools \"10.15.2.0\"]\n13                  [org.apache.derby/derbyclient\n14                   \"10.15.2.0\"]\n15                  [org.apache.jena/apache-jena-libs\n16                   \"3.17.0\" :extension \"pom\"]]\n17   :repl-options {:init-ns semantic-web-jena-clj.core})\n

\n\n\n\n

We will use the Jena library for handling RDF and SPARQL queries and the Derby database library for implementing query caching. Please note that the directory structure for this project also includes Java code that I wrote to wrap the Jena APIs for my specific needs (some files not shown for brevity):

\n\n

 1 $ tree                \n 2 .\n 3 ├── LICENSE\n 4 ├── README.md\n 5 ├── data\n 6 │   ├── business.sql\n 7 │   ├── news.nt\n 8 │   ├── sample_news.nt\n 9 ├── pom.xml\n10 ├── project.clj\n11 ├── src\n12 │   └── semantic_web_jena_clj\n13 │       └── core.clj\n14 ├── src-java\n15 │   └── main\n16 │       ├── java\n17 │       │   └── com\n18 │       │       └── markwatson\n19 │       │           └── semanticweb\n20 │       │               ├── Cache.java\n21 │       │               ├── JenaApis.java\n22 │       │               └── QueryResult.java\n23 │       └── resources\n24 │           └── log4j.xml\n25 └── test\n26     └── semantic_web_jena_clj\n27         └── core_test.clj\n

\n\n\n\n

While I expect that you will just use the Java code as is, there is one modification that you might want to make for your applications: I turned on OWL reasoning by default. If you don’t need OWL reasoning and you will be working with large numbers of RDF triples (tens of millions should fit nicely in-memory on your laptop), then you might want to change the following two lines of code in JenaApis.java by uncommenting line 2 and commenting line 4:

\n\n

1  // use if OWL reasoning not required:\n2  //model = ModelFactory.createDefaultModel();\n3  // to use the OWL reasoner:\n4  model = ModelFactory.createOntologyModel();\n

\n\n\n\n

OWL reasoning is expensive but for small RDF Data sets you might as well leave it turned on.

\n\n

I don’t list the file JenaApis.java here but you might want to have it open in an editor while reading the following listing of the Clojure code that wraps this Java code.

\n\n

The Clojure wrapping functions are mostly self-explanatory. The main corner case is converting Java results from Jena to Clojure seq data structures, as we do in lines 13-14.

\n\n

 1 (ns semantic-web-jena-clj.core\n 2   (:import (com.markwatson.semanticweb JenaApis Cache\n 3                                        QueryResult)))\n 4 \n 5 (defn- get-jena-api-model\n 6   \"get a default model with OWL reasoning\"\n 7   []\n 8   (new JenaApis))\n 9 \n10 (defonce model (get-jena-api-model))\n11 \n12 (defn- results->clj [results]\n13   (let [variable-list (seq (. results variableList))\n14         bindings-list (seq (map seq (. results rows)))]\n15     (cons variable-list bindings-list)))\n16 \n17 (defn load-rdf-file [fpath]\n18   (. model loadRdfFile fpath))\n19 \n20 (defn query \"SPARQL query\" [sparql-query]\n21   (results->clj (. model query sparql-query)))\n22 \n23 (defn query-remote\n24  \"remote service like DBPedia, etc.\"\n25  [remote-service sparql-query]\n26   (results->clj\n27     (. model queryRemote remote-service sparql-query)))\n28 \n29 (defn query-dbpedia [sparql-query]\n30   (query-remote \"https://dbpedia.org/sparql\"\n31                 sparql-query))\n32 \n33 (defn query-wikidata [sparql-query]\n34   (query-remote\n35     \"https://query.wikidata.org/bigdata/namespace/wdq/sparql\" sparql-query))\n

\n\n\n\n

Here is a listing of text code that loads RDF data from a file and does a SPARQL query, SPARQL queries DBPedia, and SPARQL queries WikiData:

\n\n

 1 (ns semantic-web-jena-clj.core-test\n 2   (:require [clojure.test :refer :all]\n 3             [semantic-web-jena-clj.core :refer :all]))\n 4 \n 5 (deftest load-data-and-sample-queries\n 6   (testing\n 7     \"Load local triples files and SPARQL queries\"\n 8     (load-rdf-file \"data/sample_news.nt\")\n 9     (let [results (query \"select * { ?s ?p ?o } limit 5\")]\n10       (println results)\n11       (is (= (count results) 6)))))\n12 \n13 (deftest dbpedia-test\n14   (testing \"Try SPARQL query to DBPedia endpoint\"\n15     (println\n16       (query-dbpedia\n17         \"select ?p where { <http://dbpedia.org/resource/Bill_Gates> ?p <http://dbped\\\n18 ia.org/resource/Microsoft> . } limit 10\"))))\n19 \n20 (deftest wikidata-test\n21   (testing \"Try SPARQL query to WikiData endpoint\"\n22     (println\n23       (query-dbpedia\n24         \"select * where { ?subject ?property ?object . } limit 10\"))))\n

\n\n\n\n

You might question line 11: We are checking that the return values as a seq of length six while the SPARQL statement limits the returned results to five results on line 9. The “extra” result” of the first element in the seq that is a list of variable names from the SPARQL query.

\n\n

Output will look like (reformatted for readability and most output is not shown):

\n\n

1 ((subject property object)\n2  (http://www.openlinksw.com/virtrdf-data-formats#default-iid\n3   http://www.w3.org/1999/02/22-rdf-syntax-ns#type\n4   http://www.openlinksw.com/schemas/virtrdf#QuadMapFormat)\n5  (http://www.openlinksw.com/virtrdf-data-formats#default-iid-nullable\n6   http://www.w3.org/1999/02/22-rdf-syntax-ns#type\n7   http://www.openlinksw.com/schemas/virtrdf#QuadMapFormat)\n8   ...\n

\n\n\n\n

Data consists of nested lists where the first sub-list is the SPARQL query variable names, in this case: subject property object. Subsequent sub-lists are binding values for the query variables.

\n\n

We will use the Jena wrapper in the next chapter.

\n\n\n

\nSimple RDF Datastore and Partial SPARQL Query Processor

\n\n

In this chapter, we’ll explore how to build a basic RDF (Resource Description Framework) datastore and implement a partial SPARQL (SPARQL Protocol and RDF Query Language) query processor using Clojure. The goal is to provide a simple but effective demonstration of RDF data manipulation and querying in a functional programming context.

\n\n

The Clojure code for this example can be found at https://github.com/mark-watson/Clojure-AI-Book-Code/tree/main/simple_rdf_sparql.

\n\n

RDF is a widely-used standard for representing knowledge graphs and linked data, which makes it a valuable tool for applications that need to model complex relationships between entities. SPARQL is the accompanying query language designed to extract and manipulate RDF data, similar to how SQL works with relational databases.

\n\n

This chapter will cover:

\n\n

Implementing a simple RDF datastore.
Managing RDF triples (adding, removing, and querying).
Designing a partial SPARQL query processor to execute basic pattern matching.
Running example queries to demonstrate functionality.

\n\n

By the end of this chapter, you’ll have a good grasp of how to handle RDF data and implement a lightweight SPARQL engine that can process simple queries.

\n\n

\nImplementing a Simple RDF Datastore

\n\n

Let’s begin by creating a simple in-memory RDF datastore using Clojure. An RDF triple is a fundamental data structure composed of a subject, predicate, and object. We will define a Triple record to represent these triples and store them in an atom.

\n\n

1 (ns simple-rdf-sparql.core\n2   (:require [clojure.string :as str]))\n3 \n4 ;; RDF triple structure\n5 (defrecord Triple [subject predicate object])\n6 \n7 ;; RDF datastore\n8 (def ^:dynamic *rdf-store* (atom []))\n

\n\n\n\n

With our triple structure defined, we can implement functions to add and remove triples from the datastore:

\n\n

 1 ;; Add a triple to the datastore\n 2 (defn add-triple [subject predicate object]\n 3   (swap! *rdf-store* conj (->Triple subject predicate object)))\n 4 \n 5 ;; Remove a triple from the datastore\n 6 (defn remove-triple [subject predicate object]\n 7   (swap! *rdf-store* (fn [store]\n 8                        (remove #(and (= (:subject %) subject)\n 9                                      (= (:predicate %) predicate)\n10                                      (= (:object %) object))\n11                                store))))\n

\n\n\n\n

\nQuerying the RDF Datastore

\n\n

Next, we need a way to query the datastore to find specific triples. We’ll start by defining a helper function to filter triples that match a given pattern:

\n\n

 1 ;; Helper function to check if a string is a variable\n 2 (defn variable? [s]\n 3   (and (string? s) (not (empty? s)) (= (first s) \\?)))\n 4 \n 5 ;; Convert triple to binding\n 6 (defn triple-to-binding [triple pattern]\n 7   (into {}\n 8         (filter second\n 9                 (map (fn [field pattern-item]\n10                        (when (variable? pattern-item)\n11                          [pattern-item (field triple)]))\n12                      [:subject :predicate :object]\n13                      pattern))))\n14 \n15 (defn query-triples [subject predicate object]\n16   (filter (fn [triple]\n17             (and (or (nil? subject) (variable? subject)\n18                      (= (:subject triple) subject))\n19                  (or (nil? predicate) (variable? predicate)\n20                      (= (:predicate triple) predicate))\n21                  (or (nil? object) (variable? object)\n22                      (= (:object triple) object))))\n23           @*rdf-store*))\n

\n\n\n\n

This code allows us to extract specific triples from the RDF datastore using pattern matching. Variables in a query pattern are denoted by a ? prefix.

\n\n

\nImplementing a Partial SPARQL Query Processor

\n\n

Now, let’s implement a basic SPARQL query processor. We’ll define a simple query structure and create functions to parse and execute these queries. We need to parse SPARQL queries like:

\n\n

1 select * where { ?name age ?age . ?name likes ?food }\n

\n\n\n\n

 1 ;; SPARQL query structure\n 2 (defrecord SPARQLQuery [select-vars where-patterns])\n 3 \n 4 ;; Parse a SPARQL query string\n 5 (defn parse-sparql-query [query-string]\n 6   (let [tokens (remove #{\"{\"  \"}\"}\n 7                        (str/split query-string #\"\\s+\"))\n 8         select-index (.indexOf tokens \"select\")\n 9         where-index (.indexOf tokens \"where\")\n10         select-vars (subvec (vec tokens)\n11                             (inc select-index) where-index)\n12         where-clause (subvec (vec tokens)\n13                              (inc where-index))\n14         where-patterns\n15         (parse-where-patterns where-clause)]\n16     (->SPARQLQuery select-vars where-patterns)))\n

\n\n\n\n

Next, we’ll define functions to execute the WHERE patterns in a SPARQL query:

\n\n

 1 ;; Execute WHERE patterns with bindings\n 2 (defn execute-where-patterns-with-bindings [patterns bindings]\n 3   (if (empty? patterns)\n 4     [bindings]\n 5     (let [pattern (first patterns)\n 6           remaining-patterns (rest patterns)\n 7           bound-pattern (apply-bindings pattern bindings)\n 8           matching-triples (apply query-triples bound-pattern)\n 9           new-bindings (map #(merge-bindings bindings (triple-to-binding % pattern))\n10                             matching-triples)]\n11       (if (empty? remaining-patterns)\n12         new-bindings\n13         (mapcat #(execute-where-patterns-with-bindings remaining-patterns %)\n14                 new-bindings)))))\n15 \n16 (defn execute-where-patterns [patterns]\n17   (if (empty? patterns)\n18     [{}]\n19     (let [pattern (first patterns)\n20           remaining-patterns (rest patterns)\n21           matching-triples (apply query-triples pattern)\n22           bindings (map #(triple-to-binding % pattern) matching-triples)]\n23       (if (empty? remaining-patterns)\n24         bindings\n25         (mapcat (fn [binding]\n26                   (let [results\n27                         (execute-where-patterns-with-bindings\n28                             remaining-patterns binding)]\n29                     (map #(merge-bindings binding %) results)))\n30                 bindings)))))\n

\n\n\n\n

\nPutting It All Together: Running Example Queries

\n\n

Finally, let’s test our partial SPARQL query processor with some example queries. First, we’ll populate the datastore with a few RDF triples:

\n\n

1 (defn -main []\n2   (reset! *rdf-store* [])\n3 \n4   (add-triple \"John\" \"age\" \"30\")\n5   (add-triple \"John\" \"likes\" \"pizza\")\n6   (add-triple \"Mary\" \"age\" \"25\")\n7   (add-triple \"Mary\" \"likes\" \"sushi\")\n8   (add-triple \"Bob\" \"age\" \"35\")\n9   (add-triple \"Bob\" \"likes\" \"burger\")\n

\n\n\n\n

Next we print all triples in the datastore and execute three sample SPARQL queries:

\n\n

1   (print-all-triples)\n2   (print-query-results\n3     \"select * where { ?name age ?age . ?name likes ?food }\")\n4   (print-query-results\n5     \"select ?s ?o where { ?s likes ?o }\")\n6   (print-query-results\n7     \"select * where { ?name age ?age . ?name likes pizza }\"))\n

\n\n\n\n

\nSummary

\n\n

This chapter demonstrated a minimalistic RDF datastore and a partial SPARQL query processor. We built the foundation to manage RDF triples and run basic pattern-based queries. This simple example can serve as a minimal embedded RDF data store for larger applications or as springboard for more advanced features like full SPARQL support, optimization techniques, and complex query structures. I hope, dear reader, that you have fun with this example.

\n\n\n

\nKnowledge Graph Navigator

\n\n

The Knowledge Graph Navigator (which I will often refer to as KGN) is a tool for processing a set of entity names and automatically explores the public Knowledge Graph DBPedia using SPARQL queries. I started to write KGN for my own use to automate some things I used to do manually when exploring Knowledge Graphs, and later thought that KGN might be also useful for educational purposes. KGN shows the user the auto-generated SPARQL queries so hopefully the user will learn by seeing examples. KGN uses the Clojure Jena wrapper\nexample code from the last chapter as well the two Java classes JenaAPis and QueryResults (which wrap the Apache Jena library) that were also included in the example for the previous chapter.

\n\n

Note: There are three separate examples for implementing SPARQL queries in this example:

\n\n

Use the code from the last chapter (Jena and query caching)
Use a small standalone set of Clojure functions to access DBPedia
Use a small standalone set of Clojure functions to access a local GraphDB RDF server with the data file dbpedia_sample.nt loaded into a graph named dbpedia.

\n\n

The example code is set up to use Jena and query caching; edit the file sparql.clj to enable the other options.

\n\n

I have implemented parts of KGN in several languages: Common Lisp, Java, Racket Scheme, Swift, Python, and Hy. The most full featured version of KGN, including a full user interface, is featured in my book Loving Common Lisp, or the Savvy Programmer’s Secret Weapon that you can read free online. That version performs more speculative SPARQL queries to find information compared to the example here that I designed for ease of understanding, and modification.

\n\n

We will be running an example using data containing three person entities, one company entity, and one place entity. The following figure shows a very small part of the DBPedia Knowledge Graph that is centered around these entities. The data for this figure was collected by an example Knowledge Graph Creator from my Common Lisp book:

\n\n\n

\"File — File dbpedia_sample.nt loaded into the free version of GraphDB

\n\n\n

I chose to use DBPedia instead of WikiData for this example because DBPedia URIs are human readable. The following URIs represent the concept of a person. The semantic meanings of DBPedia and FOAF (friend of a friend) URIs are self-evident to a human reader while the WikiData URI is not:

\n\n

http://www.wikidata.org/entity/Q215627\nhttp://dbpedia.org/ontology/Person\nhttp://xmlns.com/foaf/0.1/name\n

\n\n\n\n

I frequently use WikiData in my work and WikiData is one of the most useful public knowledge bases. I have both DBPedia and WikiData Sparql endpoints in the example code that we will look at later, with the WikiData endpoint comment out. You can try manually querying WikiData at the WikiData SPARL endpoint. For example, you might explore the WikiData URI for the person concept using:

\n\n

select ?p ?o where {\n <http://www.wikidata.org/entity/Q215627> ?p ?o .\n} limit 10\n

\n\n\n\n

For the rest of this chapter we will just use DBPedia or data copied from DBPedia.

\n\n

After looking an interactive session using the example program for this chapter we will look at the implementation.

\n\n

\nEntity Types Handled by KGN

\n\n

To keep this example simple we handle just three entity types:

\n\n

People
Organizations
Places

\n\n

In addition to finding detailed information for people, organizations, and places we will also search for relationships between entities. This search process consists of generating a series of SPARQL queries and calling the DBPedia SPARQL endpoint.

\n\n

Before we design and write the code, I want to show you sample output for our example program:

\n\n

(kgn {:People [\"Bill Gates\" \"Steve Jobs\" \"Melinda Gates\"]\n      :Organization [\"Microsoft\"]\n      :Place        [\"California\"]})\n

\n\n\n\n

The output (with some text shortened) is:

\n\n

{:entity-summaries\n ((\"Bill Gates\"\n   \"http://dbpedia.org/resource/Bill_Gates\"\n   \"William Henry Gates III (born October 28, 1955) is an American business magnate,\\\n software developer, investor, and philanthropist. He is best known as the co-founde\\\nr of Microsoft Corporation. During his career...\")\n  (\"Steve Jobs\"\n   \"http://dbpedia.org/resource/Steve_Jobs\"\n   \"Steven Paul Jobs (; February 24, 1955 – October 5, 2011) was an American busines\\\ns magnate, industrial designer, investor, and media proprietor. He was the chairman,\\\n chief executive officer (CEO), and co-founder of Apple Inc., the chairman and major\\\nity shareholder of Pixar...\")\n  (\"Melinda Gates\"\n   \"http://dbpedia.org/resource/Melinda_Gates\"\n   \"Melinda Ann Gates (née French; August 15, 1964) is an American philanthropist an\\\nd a former general manager at Microsoft. In 2000, she co-founded the Bill & Melinda \\\nGates Foundation with her husband Bill Gates...\")\n  (\"Microsoft\"\n   \"http://dbpedia.org/resource/Microsoft\"\n   \"Microsoft Corporation () is an American multinational technology company with he\\\nadquarters in Redmond, Washington. It develops, manufactures, licenses, supports, an\\\nd sells computer software...\")\n  (\"California\"\n   \"http://dbpedia.org/resource/California\"\n   \"California is a state in the Pacific Region of the United States. With 39.5 mill\\\nion residents across ...\")),\n :discovered-relationships\n (([\"<http://dbpedia.org/resource/Bill_Gates>\"\n    \"<http://dbpedia.org/property/spouse>\"\n    \"<http://dbpedia.org/resource/Melinda_Gates>\"]\n   [\"<http://dbpedia.org/resource/Melinda_Gates>\"\n    \"<http://dbpedia.org/property/spouse>\"\n    \"<http://dbpedia.org/resource/Bill_Gates>\"])\n  ([\"<http://dbpedia.org/resource/Bill_Gates>\"\n    \"<http://dbpedia.org/ontology/knownFor>\"\n    \"<http://dbpedia.org/resource/Microsoft>\"]\n   [\"<http://dbpedia.org/resource/Microsoft>\"\n    \"<http://dbpedia.org/property/founders>\"\n    \"<http://dbpedia.org/resource/Bill_Gates>\"])\n  ([\"<http://dbpedia.org/resource/Steve_Jobs>\"\n    \"<http://dbpedia.org/ontology/birthPlace>\"\n    \"<http://dbpedia.org/resource/California>\"]))}\n

\n\n\n\n

Note that the output from the function kgn is a map containing two keys: :entity-summaries and :discovered-relationships.

\n\n

\nKGN Implementation

\n\n

The example application works processing a list or Person, Place, and Organization names. We generate SPARQL queries to DBPedia to find information about the entities and relationships between them.

\n\n

Since the DBPedia queries are time consuming, I created a tiny subset of DBPedia in the file dbpedia_sample.nt and load it into a RDF data store like GraphDB or Fuseki running on my laptop. This local setup is especially helpful during development when the same queries are repeatedly used for testing. If you don’t modify the file sparql.clj then by default the public DBPedia SPARQL endpoint will be used.

\n\n

The Clojure and Java files from the example in the last chapter were copied un-changed to the current example and the project.clj file contains the same dependencies as we used earlier:

\n\n

 1 (defproject knowledge_graph_navigator_clj \"0.1.0-SNAPSHOT\"\n 2   :description \"Knowledge Graph Navigator\"\n 3   :url \"https://markwatson.com\"\n 4   :license\n 5   {:name\n 6    \"EPL-2.0 OR GPL-2+ WITH Classpath-exception-2.0\"\n 7    :url  \"https://www.eclipse.org/legal/epl-2.0/\"}\n 8   :source-paths      [\"src\"]\n 9   :java-source-paths [\"src-java\"]\n10   :javac-options     [\"-target\" \"1.8\" \"-source\" \"1.8\"]\n11   :dependencies [[org.clojure/clojure \"1.10.1\"]\n12                  [clj-http \"3.10.3\"]\n13                  [com.cemerick/url \"0.1.1\"]\n14                  [org.clojure/data.csv \"1.0.0\"]\n15                  [org.clojure/data.json \"1.0.0\"]\n16                  [org.clojure/math.combinatorics \"0.1.6\"]\n17                  [org.apache.derby/derby \"10.15.2.0\"]\n18                  [org.apache.derby/derbytools \"10.15.2.0\"]\n19                  [org.apache.derby/derbyclient\n20                   \"10.15.2.0\"]\n21                  [org.apache.jena/apache-jena-libs\n22                   \"3.17.0\" :extension \"pom\"]]\n23   :repl-options\n24   {:init-ns knowledge-graph-navigator-clj.kgn}\n25   :main ^:skip-aot knowledge-graph-navigator-clj.kgn)\n

\n\n\n\n

I copied the code from the last chapter into this project to save readers from needing to lein install the project in the last chapter. We won’t look at that code again here.

\n\n

This example is contained in several source files. We will start at the low-level code in sparql.clj. You can edit lines 10-11 if you want to change which SPARQL libraries and endpoints you want to use. There are utility functions for using DBPedia (lines 13-20), the free version of GraphDB (lines 22-35), and a top level function sparql-endpoint that can be configured to use the options you can change in lines 10-11. I have a top level wrapper function sparql-endpoint so the remainder of the example works without modification with all options. Lines 52-57 is a small main function to facilitate working with this file in isolation.

\n\n

 1 (ns knowledge-graph-navigator-clj.sparql\n 2   (:require [clj-http.client :as client])\n 3   (:require clojure.stacktrace)\n 4   (:require [cemerick.url :refer (url-encode)])\n 5   (:require [clojure.data.csv :as csv])\n 6   (:require [semantic-web-jena-clj.core :as jena]))\n 7 \n 8 ;; see https://github.com/mark-watson/clj-sparql\n 9 \n10 (def USE-LOCAL-GRAPHDB false)\n11 (def USE-CACHING true) ;; use Jena wrapper\n12 \n13 (defn dbpedia [sparql-query]\n14   (let [q\n15         (str\n16           \"https://dbpedia.org//sparql?output=csv&query=\"\n17           (url-encode sparql-query))\n18         response (client/get q)\n19         body (:body response)]\n20     (csv/read-csv body)))\n21 \n22 (defn- graphdb-helper [host port graph-name sparql-query]\n23   (let [q\n24         (str host \":\" port \"/repositories/\" graph-name\n25            \"?query=\" (url-encode sparql-query))\n26         response (client/get q)\n27         body (:body response)]\n28     (csv/read-csv body)))\n29 \n30 (defn graphdb\n31   ([graph-name sparql-query]\n32   (graphdb-helper\n33     \"http://127.0.0.1\" 7200 graph-name sparql-query))\n34   ([host port graph-name sparql-query]\n35     (graphdb-helper host port graph-name sparql-query)))\n36 \n37 (defn sparql-endpoint [sparql-query]\n38   (try\n39     (if USE-LOCAL-GRAPHDB\n40       (graphdb \"dbpedia\" sparql-query)\n41       (if USE-CACHING\n42         (jena/query-dbpedia sparql-query)\n43         (dbpedia sparql-query)))\n44     (catch Exception e\n45       (do\n46         (println\n47           \"WARNING: query failed:\\n\" sparql-query)\n48         (println (.getMessage e))\n49         (clojure.stacktrace/print-stack-trace e)\n50         []))))\n51 \n52 (defn -main\n53   \"SPARQL example\"\n54   [& _]\n55   (println\n56     (sparql-endpoint\n57       \"select * { ?s ?p ?o } limit 10\")))\n

\n\n\n\n

The next source file sparql_utils.clj contains one function that loads a SPARQL template file and performs variable substitutions from a map:

\n\n

 1 (ns knowledge-graph-navigator-clj.sparql-utils)\n 2 \n 3 (defn sparql_template\n 4   \"open SPARQL template file and perform\n 5    variable substitutions\"\n 6   [template-fpath substitution-map]\n 7   (let [template-as-string (slurp template-fpath)]\n 8     (clojure.string/replace\n 9       template-as-string\n10       (re-pattern\n11         ; create a regex pattern of quoted replacements \n12         ; separated by |\n13         ; this code is derived from a stackoverflow\n14         ; example by user bmillare\n15         (apply\n16           str\n17           (interpose\n18             \"|\"\n19             (map\n20               (fn [x] (java.util.regex.Pattern/quote x))\n21               (keys substitution-map)))))\n22       substitution-map)))\n

\n\n\n\n

The next source file entities_by_name.clj provides the functionality of finding DBPedia entity URIs for names of entities, for example “Steve Jobs.” The heart of this functionality is one SPARQL query template that is used to look up URIs by name; in this example, the name is hard-wired to “Steve Jobs”. The file entities_by_name.sparql contains:

\n\n

 1 select distinct ?s ?comment where {\n 2     ?s <http://www.w3.org/2000/01/rdf-schema#label>\n 3             \"<NAME>\"@en .\n 4     ?s <http://www.w3.org/2000/01/rdf-schema#comment>\n 5             ?comment  .\n 6     FILTER  (lang(?comment) = \"en\") .\n 7     ?s\n 8         <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>\n 9         <ENTITY_TYPE> .\n10 }\n

\n\n\n\n

The function dbpedia-get-entities-by-name takes two arguments name and dbpedia-type where name was set to “Steve Jobs” and dbpedia-type was set to the URI:

\n\n

1 <http://dbpedia.org/ontology/Person>\n

\n\n\n\n

in the SPARQL query. The FILTER statement on line 6 is used to discard all string values that are not tagged to be English language (“en”).

\n\n

This SPARQL query template file is used in lines in lines 9-11:

\n\n

 1 (ns knowledge-graph-navigator-clj.entities-by-name\n 2   (:require [knowledge-graph-navigator-clj.sparql\n 3              :as sparql])\n 4   (:require [clojure.pprint :as pp])\n 5   (:require clojure.string))\n 6 \n 7 (defn dbpedia-get-entities-by-name [name dbpedia-type]\n 8   (let [sparql-query\n 9         (utils/sparql_template\n10           \"entities_by_name.sparql\"\n11           {\"<NAME>\" name \"<ENTITY_TYPE>\" dbpedia-type})\n12         results (sparql/sparql-endpoint sparql-query)]\n13     results))\n14 \n15 (defn -main\n16   \"test/dev entities by name\"\n17   [& _]\n18   (println\n19     (dbpedia-get-entities-by-name\n20       \"Steve Jobs\"\n21       \"<http://dbpedia.org/ontology/Person>\"))\n22   (println\n23     (dbpedia-get-entities-by-name\n24       \"Microsoft\"\n25       \"<http://dbpedia.org/ontology/Organization>\"))\n26   (pp/pprint\n27     (dbpedia-get-entities-by-name\n28       \"California\"\n29       \"<http://dbpedia.org/ontology/Place>\"))\n30   )\n

\n\n\n\n

The main function in lines 23-38 was useful for debugging the SPARQL query and code and I left it in the example so you can run and test this file in isolation.

\n\n

The last utility function we need is defined in the source file relationships.clj that uses another SPARQL query template file. This SPARQL template file relationships.sparql contains:

\n\n

1 SELECT DISTINCT ?p {\n2     <URI1>\n3        ?p\n4        <URI2> .\n5     FILTER (!regex(str(?p),\"wikiPage\",\"i\"))\n6 } LIMIT 5\n

\n\n\n\n

There are three things to note here. The DISTINCT keyword removes duplicate results, In SPARQL queries URIs are enclosed in < > angle brackets but the brackets are not included in SPARQL query results so the example code adds them. Also, we are looking for all properties that link the two subject/object entity URIs except we don’t want any property URIs that provide human readable results (“follow your nose” to dereference URIs to a human readable format); these property names contain the string “wikiPage” so we filter them out of the results.

\n\n

The map call on lines 13-16 is used to discard the first SPARQL query result that is a list of variable bindings from the SPARQL query.

\n\n

 1 (ns knowledge-graph-navigator-clj.relationships\n 2   (:require [knowledge-graph-navigator-clj.sparql\n 3              :as sparql])\n 4   (:require [clojure.pprint :as pp])\n 5   (:require clojure.string))\n 6 \n 7 (defn dbpedia-get-relationships [s-uri o-uri]\n 8   (let [query\n 9         (utils/sparql_template\n10           \"relationships.sparql\"\n11           {\"<URI1>\" s-uri \"<URI2>\" o-uri})\n12         results (sparql/sparql-endpoint query)]\n13     (map\n14       (fn [u] (clojure.string/join \"\" [\"<\" u \">\"]))\n15         ;;discard SPARQL variable name p (?p):\n16         (second results)))) \n17 \n18 (defn entity-results->relationship-links\n19   [uris-no-brackets]\n20   (let [uris (map\n21                (fn [u]\n22                  (clojure.string/join \"\" [\"<\" u \">\"]))\n23                uris-no-brackets)\n24         relationship-statements (atom [])]\n25     (doseq [e1 uris]\n26       (doseq [e2 uris]\n27         (if (not (= e1 e2))\n28           (let [l1 (dbpedia-get-relationships e1 e2)\n29                 l2 (dbpedia-get-relationships e2 e1)]\n30             (doseq [x l1]\n31               (let [a-tuple [e1 x e2]]\n32                 (if (not\n33                       (. @relationship-statements\n34                         contains a-tuple))\n35                   (reset! relationship-statements\n36                     (cons a-tuple\n37                           @relationship-statements))\n38                   nil))\n39             (doseq [x l2]\n40               (let [a-tuple [e2 x e1]]\n41                 (if (not\n42                       (. @relationship-statements\n43                         contains a-tuple))\n44                   (reset! relationship-statements\n45                     (cons a-tuple\n46                           @relationship-statements))\n47                   nil)))))\n48           nil)))\n49     @relationship-statements))\n50 \n51 (defn -main\n52   \"dev/test entity relationships code\"\n53   [& _]\n54   (println\n55     \"Testing entity-results->relationship-links\")\n56   (pp/pprint\n57     (entity-results->relationship-links\n58       [\"http://dbpedia.org/resource/Bill_Gates\"\n59        \"http://dbpedia.org/resource/Microsoft\"])))\n

\n\n\n\n

The function entity-results->relationship-links (lines 18-49) takes a list of entity URIs (without the angle brackets) and if there are N input URIs it then generates SPARQL queries for all O(N^2) combinations of choosing two entities at a time.

\n\n

The last source file kgn.clj contains the main function for this application. We use the Clojure library clojure.math.combinatorics to calculate all combinations of entity URIs, taken two at a time. In lines 11-17 we map entity type symbols to the DBPedia entity type URI for the symbol.

\n\n

There are two parts to the main function kgn:

\n\n

Lines 24-39 collects comment descriptions for each input entity.
Lines 40-50 find, for each entity URI pair, possible relationships between entities.

\n\n

Function kgn returns a map of summaries and discovered entity relationships that we saw listed early in this chapter.

\n\n

 1 (ns knowledge-graph-navigator-clj.kgn\n 2   (:require\n 3     [knowledge-graph-navigator-clj.entities-by-name\n 4      :as entity-name])\n 5   (:require\n 6     [knowledge-graph-navigator-clj.relationships\n 7      :as rel])\n 8   (:require [clojure.math.combinatorics :as combo])\n 9   (:require [clojure.pprint :as pp]))\n10 \n11 (def entity-map\n12   {:People\n13    \"<http://dbpedia.org/ontology/Person>\"\n14    :Organization\n15    \"<http://dbpedia.org/ontology/Organization>\"\n16    :Place\n17    \"<http://dbpedia.org/ontology/Place>\"})\n18 \n19 (defn kgn\n20   \"Top level function for the KGN library.\n21    Inputs: a map with keys Person, Place, and\n22    Organization. values list of names\"\n23   [input-entity-map]\n24   (let [entities-summary-data\n25         (filter\n26           ;; get rid of empty SPARQL results:\n27           (fn [x] (> (count x) 1))\n28           (mapcat    ;; flatten just top level\n29             identity\n30             (for [entity-key (keys input-entity-map)]\n31               (for [entity-name\n32                     (input-entity-map entity-key)]\n33                 (cons\n34                   entity-name\n35                   (second\n36                     (entity-name/dbpedia-get-entities-by-name \n37                      entity-name\n38                      (entity-map entity-key))))))))\n39         entity-uris (map second entities-summary-data)\n40         combinations-by-2-of-entity-uris\n41         (combo/combinations entity-uris 2)\n42         discovered-relationships\n43         (filter\n44           (fn [x] (> (count x) 0))\n45           (for [pair-of-uris\n46                 combinations-by-2-of-entity-uris]\n47             (seq\n48               (rel/entity-results->relationship-links\n49                 pair-of-uris))))]\n50     {:entity-summaries entities-summary-data\n51      :discovered-relationships\n52      discovered-relationships}))\n53 \n54 (defn -main\n55   \"Main function for KGN example\"\n56   [& _]\n57   (let [results\n58         (kgn\n59           {:People\n60            [\"Bill Gates\" \"Steve Jobs\" \"Melinda Gates\"]\n61            :Organization [\"Microsoft\"]\n62            :Place        [\"California\"]})]\n63     (println \" -- results:\") (pp/pprint results)))\n

\n\n\n\n

This KGN example was hopefully both interesting to you and simple enough in its implementation to use as a jumping off point for your own projects.

\n\n

I had the idea for the KGN application because I was spending quite a bit of time manually setting up SPARQL queries for DBPedia (and other public sources like WikiData) and I wanted to experiment with partially automating this process. I have experimented with versions of KGN written in Java, Hy language (Lisp running on Python that I wrote a short book on), Swift, and Common Lisp and all four implementations take different approaches as I experimented with different ideas.

\n\n\n

\nUsing the OpenAI APIs

\n\n

I have been working as an artificial intelligence practitioner since 1982 and the capability of the beta OpenAI APIs is the most impressive thing that I have seen (so far!) in my career. These APIs use the GPT-4 model.

\n\n

I recommend reading the online documentation for the APIs to see all the capabilities of the OpenAI APIs.

\n\n

Let’s start by jumping into the example code.

\n\n

The library that I wrote for this chapter supports three functions: completing text, summarizing text, and answering general questions. The single OpenAI model that the OpenAI APIs use is fairly general purpose and can perform tasks like:

\n\n

Generate cooking directions when given an ingredient list.
Grammar correction.
Write an advertisement from a product description.
Generate spreadsheet data from data descriptions in English text.

\n\n

Given the examples from https://platform.openai.com (will require you to login) and the Clojure examples here, you should be able to modify my example code to use any of the functionality that OpenAI documents.

\n\n

We will look closely at the function completions and then just look at the small differences to the other two example functions. The definitions for all three exported functions are kept in the file src/openai_api/core.clj*. You need to request an API key (I had to wait a few weeks to receive my key) and set the value of the environment variable OPENAI_KEY to your key. You can add a statement like:

\n\n

export OPENAI_API_KEY=sa-hdffds7&dhdhsdgffd\n

\n\n\n\n

to your .profile or other shell resource file. Here the API token “sa-hdffds7&dhdhsdgffd” is made up - that is not my API token.

\n\n

When experimenting with OpenAI APIs it is often start by using the curl utility. An example curl command line call to the beta OpenAI APIs is (note: this CURL example uses an earlier API):

\n\n

 1 curl https://api.openai.com/v1/chat/completions -H \"Content-Type: application/json\" \\\n 2 -H \"Authorization: Bearer $OPENAI_API_KEY\"   -d '{\n 3     \"model\": \"gpt-3.5-turbo\",\n 4     \"messages\": [\n 5       {\n 6         \"role\": \"system\",\n 7         \"content\": \"You are an assistant, skilled in explaining complex programming \\\n 8 and other technical problems.\"\n 9       },\n10       {\n11         \"role\": \"user\",\n12         \"content\": \"Write a Python function foo to add two argument\"\n13       }\n14     ]\n15   }'\n

\n\n\n\n

Output might look like this:

\n\n

 1 {\n 2   \"id\": \"chatcmpl-8nqUrlNsCPQgUkSIjW7ytvN5GlH3C\",\n 3   \"object\": \"chat.completion\",\n 4   \"created\": 1706890561,\n 5   \"model\": \"gpt-3.5-turbo-0613\",\n 6   \"choices\": [\n 7     {\n 8       \"index\": 0,\n 9       \"message\": {\n10         \"role\": \"assistant\",\n11         \"content\": \"Certainly! Here is a Python function named `foo` that takes two \\\n12 arguments `a` and `b` and returns their sum:\\n\\n```python\\ndef foo(a, b):\\n    retur\\\n13 n a + b\\n```\\n\\nTo use this function, simply call it and pass in two arguments:\\n\\n`\\\n14 ``python\\nresult = foo(3, 5)\\nprint(result)  # Output: 8\\n```\\n\\nIn this example, `r\\\n15 esult` will store the sum of `3` and `5`, which is `8`. You can change the arguments\\\n16  `a` and `b` to any other numbers to get different results.\"\n17       },\n18       \"logprobs\": null,\n19       \"finish_reason\": \"stop\"\n20     }\n21   ],\n22   \"usage\": {\n23     \"prompt_tokens\": 35,\n24     \"completion_tokens\": 127,\n25     \"total_tokens\": 162\n26   },\n27   \"system_fingerprint\": null\n28 }\n

\n\n\n\n

All of the OpenAI APIs expect JSON data with query parameters. To use the completion API, we set values for prompt. We will look at several examples later.

\n\n

The file src/openai_api/core.clj contains the implementation of our wrapper library using Werner Kok’s library:

\n\n

 1 (ns openai-api.core\n 2   (:require\n 3    [wkok.openai-clojure.api :as api])\n 4   (:require [clj-http.client :as client])\n 5   (:require [clojure.data.json :as json]))\n 6 \n 7 (def model2 \"gpt-4o-mini\")\n 8 \n 9 (def api-key (System/getenv \"OPENAI_API_KEY\"))\n10 \n11 (defn completions [prompt]\n12   (let [url \"https://api.openai.com/v1/chat/completions\"\n13         headers {\"Authorization\" (str \"Bearer \" api-key)\n14                  \"Content-Type\" \"application/json\"}\n15         body {:model model2\n16               :messages [{:role \"user\" :content prompt}]}\n17         response (client/post url {:headers headers\n18                                    :body (json/write-str body)})]\n19     ;;(println (:body response))\n20     (get\n21      (get\n22       (first\n23        (get\n24         (json/read-str (:body response)  :key-fn keyword)\n25         :choices))\n26       :message)\n27      :content)))\n28 \n29 (defn summarize [text]\n30   (completions (str \"Summarize the following text:\\n\\n\" text)))\n31 \n32 (defn embeddings [text]\n33   (try\n34     (let* [body\n35            (str\n36             \"{\\\"input\\\": \\\"\"\n37             (clojure.string/replace\n38              (clojure.string/replace text #\"[\\\" \\n :]\" \" \")\n39              #\"\\s+\" \" \")\n40             \"\\\", \\\"model\\\": \\\"text-embedding-ada-002\\\"}\")\n41            json-results\n42            (client/post\n43             \"https://api.openai.com/v1/embeddings\"\n44             {:accept :json\n45              :headers\n46              {\"Content-Type\"  \"application/json\"\n47               \"Authorization\" (str \"Bearer \" api-key)}\n48              :body   body})]\n49           ((first ((json/read-str (json-results :body)) \"data\")) \"embedding\"))\n50     (catch Exception e\n51       (println \"Error:\" (.getMessage e))\n52       \"\")))\n53 \n54 (defn dot-product [a b]\n55   (reduce + (map * a b)))\n

\n\n\n\n

Note that the OpenAI models are stochastic. When generating output words (or tokens), the model assigns probabilities to possible words to generate and samples a word using these probabilities. As a simple example, suppose given prompt text “it fell and”, then the model could only generate three words, with probabilities for each word based on this prompt text:

\n\n

the 0.9
that 0.1
a 0.1

\n\n

The model would emit the word the 90% of the time, the word that 10% of the time, or the word a 10% of the time. As a result, the model can generate different completion text for the same text prompt. Let’s look at some examples using the same prompt text. Notice the stochastic nature of the returned results:

\n\n

 1 $ lein repl\n 2 openai-api.core=> (openai-api.core/completions \"He walked to the river\")\n 3 \" and breathed in the new day, looking out to the lake where the Mire was displacing\\\n 4  the Wold by its\"\n 5 openai-api.core=> (openai-api.core/completions \"He walked to the river\")\n 6 \". He waded in, not caring about his expensive suit pants. He was going to do this r\\\n 7 ight, even if\"\n 8 openai-api.core=> (openai-api.core/completions \"He walked to the river\")\n 9 \" every day. The salty air puffed through their pores. He had enjoyed her company. M\\\n10 aybe he did need a companion\"\n

\n\n\n\n

The function summarize is very similar to the function completions except I changed the system prompt string. Here is some example output:

\n\n

 1 openai-api.core=> (def some-text\n 2              #_=>   \"Jupiter is the fifth planet from the Sun and the largest in the\\\n 3  Solar System. It is a gas giant with a mass one-thousandth that of the Sun, but two\\\n 4 -and-a-half times that of all the other planets in the Solar System combined. Jupite\\\n 5 r is one of the brightest objects visible to the naked eye in the night sky, and has\\\n 6  been known to ancient civilizations since before recorded history. It is named afte\\\n 7 r the Roman god Jupiter.[19] When viewed from Earth, Jupiter can be bright enough fo\\\n 8 r its reflected light to cast visible shadows,[20] and is on average the third-brigh\\\n 9 test natural object in the night sky after the Moon and Venus.\")\n10 #'openai-api.core/some-text\n11 \n12 openai-api.core=> (openai-api.core/summarize some-text openai-api.core=> (openai-api\\\n13 .core/summarize some-text)\n14 \"Jupiter is classified as a gas giant along with Saturn, Uranus, and Neptune. Jupite\\\n15 r is composed primarily of gaseous and liquid matter.[21] It is the largest of the f\\\n16 our giant planets in the Solar System and hence its largest planet. It has a diamete\\\n17 r of 142,984 km at its equator, which is 0.11 times the diameter of Earth. Jupiter i\\\n18 s a gas giant because the mass of the planet\"\n

\n\n\n\n

In addition to reading the OpenAI API documentation you might want to read general material on the use of OpenAI’s GPT-4 model.

\n\n\n

\nUsing the Google Gemini 2.5 Flash APIs

\n\n

August 10, 2025 note: I added an example client using Google’s Java Gemini SDK in the last section of this chapter. The earlier example uses the Gemini REST interface using only low-level Clojure libraries.

\n\n

We used the OpenAI LLM APIs in the last chapter and now we provide a similar example using Google’s gemini-2.5-flash model.

\n\n

I recommend reading Google’s online documentation for the APIs to see all the capabilities of the OpenAI APIs.

\n\n

\nTest Code for REST Interface and Sample Test Output

\n\n

Before we look at the example code, let’s look at an example code running it and later sample output:

\n\n

 1 (ns gemini-api.core-test\n 2   (:require [clojure.test :refer :all]\n 3             [gemini-api.core :refer :all]))\n 4 \n 5 (def some-text\n 6   \"Jupiter is the fifth planet from the Sun and the largest in the Solar System. It \\\n 7 is a gas giant with a mass one-thousandth that of the Sun, but two-and-a-half times \\\n 8 that of all the other planets in the Solar System combined. Jupiter is one of the br\\\n 9 ightest objects visible to the naked eye in the night sky, and has been known to anc\\\n10 ient civilizations since before recorded history. It is named after the Roman god Ju\\\n11 piter.[19] When viewed from Earth, Jupiter can be bright enough for its reflected li\\\n12 ght to cast visible shadows,[20] and is on average the third-brightest natural objec\\\n13 t in the night sky after the Moon and Venus.\")\n14 \n15 (deftest completions-test\n16   (testing \"gemini completions API\"\n17     (let [results\n18           (gemini-api.core/generate-content \"He walked to the river\")]\n19       (println results))))\n20 \n21 (deftest summarize-test\n22   (testing \"gemini summarize API\"\n23     (let [results\n24           (gemini-api.core/summarize\n25            some-text)]\n26       (println results))))\n27 \n28 (deftest question-answering-test\n29   (testing \"gemini question-answering API\"\n30     (let [results\n31           (gemini-api.core/generate-content\n32            \"Where is the Valley of Kings?\"\n33            )]\n34       (println results))))\n

\n\n\n\n

The output (edited for brevity) looks like this:

\n\n

 1 $ lein test\n 2 \n 3 **Adding detail:**\n 4 \n 5 *   He walked slowly to the river.\n 6 *   He walked to the river, his head down.\n 7 *   He walked to the river, eager to cool off.\n 8 *   He walked to the river, his boots crunching on the gravel path.\n 9 \n10 **Adding context:**\n11 \n12 *   Tired of the city, he walked to the river.\n13 *   After the argument, he walked to the river.\n14 *   He walked to the river, seeking solace in its gentle flow.\n15 \n16 **Setting the scene:**\n17 \n18 *   The sun beat down as he walked to the river.\n19 *   A cool breeze rustled the leaves as he walked to the river.\n20 *   The air smelled of damp earth as he walked to the river.\n21 \n22 **Making it part of a longer narrative:**\n23 \n24 *   He walked to the river and sat down on the bank, watching the water flow by.\n25 *   He walked to the river, but when he arrived, he hesitated to go further.\n26 *   He walked to the river, knowing it was the only place he could truly be alone.\n27 \n28 \n29 Jupiter, the fifth planet from the Sun, is the largest planet in our solar system, a\\\n30  gas giant exceeding the mass of all other planets combined. Easily visible to the n\\\n31 aked eye, it's been observed since ancient times and named after the Roman god Jupit\\\n32 er. Its brightness makes it a prominent object in the night sky, often third brighte\\\n33 st after the Moon and Venus.\n34 \n35 \n36 The Valley of the Kings is located on the west bank of the Nile River, near the city\\\n37  of Luxor (ancient Thebes) in Egypt.\n

\n\n\n\n

\nGemini API Library Implementation for REST Interface

\n\n

Here is the library implementation, we will discuss the code after the listing:

\n\n

 1 (ns gemini-api.core\n 2   (:require [clj-http.client :as client])\n 3   (:require [clojure.data.json :as json]))\n 4 \n 5 (def model \"gemini-2.0-flash\") ; or gemini-1.5-pro, etc.\n 6 \n 7 (def google-api-key (System/getenv \"GOOGLE_API_KEY\"))\n 8 \n 9 (def base-url \"https://generativelanguage.googleapis.com/v1beta/models\")\n10 \n11 (defn generate-content [prompt]\n12   (let [url (str base-url \"/\" model \":generateContent?key=\" google-api-key)\n13         headers {\"Content-Type\" \"application/json\"}\n14         body {:contents [{:parts [{:text prompt}]}]}]\n15     (try\n16       (let [response (client/post url {:headers headers\n17                                      :body (json/write-str body)\n18                                      :content-type :json\n19                                      :accept :json})\n20             parsed-response (json/read-str (:body response) :key-fn keyword)\n21             candidates (:candidates parsed-response)]\n22         (if (seq candidates)\n23           (let [text (get-in (first candidates) [:content :parts 0 :text])]\n24             (if text\n25               text\n26               (do\n27                 (println \"No text found in response structure:\" parsed-response)\n28                 nil)))\n29           (do\n30             (println \"No candidates found in response:\" parsed-response)\n31             nil)))\n32       (catch Exception e\n33            (println \"Error making request:\" (.getMessage e))\n34            (when-let [response-body (-> e ex-data :body)]\n35              (println \"Error response body:\" response-body))\n36            nil))))\n37 \n38 (defn summarize [text]\n39   (generate-content (str \"Summarize the following text:\\n\\n\" text)))\n

\n\n\n\n

This Clojure code is designed to interact with Google’s Gemini API to generate text content and specifically to summarize text. It sets up the necessary components to communicate with the API, including importing libraries for making HTTP requests and handling JSON data. Crucially, it retrieves your Google API key from an environment variable, ensuring secure access. The code also defines configuration like the Gemini model to use and the base API endpoint URL. It’s structured within a Clojure namespace for organization and includes basic error handling and debug printing to aid in development and troubleshooting.

\n\n

The core of the functionality lies in the generate-content function. This function takes a text prompt as input, constructs the API request URL with the chosen model and your API key, and then sends this request to Google’s servers. It handles the API response, parsing the JSON result to extract the generated text content. The code also checks for potential errors, both in the API request itself and in the structure of the response, providing informative error messages if something goes wrong. Building on this, the function summarize offers a higher-level interface, taking text as input and using generate-content to send a “summarize” prompt to the API, effectively providing a convenient way to get text summaries using the Gemini models.

\n\n

\n(New) Gemini Client Library Using Google’s Java SDK for Gemini

\n\n

The code for this section can be found in the directory ** Clojure-AI-Book-Code/gemini_java_api**.

\n\n

We test code that is almost identical to that used earlier for the REST interface library so we don’t list the test code here.

\n\n

Here is the library implementation:

\n\n

 1 (ns gemini-java-api.core\n 2   (:import (com.google.genai Client)\n 3            (com.google.genai.types GenerateContentResponse)))\n 4 \n 5 (def DEBUG false)\n 6 \n 7 (def model \"gemini-2.5-flash\") ; or gemini-2.5-pro, etc.\n 8 (def google-api-key (System/getenv \"GOOGLE_API_KEY\")) ; Make sure to set this env va\\\n 9 riable\n10 \n11 (defn generate-content\n12   \"Sends a prompt to the Gemini API using the specified model and returns\n13    the text response.\"\n14   [prompt]\n15   (let [client (Client.)\n16         ^GenerateContentResponse resp\n17         (.generateContent (.models client)\n18                           model\n19                           prompt\n20                           nil)]\n21     (when DEBUG\n22       (println (.text resp))\n23       (when-let [headers\n24                  (some-> resp\n25                      .sdkHttpResponse (.orElse nil)\n26                      .headers        (.orElse nil))]\n27         (println \"Response headers:\" headers)))\n28     (.text resp)))\n29 \n30 (defn summarize [text]\n31   (generate-content (str \"Summarize the following text:\\n\\n\" text)))\n

\n\n\n\n

I used the previous REST interface library implementation for over one year but now I have switched to using this shorter implementation that uses interop with the Java Gemini SDK.

\n\n

\nGemini APIs Wrap Up

\n\n

The Gemini APIs also support a message-based API for optionally adding extra context data, configuration data, and AI safety settings. The example code using the REST interface provides a simple completion style of interacting with the Gemini models.

\n\n

If you use my Java SDK example library you can clone it in your own projects and optionally use those features of the Java SDK that you might find useful. Reference: https://github.com/googleapis/java-genai.

\n\n\n

\nQuestion Answering Using OpenAI APIs and a Local Embeddings Vector Database

\n\n

The examples in this chapter are inspired by the Python LangChain and LlamaIndex projects, with just the parts I need for my projects written from scratch in Clojure. I wrote a Python book “LangChain and LlamaIndex Projects Lab Book: Hooking Large Language Models Up to the Real World Using GPT-3, ChatGPT, and Hugging Face Models in Applications” in March 2023: https://leanpub.com/langchain that you might also be interested in.

\n\n

The GitHub repository for this example can be found here: https://github.com/mark-watson/Clojure-AI-Book-Code/tree/main/docs_qa. We will be using an OpenAI API wrapper from the last chapter that you should have installed with lein install on your local system.

\n\n

We use two models in this example: a vector embedding model\nand a text completion model (see bottom of this file).\nThe vector embedding model is used to generate a vector embeddings for “chunks” of input documents. Here we break documents into 200 character chunks and calculate a vector embedding for each chunk. A vector dot product between two embedding vectors tells us how semantically similar two chunks of text are. We will also calculate embedding vectors for user queries and use those to find chunks that might be useful for answering the query. Useful chunks are concatenated to for a prompt for a GPT text completion model.

\n\n

\nImplementing a Local Vector Database for Document Embeddings

\n\n

For interactive development we will read all text files in the data directory, create a global variable doc-strings containing the string contents of each file, and then create another global variable doc-chunks where each document string has been broken down into smaller chunks. For each chunk, we will call the OpenAI API for calculating document embeddings and store the embeddings for each chunk in the global variable embeddings.

\n\n

When we want to query the documents in the data directory, we then calculate an embedding vector for the query and using a dot product calculation, efficiently find all chunks that are semantically similar to the query. The original text for these matching chunks is then combined with the user’s query and passed to an OpenAI API for text completion.

\n\n

For this example, we use an in-memory store of embedding vectors and chunk text. A text document is broken into smaller chunks of text. Each chunk is embedded and stored in the embeddingsStore. The chunk text is stored in the chunks array. The embeddingsStore and chunks array are used to find the most similar chunk to a prompt. The most similar chunk is used to generate a response to the prompt.

\n\n

\nCreate Local Embeddings Vectors From Local Text Files with OpenAI GPT APIs

\n\n

The code for handling OpenAI API calls is in the library openai_api in the GitHub repository for this book. You need to install that example project locally using:

\n\n

1 lien install\n

\n\n\n\n

The code using text embeddings is located in src/docs_qa/vectordb.clj:

\n\n

 1 (ns docs-qa.vectordb)\n 2 \n 3 (defn string-to-floats [s]\n 4   (map\n 5     #(Float/parseFloat %)\n 6     (clojure.string/split s #\" \")))\n 7 \n 8 (defn truncate-string [s max-length]\n 9   (if (< (count s) max-length)\n10     s\n11     (subs s 0 max-length)))\n12 \n13 (defn break-into-chunks [s chunk-size]\n14   (let [chunks (partition-all chunk-size s)]\n15     (map #(apply str %) chunks)))\n16 \n17 (defn document-texts-from_dir [dir-path]\n18   (map\n19     #(slurp %)\n20     (rest\n21       (file-seq\n22         (clojure.java.io/file dir-path)))))\n23 \n24 (defn document-texts-to-chunks [strings]\n25   (flatten\n26    (map #(break-into-chunks % 200) strings)))\n27 \n28 (def directory-path \"data\")\n29 \n30 (def doc-strings (document-texts-from_dir directory-path))\n31 \n32 (def doc-chunks\n33   (filter\n34     #(> (count %) 40)\n35     (document-texts-to-chunks doc-strings)))\n36 \n37 (def chunk-embeddings\n38   (map #(openai-api.core/embeddings %) doc-chunks))\n39 \n40 (def embeddings-with-chunk-texts\n41   (map vector chunk-embeddings doc-chunks))\n42 \n43 ;;(clojure.pprint/pprint\n44 ;;  (first embeddings-with-chunk-texts))\n

\n\n\n\n

If we uncomment the print statement in the last two lines of code, we see the first embedding vector and its corresponding chunk text:

\n\n

 1 [[-0.011284076\n 2   -0.0110755935\n 3   -0.011531647\n 4   -0.0374746\n 5   -0.0018975098\n 6   -0.0024985236\n 7   0.0057560513 ...\n 8   ]\n 9  \"Amyl alcohol is an organic compound with the formula C 5 H 12 O. All eight isomers\\\n10  of amyl alcohol are known. The most important is isobutyl carbinol, this being the \\\n11 chief constituent of fermentation \"]\n12 ]\n

\n\n\n\n

\nUsing Local Embeddings Vector Database with OpenAI GPT APIs

\n\n

The main application code is in the file src/docs_qa/core.clj:

\n\n

 1 (ns docs-qa.core\n 2   (:require [clojure.java.jdbc :as jdbc]\n 3             [openai-api.core :refer :all]\n 4             [docs-qa.vectordb :refer :all])\n 5   (:gen-class))\n 6 \n 7 (defn best-vector-matches [query]\n 8   (clojure.string/join\n 9    \" .\"\n10    (let [query-embedding\n11          (openai-api.core/embeddings query)]\n12     (map\n13      second\n14      (filter\n15       (fn [emb-text-pair]\n16         (let [emb (first emb-text-pair)\n17               text (second emb-text-pair)]\n18           (> (openai-api.core/dot-product\n19               query-embedding\n20               emb)\n21              0.79)))\n22       docs-qa.vectordb/embeddings-with-chunk-texts)))))\n23 \n24 (defn answer-prompt [prompt]\n25   (openai-api.core/answer-question\n26    prompt))\n27 \n28 (defn -main\n29   []\n30   (println \"Loading text files in ./data/, performing chunking and getting OpenAI em\\\n31 beddings...\")\n32   (answer-prompt \"do nothing\")n ;; force initiation\n33   (print \"...done loading data and getting local embeddings.\\n\")\n34   (loop []\n35   (println \"Enter a query:\")\n36   (let [input (read-line)]\n37     (if (empty? input)\n38       (println \"Done.\")\n39       (do\n40         (let [text (best-vector-matches input)\n41               prompt\n42               (clojure.string/replace\n43                (clojure.string/join\n44                 \"\\n\"\n45                 [\"With the following CONTEXT:\\n\\n\"\n46                 text\n47                 \"\\n\\nANSWER:\\n\\n\"\n48                 input])\n49                #\"\\s+\" \" \")]\n50           (println \"** PROMPT:\" prompt)\n51           (println (answer-prompt prompt)))\n52           (recur))))))\n

\n\n\n\n

The main example function reads the text files in ./data/, chunks the files, and uses the OpenAI APIs to get embeddings for each chunk. The main function then has an infinite loop where you can enter a question about your local documents. The most relevant chunks are identified and turned into a prompt along with your question, the generated prompt and answer to the question are printed. You can enter a control-D to stop the example program:

\n\n

 1 $ lein run\n 2 Loading text files in ./data/, performing chunking and getting OpenAI embeddings...\n 3 ...done loading data and getting local embeddings.\n 4 Enter a query:\n 5 What is Chemistry. How useful, really, are the sciences. Is Amyl alcohol is an organ\\\n 6 ic compound?\n 7 PROMPT: With the following CONTEXT: Amyl alcohol is an organic compound with the for\\\n 8 mula C 5 H 12 O. All eight isomers of amyl alcohol are known. The most important is \\\n 9 isobutyl carbinol, this being the chief constituent of fermentation .een 128 and 132\\\n10  C only being collected. The 1730 definition of the word \"chemistry\", as used by Geo\\\n11 rg Ernst Stahl, meant the art of resolving mixed, compound, or aggregate bodies into\\\n12  their principles .; and of composing such bodies from those principles. In 1837, Je\\\n13 an-Baptiste Dumas considered the word \"chemistry\" to refer to the science concerned \\\n14 with the laws and effects of molecular forces.[16] .This definition further evolved \\\n15 until, in 1947, it came to mean the science of substances: their structure, their pr\\\n16 operties, and the reactions that change them into other substances - a characterizat\\\n17  .ion accepted by Linus Pauling.[17] More recently, in 1998, the definition of \"chem\\\n18 istry\" was broadened to mean the study of matter and the changes it undergoes, as ph\\\n19 rased by Professor Raymond Chang. .ther aggregates of matter. This matter can be stu\\\n20 died in solid, liquid, or gas states, in isolation or in combination. The interactio\\\n21 ns, reactions and transformations that are studied in chemistry are ANSWER: What is \\\n22 Chemistry. How useful, really, are the sciences. Is Amyl alcohol is an organic compo\\\n23 und?\n24 \n25 Chemistry is the science of substances: their structure, their properties, and the r\\\n26 eactions that change them into other substances. Amyl alcohol is an organic compound\\\n27  with the formula C5H12O. All eight isomers of amyl alcohol\n28 Enter a query:\n29 What is the Austrian School of Economics?\n30 PROMPT: With the following CONTEXT: The Austrian School (also known as the Vienna Sc\\\n31 hool or the Psychological School ) is a Schools of economic thought|school of econom\\\n32 ic thought that emphasizes the spontaneous organizing power of the p .rice mechanism\\\n33 . Austrians hold that the complexity of subjective human choices makes mathematical \\\n34 modelling of the evolving market extremely difficult (or Undecidable and advocate a \\\n35 \"laissez faire\" ap .proach to the economy. Austrian School economists advocate the s\\\n36 trict enforcement of voluntary contractual agreements between economic agents, and h\\\n37 old that commercial transactions should be subject t .o the smallest possible imposi\\\n38 tion of forces they consider to be (in particular the smallest possible amount of go\\\n39 vernment intervention). The Austrian School derives its name from its predominantly \\\n40 Au .strian founders and early supporters, including Carl Menger, Eugen von Böhm-Bawe\\\n41 rk and Ludwig von Mises. Economics is the social science that analyzes the productio\\\n42 n, distribution, and consumption of .growth, and monetary and fiscal policy. The pro\\\n43 fessionalization of economics, reflected in the growth of graduate programs on the s\\\n44 ubject, has been described as \"the main change in economics since .essional study; s\\\n45 ee Master of Economics. Economics is the social science that studies the behavior of\\\n46  individuals, households, and organizations (called economic actors, players, or age\\\n47 nts), whe . govern the production, distribution and consumption of goods and service\\\n48 s in an exchange economy.[3] An approach to understanding these processes, through t\\\n49 he study of agent behavior under scarcity, ANSWER: What is the Austrian School of Ec\\\n50 onomics?\n51 \n52 \n53 The Austrian School of Economics is a school of economic thought that emphasizes the\\\n54  spontaneous organizing power of the price mechanism and advocates a \"laissez faire\"\\\n55  approach to the economy. It is named after its predominantly Austrian founders and \\\n56 early supporters, including\n57 Enter a query:\n58 Done.\n

\n\n\n\n

\nWrap Up for Using Local Embeddings Vector Database to Enhance the Use of GPT3 APIs with Local Documents

\n\n

As I write this in May 2023, I have been working almost exclusively with OpenAI APIs for the last year and using the Python libraries for LangChain and LlamaIndex for the last three months.

\n\n

I started writing the examples in this chapter for my own use, implementing a tiny subset of the LangChain and LlamaIndex libraries in Clojure for creating local embedding vector data stores and for interactive chat using my own data.

\n\n\n

\nRunning LLMs Locally Using Ollama

\n\n

In the last two chapters we used cloud services to run LLMs. For my personal research and experimentation I prefer running smaller models locally on my Mac Mini that has 32G of memory. We will use the Ollama system that runs on macOS and Linux (and Windows support is coming soon). Here we use the Mistral 7B LLM. If you don’t have at least 16G of memory on your system then you should consider substituting the model “mistral” in the following examples with Stable LM 2 1.6B that is a state-of-the-art 1.6 billion parameter small language model trained on multilingual data in English, Spanish, German, Italian, French, Portuguese, and Dutch. Use the model file name “stablelm2” in the following examples instead of “mistral”.

\n\n

You need to install Ollama on your system: https://ollama.ai

\n\n

You then need to install the Mistral model (this takes a while the first time, but the model file is cached so future startups are fast):

\n\n

ollama run mistral

\n\n

\nRunning the Example Tests

\n\n

Before we look at the code, you might want to run the example tests first:

\n\n

In one console, run the Ollama REST API service:

\n\n

ollama serve

\n\n

Then run the tests in another console:

\n\n

lein test

\n\n

\nClojure Client Library for the Ollama Service REST APIs

\n\n

The following Clojure code (ollama/src/ollama_api/core.clj) defines a simple API client for interacting with the Ollama REST API text generation service. Here’s a breakdown of its functionality:

\n\n

Dependencies:

\n\n

(:require [clj-http.client :as client]) for HTTP requests.
(:require [clojure.data.json :as json]) for JSON processing.

\n\n

ollama-helper is a private function (indicated by - prefix) used to interact with the Ollama API. It takes body (a JSON string) as an argument and makes a POST request to http://localhost:11434/api/generate with the body, sets the request header to accept JSON and indicates that the content type is JSON, and finally extracts the response from the API and parses the JSON.

\n\n

The completions function takes prompt-text as an argument, constructs a JSON string with the prompt and model details, and finally calls ollama-helper with this JSON string.

\n\n

The summarize function uses the completions function to send a summarization request by creating a new prompt by concatenating the string “Summarize the following text: “ with the original prompt text.

\n\n

The answer-question function also uses the completions function to send a question answering request by creating a new prompt by concatenating the string “Answer the following question: “ with the original prompt text.

\n\n

 1 (ns ollama-api.core\n 2   (:require [clj-http.client :as client])\n 3   (:require [clojure.data.json :as json]))\n 4 \n 5 \n 6 (defn- ollama-helper [body]\n 7   (let [json-results\n 8         (client/post\n 9           \"http://localhost:11434/api/generate\"\n10           {:accept :json\n11            :headers\n12            {\"Content-Type\" \"application/json\"}\n13            :body   body\n14            })]\n15     ((json/read-str (json-results :body)) \"response\")))\n16 \n17 (defn completions\n18   \"Use the Ollama API for text completions\"\n19   [prompt-text]\n20   (let\n21     [body\n22      (str\n23        \"{\\\"prompt\\\": \\\"\" prompt-text\n24        \"\\\", \\\"model\\\": \\\"mistral\\\"\"\n25        \", \\\"stream\\\": false }\"\n26        )]\n27     (ollama-helper body)))\n28 \n29 (defn summarize\n30   \"Use the Ollama API for text summarization\"\n31   [prompt-text]\n32   (completions\n33     (str \"Summarize the following text: \"\n34        prompt-text)))\n35 \n36 (defn answer-question\n37   \"Use the Ollama API for question answering\"\n38   [prompt-text]\n39   (completions\n40     (str \"Answer the following question: \"\n41        prompt-text)))\n

\n\n\n\n

Here are the unit tests:

\n\n

 1 (ns ollama-api.core-test\n 2   (:require [clojure.test :refer :all]\n 3             [ollama-api.core :refer :all]))\n 4 \n 5 (def some-text\n 6   \"Jupiter is the fifth planet from the Sun and the largest in the Solar System. It \\\n 7 is a gas giant with a mass one-thousandth that of the Sun, but two-and-a-half times \\\n 8 that of all the other planets in the Solar System combined. Jupiter is one of the br\\\n 9 ightest objects visible to the naked eye in the night sky, and has been known to anc\\\n10 ient civilizations since before recorded history. It is named after the Roman god Ju\\\n11 piter.[19] When viewed from Earth, Jupiter can be bright enough for its reflected li\\\n12 ght to cast visible shadows,[20] and is on average the third-brightest natural objec\\\n13 t in the night sky after the Moon and Venus.\")\n14 \n15 (deftest completions-test\n16   (testing \"ollama-Ollama completions API\"\n17     (let [results\n18           (ollama-api.core/completions \"He walked to the river\")]\n19       (println results))))\n20 \n21 (deftest summarize-test\n22   (testing \"ollama-Ollama summarize API\"\n23     (let [results\n24           (ollama-api.core/summarize\n25             some-text)]\n26       (println results))))\n27 \n28 \n29 (deftest question-answering-test\n30   (testing \"ollama-Ollama question-answering API\"\n31     (let [results\n32           (ollama-api.core/answer-question\n33             \"Where is the Valley of Kings?\"\n34             )]\n35       (println results))))\n

\n\n\n\n

The output will change each time you run the tests. The output from Large Language Models (LLMs) usually change each time you run the same tests or prompts. This variability stems from several key factors:

\n\n

Stochasticity: LLMs are complex neural networks trained on massive datasets. During training these networks develop internal representations and probabilistic weights that influence their outputs. When generating text LLMs sample from these weights, introducing an inherent element of randomness. This means even with identical inputs and identical LLM weights the same prompt used repeatedly can lead to slightly different outputs.
Temperature: Some LLMs use a temperature parameter to control the “randomness” of their outputs. A higher temperature encourages exploration of less likely but potentially more creative responses, while a lower temperature leads to more deterministic and consistent outputs.
Beam Search vs. Sampling: Different decoding strategies can also impact output variability. Beam search focuses on the most likely sequences, gradually refining them, while sampling explores a wider range of possibilities. Beam search typically leads to less variation compared to sampling, but even within beam search, there can be randomness in how ties are broken when choosing the next word.

\n\n

I edited the following output shortening the output from the text completion test and by adding labels for each test:

\n\n

 1  $ lein test\n 2 \n 3 COMPLETION TEST:\n 4 \n 5 lein test ollama-api.core-test\n 6 He walked to the river, feeling the cool breeze on his skin and the gentle rustling \\\n 7 of leaves in the trees. The sun was just beginning to set, casting a warm orange glo\\\n 8 w across the sky. As he approached the water's edge, he could see the ripples create\\\n 9 d by the gentle flow of the river. He stopped for a moment to take it all in, feelin\\\n10 g a sense of peace and tranquility wash over him.\n11 \n12 As he continued on his journey, he couldn't help but think about how much the world \\\n13 had changed in recent times. The pandemic had brought with it so much uncertainty an\\\n14 d fear, but now, as he stood by the river, he felt grateful to be alive and able to \\\n15 enjoy such simple pleasures. He made a mental note to come back here more often, to \\\n16 take time for himself and to appreciate the beauty of nature....\n17 \n18 SUMMARIZATION TEST:\n19 \n20 Jupiter is a massive gas giant planet located in our solar system. It's the fifth pl\\\n21 anet from the sun and is known for being one of the brightest objects visible to the\\\n22  naked eye at night. With a mass one-thousandth that of the sun, it has a unique pla\\\n23 ce in the cosmos.\n24 \n25 QUESTION ANSWERING TEST:\n26 \n27 The Valley of Kings is located in Egypt, specifically in the region of Giza. It is a\\\n28  valley on the west bank of the Nile River and is known for its abundance of royal t\\\n29 ombs dating back to ancient Egypt's New Kingdom period.\n

\n\n\n\n\n

\nUsing Moonshot’s Kimi K2 Model with Built In $web_search Tool Support

\n\n

Moonshot AI (or “Dark Side of the Moon”) is a prominent Chinese artificial intelligence startup founded in March 2023. The company quickly achieved a multi-billion dollar valuation, notably securing a $1 billion funding round led by Alibaba. Founded by a team with strong academic roots from institutions like Tsinghua University and Carnegie Mellon, Moonshot AI has established itself as one of China’s leading “AI Tigers.” The company’s primary strategic focus is on developing large language models (LLMs) capable of handling exceptionally long context windows, aiming to push the boundaries of what AI can process and comprehend in a single prompt.

\n\n

Their flagship model, Kimi K2, is a state-of-the-art, open-weight language model that has drawn significant attention. It is built on a Mixture-of-Experts (MoE) architecture with one trillion total parameters, of which 32 billion are active during inference, making it both powerful and efficient. Kimi K2 is specifically designed as an “agentic” AI, meaning it’s optimized not just for conversation but for performing complex, multi-step tasks, using tools, and executing code autonomously. With a 128k token context window and benchmark performance that rivals or exceeds leading proprietary models in coding and reasoning tasks, Kimi K2 represents a major milestone for open-source AI.

\n\n

Kimi K2 has built in support for web searching, as the following code example shows. You will need a Moonshot API key from the Moonshot console https://login.moonshot.ai and the model documentation can be found here https://platform.moonshot.ai/docs. If you don’t want to use servers in China, the Kimi K2 model is open source and several US-based providers offer inference services.

\n\n

\nClojure Library Moonshot.ai’s Kimi K2 Model (Including Web Search Tool)

\n\n

The following Clojure code defines a client for interacting with the Moonshot AI API, providing two primary functions for chat completions. The first, completions, performs a basic, single-turn request by sending a user prompt along with a predefined system message to the Kimi 2 model and returns the text content of the model’s response. The second, more advanced function, search, orchestrates a multi-turn, agentic conversation that leverages the model’s built-in web search tool; it initiates a loop that repeatedly calls a private chat helper function, checks if the model’s response is a request to use a tool (“tool_calls”), and if so, constructs and appends the necessary tool-related messages to the conversation history before continuing the loop until the model provides a final content-based answer. The entire namespace relies on the clj-http.client and clojure.data.json libraries for making HTTP POST requests and handling JSON serialization, respectively, while retrieving the required MOONSHOT_API_KEY from system environment variables and including basic error handling for failed API calls.

\n\n

  1 (ns moonshot-api.core\n  2   (:require [clj-http.client :as client]\n  3             [clojure.data.json :as json])\n  4   (:gen-class))\n  5 \n  6 ;; Define the API key, base URL, and model for Moonshot AI\n  7 (def moonshot-api-key (System/getenv \"MOONSHOT_API_KEY\"))\n  8 (def moonshot-base-url \"https://api.moonshot.ai/v1\")\n  9 (def moonshot-model \"kimi-k2-0711-preview\")\n 10 \n 11 (defn completions\n 12   \"Sends promp request to the Moonshot AI chat completions API.\"\n 13   [prompt]\n 14   (if-not moonshot-api-key\n 15     (println \"Error: MOONSHOT_API_KEY environment variable not set.\")\n 16     (try\n 17       (let [url (str moonshot-base-url \"/chat/completions\")\n 18             headers {\"Authorization\" (str \"Bearer \" moonshot-api-key)\n 19                      \"Content-Type\" \"application/json\"}\n 20             ;; Construct the request body to match the Python example\n 21             body {:model moonshot-model\n 22                   :messages [{:role \"system\" :content \"You are Kimi, an AI assistant\\\n 23  provided by Moonshot AI. You are proficient in English conversations. You provide u\\\n 24 sers with safe, helpful, and accurate answers.\"}\n 25                              {:role \"user\" :content prompt}]\n 26                   :temperature 0.3}\n 27             ;; Make the POST request\n 28             response (client/post url {:headers headers\n 29                                        :body    (json/write-str body)\n 30                                        ;; Throw an exception for non-2xx response\n 31                                        :throw-exceptions false})\n 32             ;; Parse the JSON response body\n 33             parsed-body (json/read-str (:body response) :key-fn keyword)]\n 34 \n 35         (if (= (:status response) 200)\n 36           ;; Extract the content from the response using the -> (thread-first) macro\n 37           ;; This is equivalent to:\n 38           ;;   (get (get (first (get parsed-body :choices)) :message) :content)\n 39           (-> parsed-body :choices first :message :content)\n 40           ;; Handle potential errors from the API\n 41           (str \"Error: Received status \" (:status response)\n 42                \". Body: \" (:body response))))\n 43       (catch Exception e\n 44         (str \"An exception occurred: \" (.getMessage e))))))\n 45 \n 46 (defn- chat\n 47   \"Sends a chat request to the Moonshot AI chat completions API with tool support.\"\n 48   [messages]\n 49   (let [url (str moonshot-base-url \"/chat/completions\")\n 50         headers {\"Authorization\" (str \"Bearer \" moonshot-api-key)\n 51                  \"Content-Type\" \"application/json\"}\n 52         body {:model moonshot-model\n 53               :messages messages\n 54               :temperature 0.3\n 55               :tools [{:type \"builtin_function\"\n 56                        :function {:name \"$web_search\"}}]}\n 57         response (client/post url {:headers headers\n 58                                    :body    (json/write-str body)\n 59                                    :throw-exceptions false})\n 60         parsed-body (json/read-str (:body response) :key-fn keyword)]\n 61     (if (= (:status response) 200)\n 62       (-> parsed-body :choices first)\n 63       (throw (Exception. (str \"Error: Received status \" (:status response)\n 64                               \". Body: \" (:body response)))))))\n 65 \n 66 (defn search\n 67   \"Performs a Kimi 2 completion with web search.\"\n 68   [user-question]\n 69   (if-not moonshot-api-key\n 70     (println \"Error: MOONSHOT_API_KEY environment variable not set.\")\n 71     (try\n 72       (loop [messages [{:role \"system\" :content \"You are Kimi an AI assistant who re\\\n 73 turns all answers in English.\"}\n 74                        {:role \"user\" :content user-question}]]\n 75         (let [choice (chat messages)\n 76               finish-reason (:finish_reason choice)]\n 77           (if (= finish-reason \"tool_calls\")\n 78             (let [assistant-message (:message choice)\n 79                   tool-calls (-> assistant-message :tool_calls)\n 80                   tool-messages (map (fn [tool-call]\n 81                                        (let [tool-call-name\n 82                                              (-> tool-call :function :name)]\n 83                                          (if (= tool-call-name \"$web_search\")\n 84                                            (let [tool-call-args\n 85                                                  (json/read-str\n 86                                                    (-> tool-call\n 87                                                        :function :arguments)\n 88                                                    :key-fn keyword)]\n 89                                              {:role \"tool\"\n 90                                               :tool_call_id (:id tool-call)\n 91                                               :name tool-call-name\n 92                                               :content (json/write-str tool-call-arg\\\n 93 s)})\n 94                                            (let [error-message\n 95                                                  (str\n 96                                                   \"Error: unable to find tool by nam\\\n 97 e '\"\n 98                                                   tool-call-name \"'\")]\n 99                                              {:role \"tool\"\n100                                               :tool_call_id (:id tool-call)\n101                                               :name tool-call-name\n102                                               :content\n103                                               (json/write-str error-message)}))))\n104                                      tool-calls)]\n105               (recur (concat messages [assistant-message] tool-messages)))\n106             (-> choice :message :content))))\n107       (catch Exception e\n108         (str \"An exception occurred: \" (.getMessage e))))))\n

\n\n\n\n

\nTest code for the Moonshot.ai Kimi K2 API Client Library

\n\n

The test code for this library has two examples: a simple text completion augmented by the text completion with the web search tool. Here is the test code to simple text completion:

\n\n

1 (let [results\n2       (moonshot-api.core/completions \"Write a story starting with the text: He walke\\\n3 d to the river\")]\n4   (println results)\n

\n\n\n

Here is a few lines of sample output:

\n\n

 1 $ lein test\n 2 \n 3 lein test moonshot-api.core-test\n 4 He walked to the river because the house behind him had become too small for the gri\\\n 5 ef it carried.\n 6 \n 7 The grass was still wet with dew, and each step left a darker footprint, as though t\\\n 8 he earth itself were taking notes. When he reached the bank, the water was the color\\\n 9  of tarnished coins, sliding past without a sound. He knelt, cupped his hands, and l\\\n10 et the river run through them. The cold stung, but it was the first thing all mornin\\\n11 g that felt real.\n12 \n13 A dragonfly hovered, wings catching the early light like splinters of glass. It dipp\\\n14 ed once, skimming the surface, and he thought of his daughter’s laugh—bright, brief,\\\n15  skimming the surface of every room she had ever entered.\n16 \n17 He had come to scatter her ashes, but the plastic urn in his coat pocket might as we\\\n18 ll have been a brick. His fingers closed around it, then opened again. Not yet.\n19 \n20 Across the water, a willow leaned so low its branches combed the current. He imagine\\\n21 d the tree drinking her in, leaf by leaf, until every green blade carried a memory. \\\n22 That seemed better than surrendering her to the anonymous pull of the river.\n23 \n24  ...\n

\n\n\n\n

Here is example code for completion augmented with web search:

\n\n

1 (let [results\n2       (moonshot-api.core/search \"Current weather in Flagstaff Arizona\")]\n3   (println results)\n

\n\n\n\n

Here is some sample output:

\n\n

 1 Right now in Flagstaff, Arizona it is **76 °F (24 °C)** under **partly cloudy** skie\\\n 2 s.  \n 3 - **Wind:** Southwest at 15-16 mph  \n 4 - **Humidity:** 33 %  \n 5 - **UV index:** 7 of 11 (high)  \n 6 - **Rain chance:** 15 % with no measurable precipitation so far  \n 7 \n 8 Today’s high will reach about **77-78 °F** and tonight’s low will drop to around **5\\\n 9 2 °F**. There is a slight chance of an isolated shower or thunderstorm later in the \\\n10 day.\n

\n\n\n\n

\nWrap Up for Moonshot.ai Kimi K2 Model

\n\n

The Kimi K2 model is very efficient making it one of the least expensive commercial APIs to use. The model is at the same time powerful and is excellent at tool use and as a software assitant. As I write this chapter on July 21, 2025 almost all of my commercial LLM API use is either Google Gemini 2.5 Flash and Pro, and the Kimi K2 model.

\n\n\n

\nConclusions

\n\n

The material in this book was informed by my own work interests and experiences. If you enjoyed reading this book and you make practical use of at least some of the material I covered, then I consider my effort to be worthwhile.

\n\n

Writing software is a combination of a business activity, promoting good for society, and an exploration to try out new ideas for self improvement. I believe that there is sometimes a fine line between spending too many resources tracking many new technologies versus getting stuck using old technologies at the expense of lost opportunities. My hope is that reading it was an efficient and pleasurable use of your time, letting you try some new techniques and technologies that you had not considered before.

\n\n

When we do expend resources to try new things it is almost always best to perform many small experiments and then dig deeper into areas that have a good chance of providing high value and capturing your interest. I hope that I have provided you with a good road map to dig deeper into material that interests you.

\n\n

If we never get to meet in person or talk on the telephone, then I would like to thank you now for taking the time to read my book.

\n\n

\n\n","tocStructure",[307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366],{"_71":72,"_38":73,"_66":-5,"_74":75,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":81,"_66":-5,"_74":82,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":86,"_66":-5,"_74":87,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":91,"_66":-5,"_74":92,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":94,"_66":-5,"_74":95,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":97,"_66":-5,"_74":98,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":100,"_66":-5,"_74":101,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":104,"_66":-5,"_74":105,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":107,"_66":-5,"_74":108,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":110,"_66":-5,"_74":111,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":113,"_66":-5,"_74":114,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":117,"_66":-5,"_74":118,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":120,"_66":-5,"_74":121,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":124,"_66":-5,"_74":125,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":127,"_66":-5,"_74":128,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":130,"_66":-5,"_74":131,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":133,"_66":-5,"_74":134,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":136,"_66":-5,"_74":137,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":140,"_66":-5,"_74":141,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":143,"_66":-5,"_74":144,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":147,"_66":-5,"_74":148,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":150,"_66":-5,"_74":151,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":153,"_66":-5,"_74":154,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":156,"_66":-5,"_74":157,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":160,"_66":-5,"_74":161,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":163,"_66":-5,"_74":164,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":166,"_66":-5,"_74":167,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":169,"_66":-5,"_74":170,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":172,"_66":-5,"_74":173,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":175,"_66":-5,"_74":176,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":178,"_66":-5,"_74":179,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":181,"_66":-5,"_74":182,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":185,"_66":-5,"_74":186,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":189,"_66":-5,"_74":190,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":192,"_66":-5,"_74":193,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":195,"_66":-5,"_74":196,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":198,"_66":-5,"_74":199,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":201,"_66":-5,"_74":202,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":204,"_66":-5,"_74":205,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":208,"_66":-5,"_74":209,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":211,"_66":-5,"_74":212,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":214,"_66":-5,"_74":215,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":218,"_66":-5,"_74":219,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":222,"_66":-5,"_74":223,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":225,"_66":-5,"_74":226,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":228,"_66":-5,"_74":229,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":231,"_66":-5,"_74":232,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":234,"_66":-5,"_74":235,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":238,"_66":-5,"_74":239,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":241,"_66":-5,"_74":242,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":244,"_66":-5,"_74":245,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":247,"_66":-5,"_74":248,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":250,"_66":-5,"_74":251,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":254,"_66":-5,"_74":255,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":257,"_66":-5,"_74":258,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":260,"_66":-5,"_74":261,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":264,"_66":-5,"_74":265,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":267,"_66":-5,"_74":268,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":85,"_38":270,"_66":-5,"_74":271,"_67":76,"_88":-5,"_89":-5,"_79":-5},{"_71":72,"_38":273,"_66":-5,"_74":274,"_67":76,"_88":-5,"_89":-5,"_79":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

\nCover Material, Copyright, and License

Table of Contents

\nCover Material, Copyright, and License

\nPreface

\nRequests from the Author

\nHire the Author as a Consultant

\nClojure, With Some Java and Python

\nPersonal Artificial Intelligence Journey: or, Life as a Lisp Developer

\nAcknowledgements

\nDeep Learning Using Deeplearning4j

\nFeed Forward Classification Networks

\nOptional Material: Documentation for Other Types of DeepLearning4J Built-in Layers

\nDeep Learning Wrap Up

\nNatural Language Processing Using OpenNLP

\nUsing the Clojure and Java Wrappers for OpenNLP

\nAnomaly Detection Machine Learning Example

\nMotivation for Anomaly Detection

\nMath Primer for Anomaly Detection

\nAnomalyDetection Utility Class Written in Java

\nClojure Experiment for the University of Wisconsin Cancer Data Using Java Anomaly Detection Code

\nWeb Scraping

\nWeb Scraping Using the jsoup Library

\nUsing the Brave Search APIs

\nSetting an Environment Variable for the Access Key for Brave Search APIs

\nUsing the Brave Search API

\nWrap-up

\nBackground Material for the Semantic Web and Knowledge Graphs

\nLearning Plan

\nAvailable Tools

\nRDF: The Universal Data Format

\nExtending RDF with RDF Schema

\nThe SPARQL Query Language

\nOWL: The Web Ontology Language

\nSemantic Web Wrap-up

\nClojure Wrapper for the Jena RDF and SPARQL Library

\nSimple RDF Datastore and Partial SPARQL Query Processor

\nImplementing a Simple RDF Datastore

\nQuerying the RDF Datastore

\nImplementing a Partial SPARQL Query Processor

\nPutting It All Together: Running Example Queries

\nSummary

\nKnowledge Graph Navigator

\nEntity Types Handled by KGN

\nKGN Implementation

\nUsing the OpenAI APIs

\nUsing the Google Gemini 2.5 Flash APIs

\nTest Code for REST Interface and Sample Test Output

\nGemini API Library Implementation for REST Interface

\n(New) Gemini Client Library Using Google’s Java SDK for Gemini

\nGemini APIs Wrap Up

\nQuestion Answering Using OpenAI APIs and a Local Embeddings Vector Database

\nImplementing a Local Vector Database for Document Embeddings

\nCreate Local Embeddings Vectors From Local Text Files with OpenAI GPT APIs

\nUsing Local Embeddings Vector Database with OpenAI GPT APIs

\nWrap Up for Using Local Embeddings Vector Database to Enhance the Use of GPT3 APIs with Local Documents

\nRunning LLMs Locally Using Ollama

\nRunning the Example Tests

\nClojure Client Library for the Ollama Service REST APIs

\nUsing Moonshot’s Kimi K2 Model with Built In $web_search Tool Support

\nClojure Library Moonshot.ai’s Kimi K2 Model (Including Web Search Tool)

\nTest code for the Moonshot.ai Kimi K2 API Client Library

\nWrap Up for Moonshot.ai Kimi K2 Model

\nConclusions