---

This repository is the engine underneath the product, not the product itself.

Looking for LingTai the product? The Lingtai-AI/lingtai repository is the source of truth for the Digital Scientist — the lifelong, self-growing agent — including the guided installer, the TUI/Portal, and everyday workflows. Normal users should start there and let the installer manage this runtime for them. This repository is for developers who build on or contribute to the kernel; do not treat a bare pip install here as the normal installation path.

What this repository owns

• The agent runtime — the core turn loop, lifecycle, tool dispatch, mailbox, molt, and notification machinery that make an agent run.
• Two Python surfaces — lingtai.kernel, the minimal runtime (BaseAgent, intrinsics, the LLM protocol, mail, and logging), and lingtai, the batteries-included runtime, CLI, and services that build Agent(BaseAgent) on top of it and re-export the kernel's public API.
• The batteries — the bundled built-in tools, the LLM adapters, the curated MCP server implementations, and the packaging (a pure-Python distribution). These are ownership boundaries, not a feature list.

Developer quick start

For kernel development — not the normal LingTai user installation path. Requires Python >= 3.11; use a local .venv. The code baseline remains open-ended at Python

= 3.11, while the managed macOS runtime and direct dependency follow this wheel compatibility matrix:

Target interpreter	Supported Python (package/deps)	Managed runtime selector	Direct onnxruntime requirement
Apple Silicon, macOS 14+	3.11–3.14	3.11–3.13	1.28.0
Apple Silicon, macOS 13	3.11–3.13	3.11–3.13	1.23.2
Intel/Rosetta, macOS 13+	3.11–3.13	3.11–3.13	1.23.2

The confirmed onnxruntime wheels make macOS 13 the support floor. Only Apple Silicon on macOS 14+ supports Python 3.14 in the dependency matrix (onnxruntime 1.28.0 publishes a cp314 ARM wheel); an x86_64 process under Rosetta follows the Intel row. The managed runtime selector caps at Python 3.13 on every macOS cell because that is the interpreter range the managed dependency matrix is verified on; LingTai itself ships as a pure-Python universal wheel, so the cap is not a LingTai native-build limit. Python 3.14 remains usable for source installs outside the managed selector.

git clone https://github.com/Lingtai-AI/lingtai-kernel.git
cd lingtai-kernel
uv venv --python 3.11
uv pip install -e . pytest
.venv/bin/python -m pytest

Architecture / developer entry points

Before changing anything, a coding agent first finds and reads this repository’s local dev guide skill; it owns the workflow and routes each task onward through the linked entry points below without duplicating the Anatomy or Contract systems.

Entry point	What it covers
dev-guide-skill/SKILL.md	The mandatory repository-local dev guide skill: the development workflow a coding agent must follow before editing.
ANATOMY.md	Repository structure/composition map — where each subsystem's anatomy begins and how it reaches its behavioral Contract.
CONTRACT.md	Normative interface/behavior promises plus the governed-component pairing/ownership rule, linked back to Anatomy structure.
src/lingtai/kernel/ANATOMY.md	The core runtime: BaseAgent, turn/lifecycle, tool machinery, mail, LLM protocol.
src/lingtai/ANATOMY.md	The lingtai package: Agent(BaseAgent), capabilities, presets, CLI, public re-exports.
src/lingtai/tools/ANATOMY.md	The concrete built-in tools and the registry that composes them.
src/lingtai/mcp_servers/ANATOMY.md	The bundled MCP server implementations.
CONTRIBUTING.md	Contribution workflow and repository navigation.
docs/references/claude-code-guide.md	The full repository guide — test commands, architecture notes, and conventions.

Security · Support · Acknowledgements

For responsible disclosure, read SECURITY.md; for help, read SUPPORT.md; for credits, read docs/references/acknowledgements.md.

License

Apache-2.0 — Zesen Huang, 2025–2026