Synalinks

Synalinks

Synalinks is an open-source, Keras-inspired framework for building neuro-symbolic LM applications (RAGs, agents, self-evolving reasoning) with in-context reinforcement learning. This skill is the single entry point: each section below is a scannable overview that points to a runnable script + its captured run log and a deep-dive reference doc under references/.

Core abstractions

• DataModel — Pydantic-style schema for structured I/O (replaces tensors).
• Module — async computational unit processing JSON data (replaces layers).
• Program — DAG of modules with conditional logic (replaces models).
• Reward / Optimizer — guide training by maximizing reward (no gradients; prompts/examples/plans are the trainable variables).
• DecisionModel — answers typed questions (yes/no, choice, score) with calibrated probabilities instead of generating text; used for decisions.

Universal gotchas (apply everywhere)

1. All module constructors are keyword-only (* after self). Call Generator(data_model=Answer, language_model=lm), never positionally. The one exception is Tool(func, *, ...) — func stays positional.
2. instructions MUST be a string, never a list — passing a list raises ValidationError.
3. All call() methods are async — await every module/program call.
4. language_model/embedding_model may be omitted if a process-wide default is set (set_default_language_model(...)); resolved at call time.
5. Always check for None results — a failed LM call or a non-activated branch yields None.
6. A DecisionModel is never a language_model — passing one as language_model raises. Modules that can decide take decision_model=.

Quick Start

pythonCopy code
import synalinks, asyncio

class Query(synalinks.DataModel):
    query: str = synalinks.Field(description="The user query")

class Answer(synalinks.DataModel):
    answer: str = synalinks.Field(description="The answer")

async def main():
    lm = synalinks.LanguageModel(model="ollama/mistral")
    inputs = synalinks.Input(data_model=Query)
    outputs = await synalinks.Generator(data_model=Answer, language_model=lm)(inputs)
    program = synalinks.Program(inputs=inputs, outputs=outputs, name="simple_qa")
    result = await program(Query(query="What is the capital of France?"))
    print(result.prettify_json())

asyncio.run(main())

Runnable: scripts/simple_qa.py → log references/simple_qa.log.

Core: DataModel, operators, models

DataModel defines structured I/O; Field(description=...) shapes what the LM emits. Complex types, nested models, Optional/Enum/List all work. ChatMessages is the special conversational data model. LanguageModel and EmbeddingModel are Module subclasses accepting **default_kwargs (temperature, top_p, max_tokens, reasoning_effort, dimensions, ...) forwarded to every call, plus fallback= (string/dict/instance, auto-coerced).

JSON operators (circuit-like logic on DataModels):

Module forms: synalinks.And()/Or()/Xor()/Not() (take a list). synalinks.ops has concat, in_mask/out_mask, factorize, logical_*. Config helpers: enable_logging(), enable_observability(), set_seed(), clear_session().

• Deep dives: references/api-reference.md, references/data-models.md
• scripts/subclassing_modules.py → references/subclassing_modules.log

Programs: the four building APIs

Program inherits from both Trainer and Module (a Program is itself a module — nest freely).

Save/load: program.save("p.json") / Program.load(...) (config + variables + optimizer/reward state). to_json() is inspect-only (no variables). Inspection: summary(expand_nested=True), get_module(...), trainable_variables, get_state_tree/set_state_tree. Register custom subclasses with @synalinks.saving.register_synalinks_serializable().

• Deep dive: references/programs.md
• scripts/four_apis.py → references/four_apis.log

Modules: generation & custom subclassing

• Generator — core structured-output LM module. Trainable vars: instructions, examples. Knobs: return_inputs, temperature, reasoning_effort, use_inputs_schema, streaming.
• ChainOfThought — Generator that prepends a thinking field (reasoning_effort="low" by default).
• SelfCritique — produces a critique and optional reward in [0,1] (with decision_model=: only the reward, graded on five levels).
• Identity — pass-through placeholder.
• PythonSynthesis — generates/executes Python in a sandbox (no LM call; the script is the trainable variable; needs advanced optimizers).
• SequentialPlanSynthesis — internal only (not in public API; import from synalinks.src.modules.synthesis.sequential_plan_synthesis).

Custom modules: subclass Module, implement async call(), compute_output_spec(), and get_config/from_config; use add_variable(...) for trainable state; return None to short-circuit logical flows.

