Clojure安全LLM输出工具

Basic Setup

(comment
  ;; Single provider
  (def router
    (svar/make-router [{:id :openai
                        :api-key (System/getenv "OPENAI_API_KEY")
                        :models [{:name "gpt-4o"}
                                 {:name "gpt-4o-mini"}]}])))

Quick Start

 lazytest/skip=true
;; deps.edn
{:deps {com.blockether/svar {:mvn/version "0.7.11"}}}

(require '[com.blockether.svar.core :as svar])

;; Create a router — the single entry point for all LLM calls.
;; Every function takes the router as its first argument.
(comment
  (def router (svar/make-router [{:id :openai
                                  :api-key (System/getenv "OPENAI_API_KEY")
                                  :models [{:name "gpt-4o"}]}])))

Usage

Routing Options

Every ask! call accepts :routing to control provider/model selection:

(comment
  ;; Let the router pick the cheapest model
  (svar/ask! router {:spec my-spec
                     :messages [(svar/user "...")]
                     :routing {:optimize :cost}})

  ;; Or the most capable
  (svar/ask! router {:spec my-spec
                     :messages [(svar/user "...")]
                     :routing {:optimize :intelligence}})

  ;; Pin to a specific provider + model
  (svar/ask! router {:spec my-spec
                     :messages [(svar/user "...")]
                     :routing {:provider :openai :model "gpt-4o-mini"}}))

API styles

svar now uses explicit transport names for OpenAI-compatible providers:

• :openai-compatible-chat → /chat/completions
• :openai-compatible-responses → /responses
• :anthropic → /messages

Known provider profiles choose the right transport for you. For custom providers, set :api-style explicitly:

(comment
  (def router
    (svar/make-router
      [{:id :my-openai-gateway
        :api-key (System/getenv "MY_GATEWAY_API_KEY")
        :base-url "https://gateway.example.com/v1"
        :api-style :openai-compatible-chat
        :models [{:name "gpt-4o"}]}
       {:id :my-responses-gateway
        :api-key (System/getenv "MY_RESPONSES_API_KEY")
        :base-url "https://gateway.example.com/v1"
        :api-style :openai-compatible-responses
        :models [{:name "gpt-5.5"}]}])))

Spec DSL Reference

The spec DSL defines the shape of LLM output. Every field has a name, type, cardinality, and description.

All Types

Keyword Type (TYPE_KEYWORD)

String values automatically become Clojure keywords on parse — useful for status codes, categories, and enum-like fields that you want as keywords in your code:

(def status-spec
  (svar/spec
    (svar/field svar/NAME :status
                svar/TYPE svar/TYPE_KEYWORD
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Current status")))

;; String "active" in JSON becomes keyword :active in Clojure
(svar/str->data-with-spec "{\"status\": \"active\"}" status-spec)
;; => {:status :active}

Enums (VALUES)

When a field should only contain one of a fixed set of values — status codes, categories, severity levels — use VALUES with a map of {value description}. The descriptions are included in the LLM prompt so it understands what each value means, which dramatically improves output accuracy:

(def sentiment-spec
  (svar/spec
    (svar/field svar/NAME :sentiment
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Sentiment classification"
                svar/VALUES {"positive" "Favorable or optimistic tone"
                             "negative" "Unfavorable or critical tone"
                             "neutral" "Balanced or factual tone"})
    (svar/field svar/NAME :confidence
                svar/TYPE svar/TYPE_FLOAT
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Confidence score from 0.0 to 1.0")))

;; Valid enum value passes
(svar/validate-data sentiment-spec {:sentiment "positive" :confidence 0.95})
;; => {:valid? true}

;; Invalid enum value caught
(:valid? (svar/validate-data sentiment-spec {:sentiment "happy" :confidence 0.8}))
;; => false

Optional Fields (REQUIRED)

Fields are required by default — the LLM must provide a value. Set REQUIRED false when a field might legitimately be absent (e.g., a phone number the source text doesn't mention). Optional fields parse as nil when missing, and validation passes without them:

(def contact-spec
  (svar/spec
    (svar/field svar/NAME :name
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Full name")
    (svar/field svar/NAME :phone
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/REQUIRED false
                svar/DESCRIPTION "Phone number if available")))

;; Validation passes without optional fields
(svar/validate-data contact-spec {:name "Jane Doe"})
;; => {:valid? true}

;; But fails without required fields
(svar/validate-data contact-spec {:phone "555-1234"})
;; => {:valid? false, :errors [{:error :missing-required-field, :field :name, :path "name"}]}

Collections (CARDINALITY_MANY)

When a field holds multiple values — tags, authors, line items — use CARDINALITY_MANY. The LLM returns a JSON array, parsed as a Clojure vector:

(def article-spec
  (svar/spec
    (svar/field svar/NAME :title
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Article title")
    (svar/field svar/NAME :tags
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_MANY
                svar/DESCRIPTION "List of tags")))

;; Arrays are parsed as Clojure vectors
(svar/str->data-with-spec "{\"title\": \"SVAR Guide\", \"tags\": [\"clojure\", \"llm\", \"parsing\"]}" article-spec)
;; => {:title "SVAR Guide", :tags ["clojure" "llm" "parsing"]}

(svar/validate-data article-spec {:title "SVAR Guide" :tags ["clojure" "llm"]})
;; => {:valid? true}

Nested Specs (TYPE_REF / TARGET)

When your LLM output has nested objects — a company with an address, an order with line items — you define each sub-object as its own named spec, then reference it with TYPE_REF + TARGET. This keeps specs composable and reusable: define Address once, reference it from Company, Person, Order, etc.

Pass referenced specs via {:refs [address-spec]} so the prompt generator and parser know how to handle them. Combine with CARDINALITY_MANY for arrays of nested objects (e.g., branch offices).

(def address-spec
  (svar/spec :Address
    (svar/field svar/NAME :street
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Street address")
    (svar/field svar/NAME :city
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "City name")))

(def company-spec
  (svar/spec
    {:refs [address-spec]}
    (svar/field svar/NAME :name
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Company name")
    (svar/field svar/NAME :headquarters
                svar/TYPE svar/TYPE_REF
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/TARGET :Address
                svar/DESCRIPTION "HQ address")
    (svar/field svar/NAME :branches
                svar/TYPE svar/TYPE_REF
                svar/CARDINALITY svar/CARDINALITY_MANY
                svar/TARGET :Address
                svar/DESCRIPTION "Branch office addresses")))

;; Parse nested JSON — refs become nested maps/vectors automatically
(svar/str->data-with-spec
  "{\"name\": \"Acme Corp\", \"headquarters\": {\"street\": \"123 Main St\", \"city\": \"SF\"}, \"branches\": [{\"street\": \"456 Oak Ave\", \"city\": \"LA\"}]}"
  company-spec)
;; => {:name "Acme Corp", :headquarters {:street "123 Main St", :city "SF"}, :branches [{:street "456 Oak Ave", :city "LA"}]}

;; Ref registry maps spec names to their definitions
(vec (keys (svar/build-ref-registry company-spec)))
;; => [:Address]

Namespaced Keys (KEY-NS)

When LLM output maps directly to Datomic/Datalevin entities, you want namespaced keys (:page.node/type instead of :type). KEY-NS adds a namespace prefix to all keys during parsing, so you can transact LLM results straight into your database without manual key transformation.

This is especially useful when multiple specs share field names like :type or :id — namespacing disambiguates them.

(def node-spec
  (svar/spec :node
    {svar/KEY-NS "page.node"}
    (svar/field svar/NAME :type
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Node type")
    (svar/field svar/NAME :content
                svar/TYPE svar/TYPE_STRING
                svar/CARDINALITY svar/CARDINALITY_ONE
                svar/DESCRIPTION "Text content")))

;; Keys are automatically namespaced — ready for d/transact!
(svar/str->data-with-spec "{\"type\": \"heading\", \"content\": \"Introduction\"}" node-spec)
;; => {:page.node/type "heading", :page.node/content "Introduction"}