Configuration

Every setting ActiveSanction.configure and Client.new accept. Type and default come from Configuration itself — see site/bin/generate_configuration.rb — so a setting added or retyped here needs no edit to this page. The one line of effect for each is written by hand below the table. Full method signatures are in the generated API documentation.

An unknown setting, or a value a writer refuses, raises ConfigurationError at the point it is set. See the error hierarchy.

Setting	Type	Default	Effect
cache_dir	String	$XDG_CACHE_HOME/active_sanction, or ~/.cache/active_sanction when unset	Where raw payloads and conditional-GET validators are cached. Recoverable by fetching again; safe to delete.
candidate_limit	Integer	200	Names the index hands the scorer per query. Overridden per query with `limit:`.
doctor_tolerance	Float	0.1	How far one of the doctor's measurements may move from the last sync before it is reported. Overridden per run with `tolerance:`.
instrumenter	T.untyped	nil	Where the six structured events go. Anything answering `#call(event)`; `nil` means nothing is listening, and costs nothing. See instrumentation.
logger	T.untyped	nil	Anything Logger-shaped, or `nil`.
max_redirects	Integer	5	Redirect hops followed before giving up.
max_retries	Integer	2	Attempts after the first, for a retryable failure.
normalizer_dictionary	ActiveSanction::Normalizer::Dictionary	Normalizer::Dictionary	The token lists the normalizer strips per entity type. See how matching works.
open_timeout	Numeric	10	Seconds to establish a connection.
read_timeout	Numeric	60	Seconds to wait for the next chunk of a body, not for the whole of one.
retain_payloads	Integer	3	Raw payloads kept per source, for re-parsing or diffing a suspicious file.
retry_backoff	Numeric	1.0	Seconds before the first retry, doubling on each one after it.
scorer_weights	ActiveSanction::Scorer::Weights	Scorer::Weights	What each signal the scorer reads is worth. See how matching works.
screening_limit	Integer	10	Results a screening call returns, highest score first. Overridden per query with `limit:`.
screening_threshold	Float	75.0	The lowest score a screening call reports, on the 0..100 scale. Overridden per query with `threshold:`.
sources	T.nilable(T::Array[Symbol])	nil	Which lists a sync runs, by key. `nil` means every registered source.
stale_after	T.nilable(Numeric)	86400	Seconds before `stale?` reports a source due for a sync. `nil` disables the clock; does not cap how long a cached copy may be used.
storage	ActiveSanction::Storage::Base	Storage::FileSystem	Where synced lists are read from and written to. Any Storage::Base — FileSystem, ActiveRecord, Memory, or your own.
storage_dir	String	~/.active_sanction	Where the filesystem store keeps parsed snapshots, when `storage` is left at its default.
sync_concurrency	Integer	1	How many publishers are fetched from at once — never how hard any one of them is asked.
user_agent	String	"active_sanction/1.1.1 (+https://github.com/Babystep-Technologies/active_sanction)"	Sent on every request. Cannot be blank — some publishers 403 a request with none.
xml_backend	Symbol	:rexml	Which XML library the XML toolkit parses with. `:nokogiri` for a host already parsing large documents.

Two settings that travel with every result

scorer_weights and normalizer_dictionary are not simple values — they are objects with their own defaults, described in full on How matching works rather than restated here. scorer_weights is stamped onto every MatchResult, so a tuned installation’s decisions stay explainable after the defaults move.

screening_threshold and candidate_limit

The two settings a host most often tunes.

• screening_threshold trades recall for precision. See the accuracy report for what moving it away from the default costs, measured rather than guessed.
• candidate_limit trades recall for latency: it bounds how many names the index hands the scorer before a threshold is applied. See performance characteristics.

Reading and changing configuration

ActiveSanction.configure do |c|
  c.user_agent = "my-app/1.0 (compliance@example.com)"
  c.screening_threshold = 80
end

ActiveSanction.config.screening_threshold   # => 80.0

Client.new accepts every setting above as a keyword argument, for a process holding more than one configuration at once:

audit_client = ActiveSanction::Client.new(sources: %i[ofac_sdn], screening_threshold: 60)

Configuration#with derives a copy from an existing, frozen configuration with some settings changed:

audit = config.with(storage: pinned_store, sources: %i[ofac_sdn])