• Deep dive: references/modules-catalog.md
• scripts/chain_of_thought.py → references/chain_of_thought.log
• scripts/custom_module.py → references/custom_module.log

Control flow: routing, parallelism, guards

• Decision — single-label routing; output {thinking, choice} constrained to labels. MultiDecision — multi-label (choices: list[str]). Both take decision_model= (output without thinking); Decision then accepts min_confidence (abstains → None), MultiDecision threshold.

• Branch — route to one of N modules; branches/labels same length; non-activated branches return None; each branch trains separately; decision_type=MultiDecision for multi-fire. Merge with | (not +). return_decision/inject_decision default True.

• Parallel branches — modules sharing an input run concurrently via asyncio.

• Self-consistency — N Generators at temperature>0, merge with &, then a final Generator over inputs & merged.

• XOR guards — warning ^ inputs to bypass; warning | answer to replace. A custom module returning None allows-through.

• Deep dive: references/control-flow.md

• scripts/conditional_branches.py → references/conditional_branches.log

• scripts/guard_patterns.py → references/guard_patterns.log

Agents: tools, RLM, DeepAgent, MCP

• FunctionCallingAgent — autonomous/interactive tool use; max_iterations, return_inputs_with_trajectory (emits the ChatMessages trajectory with tool_calls inside assistant messages).

• Tools — async def, fully type-annotated, docstringed, decorated with @synalinks.utils.register_synalinks_serializable(), returning a dict with a log/status field. All params required (no defaults). Tool(func).

• RLM (RecursiveLanguageModelAgent) — only tool is run_python_code in a persistent REPL sandbox; recursive=True exposes llm_query/ llm_query_batched over a sub_language_model for long-context work; terminates via in-sandbox submit(...). max_iterations, max_llm_calls.

• DeepAgent — sandboxed coding agent over a workdir with read/write/edit/search/run_bash; host-safe (operates on a copy); inspect via agent.sandbox.diff() (sandbox lives on the module, not the Program).

• Subagents — max_subagent_depth>0 enables spawn/merge/discard_subagent on isolated Sandbox.forks. MCP — MultiServerMCPClient({...}), await client.get_tools().

• Deep dive: references/agents-tools.md

• scripts/tool_agent.py → references/tool_agent.log (use ollama/qwen3:8b)

• scripts/rlm_agent.py → references/rlm_agent.log

• scripts/deep_agent.py → references/deep_agent.log

Knowledge & RAG

KnowledgeBase is DuckDB-backed (uri="duckdb://./db.db" or :memory:), one table per DataModel — first field is the primary key. Add graph_uri="ladybug://..." for a property-graph store. Modules (keyword-only): EmbedKnowledge (mask to one field), UpdateKnowledge (upsert), RetrieveKnowledge (LM generates the query; search_type in similarity/fulltext/hybrid), StampKnowledge. Direct methods: fulltext_search, similarity_search, hybrid_search, get, getall, query. Pipe Generator → UpdateKnowledge to extract-and-store.

• Deep dive: references/knowledge-base.md
• scripts/rag_example.py → references/rag_example.log

Training (in-context RL)

Workflow: build → compile(reward=, optimizer=, metrics=) → fit(x, y, ...) → evaluate(x, y) → predict(x) → save(...). Data is NumPy arrays of DataModel instances (dtype="object") or custom iterables. fit knobs: validation_split/validation_data, epochs, batch_size, minibatch_size, callbacks. Callbacks: ProgramCheckpoint(monitor="val_reward", mode="max"), custom Callback subclasses (sync hooks). compile accepts string identifiers ("omega", "exactmatch", "f1score").

• Deep dive: references/training-guide.md
• scripts/training_example.py → references/training_example.log (logging off — fit() progress bar only)

Decision models

synalinks.DecisionModel(model="typesafe/jev-latest") (key: TYPESAFE_API_KEY) answers the fields of a data model as questions, each asked with its description: bool → yes/no, Literal/Enum → choice, score types (synalinks.Rating, synalinks.Score, ...) → score over the scale. Free-text fields raise UnsupportedSchemaError. Pass it as decision_model= to Generator, Decision, MultiDecision, Branch, SelfCritique, RubricsAsJudge (they drop thinking/critique); Branch routes with it while its branches keep their LMs. min_confidence (Decision/Branch) and threshold (MultiDecision/Branch) let a decision be skipped rather than guessed; tune them with synalinks.tuners (price an abstention between a right and a wrong answer in the reward). set_default_decision_model(...) makes these modules prefer it over the default LM. It learns in context: every optimizer (incl. OMEGA) works unchanged. Counted by the LM operational metrics.

