genai-tk — GenAI & Agentic Toolkit
genai-tk is a Python 3.12+ toolkit where YAML config drives everything:
LLM providers, agent profiles, retrievers, workflows, and CLI commands are declared in config/*.yaml and
resolved at runtime through an Inversion-of-Control registry (ImportResolver). You extend it by adding YAML
entries that point at dotted Python paths, not by editing the library.
config/app_conf.yaml ─► global_config() ─► ImportResolver ─► factories / harness ─► LangChain objects
Verified against upstream commit 7fbd7a3 (2026-10-12). The toolkit moves fast and several upstream docs lag
the code (see "Upstream doc drift" below). When docs and code disagree, trust the code.
Quick Reference
| Topic | Reference |
|---|
Install, extras, cli init, full CLI command tree, CliTopCommand, cli skills, house conventions | cli-and-init.md |
app_conf.yaml, :merge, :profiles, GENAITK_PROFILE, typed config access, IoC | configuration.md |
get_llm / get_embeddings, model_id@provider, providers.yaml, reasoning effort, routing, decision models | models.md |
| Agent profiles, harness layer, tools, middlewares, skills, sandbox, MCP, DeerFlow, CodeAct, trajectories | agents.md |
RetrieverFactory, ManagedRetriever, embeddings stores, chunkers, cli rag, RAG as a tool | rag.md |
| YAML workflows, Prefect, ingest routing, markdownize converters | workflows.md |
BAML structured extraction: BamlStructuredProcessor, baml_invoke, cli baml | baml-structured.md |
Core Workflow
1. Install and scaffold
genai-tk is not on PyPI. Install from git with uv, then scaffold:
uv init my-app && cd my-app
uv add "genai-tk @ git+https://github.com/tclatos/genai-tk@main"
uv run cli init --name "My Agent App" # scaffolds config/, skills/, justfile; runs uv sync
uv run cli init --extra harnessing --extra browser # also install DeepAgents/DeerFlow + Playwright
just run # uv run cli agent chat
Extras: harnessing (deepagents, DeerFlow, OpenSandbox), browser, nlp, postgres, streamlit, baml,
chromadb, docling, monitoring, and all (everything except monitoring). Put API keys in .env
(auto-loaded, plus ~/.env for the CLI). Run uv run cli info doctor as a pre-flight check.
2. Call models
from genai_tk.core.factories import get_llm, get_embeddings
llm = get_llm() # llm.models.default from the active profile
llm = get_llm("fast_model") # a tag under llm.models
llm = get_llm("gpt-4o-mini@openai") # model_id@provider (resolved via models.dev)
llm = get_llm("parrot_local@fake") # offline fake model, no API key
llm = get_llm("o3 (high)@openai") # inline reasoning effort
llm = get_llm("claude-haiku@openrouter:speed") # gateway routing strategy
llm = get_llm("gpt-4o-mini@openai", streaming=True, json_mode=True, cache="sqlite")
embeddings = get_embeddings() # embeddings.models.default
Both return plain LangChain BaseChatModel / Embeddings objects. CLI: cli core llm -i "hello" -m parrot_local@fake,
cli info models, cli info llm-profile <id>. Details in models.md.
3. Define an agent in YAML, run it anywhere
Profiles live under a top-level agents: dict keyed by slug, in config/agents.yaml or config/agents/*.yaml.
agent_defaults: supplies fallbacks for LangChain profiles.
# config/agents.yaml
agent_defaults:
type: react
default_profile: research
agents:
research:
harness: langchain # langchain (default) | deerflow
name: "Research"
type: deep # react | deep | custom
llm: gpt-4o-mini@openai
system_prompt: "You are an expert researcher. Cite sources."
tools:
- genai_tk.agents.tools.langchain.search_tools_factory.create_search_function:
verbose: false
mcp_servers: [filesystem] # names from mcpServers: in mcp_servers.yaml
skill_directories: ["${paths.project}/skills"]
enable_planning: true
enable_file_system: true
checkpointer: {type: memory} # none | memory | class
from genai_tk.agents.langchain import LangchainAgent
agent = LangchainAgent("research", llm="claude-haiku@openrouter") # slug or display name, + overrides
print(agent.run("Summarise this week's AI news"))
uv run cli agents list
uv run cli agents run research "Summarise this week's AI news"
uv run cli agents run research --chat
For a harness-agnostic API (LangChain and DeerFlow behind one event stream), use
genai_tk.agents.harness.create_harness("research"). See agents.md.
4. Add RAG, workflows, or structured extraction
embeddings_store:
chroma:
backend: genai_tk.core.vector_backends.ChromaBackend
embeddings: default
config: {storage: "${paths.data_root}/vector_store"}
retrievers:
docs: {type: genai_tk.core.retrievers.VectorRetriever, embeddings_store: chroma, top_k: 4}
uv run cli rag add-files ./docs -r docs -p "**/*.md"
uv run cli rag query "What does the doc say about X?" -r docs
uv run cli workflow run markdownize/fast --set sources=./inbox --set md_output_dir=./data/md
uv run cli baml run ExtractResume -i "John Smith; 10 years Python" # a function from your baml_src/
Configuration in One Minute
config/app_conf.yaml is the root. It is loaded from config/app_conf.yaml relative to the current working
directory (it does not walk up parent directories), so run commands from the project root.
profile: ${oc.env:GENAITK_PROFILE,local}
paths:
project: ${oc.env:PWD}
config: ${paths.project}/config
data_root: ${paths.project}/data
:merge: ["**/*.yaml", "!demos/**", "!examples/agents/**"] # gitignore-style globs under config/
:profiles:
local:
llm: {models: {default: gpt-4o-mini@openai, fake: parrot_local@fake}, cache: sqlite}
embeddings: {models: {default: embeddings_768@fake}}
:env: {LOGURU_LEVEL: INFO}
from genai_tk.config_mgmt.config_mngr import global_config, switch_profile
cfg = global_config()
cfg.get_str("llm.models.default")
cfg.section("my_feature", MyFeatureConfig) # typed Pydantic access; empty model if absent
switch_profile("pytest") # sets GENAITK_PROFILE and reloads
Full semantics in configuration.md.
Coding Conventions (from upstream AGENTS.md)
- Python 3.12+:
str | None, list[str]; avoid Any (use discriminated unions or TypeAlias)
- Absolute imports only; ruff with line length 120
- Pydantic v2 for all structured data:
model_config = {...}, model_post_init(), model_dump_json(); no
dataclasses, unnamed tuples, or untyped dicts
loguru for logging; Google-style docstrings without types or Raises:- Read config through typed models:
global_config().section(...) / .section_dict(...)
- Tests: use the
fake_llm_id / fake_llm fixtures and fake providers instead of mocks; never hard-code model IDs
- Domain knowledge goes in
SKILL.md files loaded on demand, not in system prompts
Upstream Doc Drift
These upstream docs or bundled skills contradict the code at 7fbd7a3. Use the right-hand column.
| Docs say | Code does |
|---|
| Config search walks up parent directories | Only config/app_conf.yaml under the CWD |
cli init -t agent-app|rag-app|workflow-app|minimal, --with-deer-flow | Flags are --name, --extra, --with-graph, --graph-path, --force |
cli mcp serve|list|generate | The group is cli mcpserver start|serve|list|generate |
cli core decision | cli core classifier |
get_llm(..., reasoning={...}) | Raises; use "model (high)@provider" or reasoning_effort="high" |
Workflow DSL with steps: / uses: / needs: | run: or pipeline: with id, run, after, with |
cli rag add-files <retriever> <dir>, --include | cli rag add-files <dir> -r <retriever> -p <pathspec> |
Short retriever/backend aliases (type: vector, backend: Chroma) | Fully qualified class paths are required |
langchain_agents: profile lists | agents: dict + agent_defaults: |
baml_invoke(inputs=...), cli baml extract --recursive --include | baml_invoke(name, params, ...), -p <pathspec> (default **/*.md) |
Bundled baml_extract, rag_ingest, office2pdf workflows (and cli baml extract) just work | Their YAML param names don't match the flow signatures; see workflows.md |
Anti-Patterns to Avoid
- Using pre-2026 import paths —
genai_tk.core.llm_factory, genai_tk.utils.config_mngr, and
genai_tk.core.retriever_factory are gone with no shims; import from genai_tk.core.factories and
genai_tk.config_mgmt.config_mngr
- Writing
langchain_agents: / profiles: lists or spec: web_search tools — the old profile schema is
rejected; use the agents: dict and qualified factory paths for tools
- Putting
skills: on a profile — it is silently ignored; use skill_directories: (deep agents only)
- Bare model names in YAML —
gpt-4o-mini triggers fuzzy lookup; always write model_id@provider
- Short aliases for retrievers and vector backends — they fail to resolve; use
genai_tk.core.retrievers.VectorRetriever, genai_tk.core.vector_backends.ChromaBackend, etc.
- Hard-coding agents or LLMs in Python — add a YAML entry;
LangchainAgent("slug") only loads and overrides
type: deep or DeerFlow without the harnessing extra — deepagents and deerflow-harness live there- Expecting
--sandbox on cli agents run to isolate a LangChain profile — it only applies to DeerFlow; set
backend: {type: docker} (or LangchainAgent(..., sandbox="docker")) for LangChain profiles
- Running from a subdirectory — config discovery is CWD-relative;
ConfigFileNotFoundError usually means
you are not at the project root
- Copying examples from upstream
docs/ without checking the code — see "Upstream Doc Drift"
When to Use / Not Use
Use this skill when:
- Working inside a genai-tk project (a
config/app_conf.yaml and genai_tk imports are present)
- Writing or fixing agent profiles, provider/LLM config, retrievers, workflows, or
cli.commands entries
- Scaffolding with
cli init, extending the CLI, or wiring MCP servers, sandboxes, BAML, or trajectories
- Migrating code written for older genai-tk versions (old imports,
langchain_agents:, SmolAgents)
Do NOT use this skill when:
- The project uses plain LangChain/LangGraph without genai-tk — use the langchain skill
- You need a quick standalone agent without config-first machinery — the smolagents or langchain skills fit better
- The question is about DeerFlow or DeepAgents used directly, outside genai-tk's harness