• Deep dive: references/decision-models.md
• scripts/decision_model.py (needs TYPESAFE_API_KEY; no captured run)

Rewards & metrics

Rewards drive optimization; metrics are passive. Both return a float in [0,1] and support in_mask/out_mask(_pattern) field masking. Built-in rewards: ExactMatch, CosineSimilarity, LMAsJudge, ProgramAsJudge (judge program must output a float field named reward), RubricsAsJudge (named, weighted criteria; decision_model= grades them all in one call) and its presets (list_rubrics(): Faithfulness, AnswerRelevancy, Hallucination, ContextualPrecision/Recall/Relevancy, Toxicity, Bias, PIILeakage, TaskCompletion, ToolCorrectness, PlanQuality, RoleAdherence, ... — 31 in all), tool-using judges AgentAsJudge (tools), DeepAgentAsJudge (sandboxed project: run tests/patches) and RLMAsJudge (Python sandbox, huge outputs), ComposableReward (weighted mix of rewards) and BatchReward / BatchRewardFunctionWrapper (whole-batch rewards, never auto-wrapped). Custom: async (y_true, y_pred) -> float decorated and wrapped in RewardFunctionWrapper — always handle None. Metrics: F1Score, FBetaScore, BinaryF1Score, ListF1Score, Precision/Recall, MeanMetricWrapper(fn=...).

• Deep dive: references/rewards-metrics.md
• scripts/custom_reward.py → references/custom_reward.log

Optimizers

Optimizers evolve trainable variables (no gradients). Always start with RandomFewShot (free, examples-only) before reaching for OMEGA (LLM-driven evolutionary optimizer with Dominated Novelty Search for quality-diversity; optimizes the full trainable variable). OMEGA needs an embedding_model for the DNS branch (pass one or set a default); temperatures must be non-zero; population_size ≤ ~20 (DNS is O(N²)). algorithm="ga" ablates DNS.

• Deep dive: references/optimizers.md
• scripts/omega_example.py → references/omega_example.log (.fit on ollama — progress bar only)

Providers

• Constrained json_schema: openai/, azure/, ollama/, mistral/, gemini/, xai/, deepseek/, together_ai/, hosted_vllm/.
• Tool-call (no native schema, or heterogeneous backends): groq/, cohere/, openrouter/, bedrock/.
• response_format (litellm auto-routes): anthropic/.

Some prefixes are rewritten in __init__: ollama/→ollama_chat/ (default api_base http://localhost:11434), vllm/→hosted_vllm/ (HOSTED_VLLM_API_BASE or http://localhost:8000), doubleword/→openai/ + the Doubleword api_base.

An OpenAI-compatible server without a dedicated prefix (LMStudio, a custom gateway, OpenRouter embeddings) uses the openai/ prefix + api_base + a dummy OPENAI_API_KEY; local servers also need litellm.register_model({...}) so cost tracking returns 0. Azure keeps its own azure/<deployment> prefix (same constrained json_schema path as openai/) and needs AZURE_API_KEY + AZURE_API_BASE + AZURE_API_VERSION.

• Helper: scripts/lmstudio_setup.py → references/lmstudio_setup.log (demo runs against local ollama)

Datasets & visualization

Built-in datasets expose load_data() / get_input_data_model() / get_output_data_model(): synalinks.datasets.gsm8k, .hotpotqa (load_knowledge() for RAG), .arcagi (per-task, plot_task(...)). Build your own with NumPy arrays of DataModels (dtype="object") or custom iterables (optional __len__ enables progress bars; use validation_data, not validation_split). Visualization: synalinks.utils.plot_program, plot_history, plot_metrics_with_mean_and_std, plot_metrics_comparison_with_mean_and_std.

• scripts/custom_dataset.py → references/custom_dataset.log
• scripts/visualization.py → references/visualization.log (both .fit — progress bar only, no logging)

Scripts → logs index

Every runnable script states its Usage: and (where a captured run exists) its Run log: in its module docstring.

Reference docs

api-reference.md, data-models.md, programs.md, modules-catalog.md, control-flow.md, agents-tools.md, knowledge-base.md, training-guide.md, rewards-metrics.md, optimizers.md, decision-models.md — all under references/.