DEV Community: Yehor Kaliberda

How Symbiote Annotated a Python Repository Overnight — Without Breaking Anything

Yehor Kaliberda — Tue, 02 Jun 2026 17:30:21 +0000

CallMed AI — Aarhus, Denmark

We built Symbiote to solve one specific problem: adding PEP 484 type annotations to a Python codebase without touching runtime logic, breaking existing tests, or truncating docstrings.

Here's what a real run looks like.

The target: tablib

tablib is a Python library for working with tabular data — CSV, Excel, JSON, YAML. It's maintained by jazzband, has 4,600+ stars, and is used in production by thousands of teams. It predates PEP 484 and has partial annotation coverage in its core modules.

We ran Symbiote's Mirror Pass on it.

What Symbiote does

The pipeline has three stages:

1. Perception — Symbiote parses the repository into a typed AST dependency graph using tree-sitter. Every file, every function, every import edge is mapped. The output is a PerceptionFrame: a typed snapshot of what the codebase looks like right now.

2. Reasoning — A PlannerAgent ingests the AST graph and computes a blast radius for each proposed change. Before any file is touched, Symbiote knows which other files import it and would be affected. This is how we avoid cascading breaks.

3. Action — The Mirror agent rewrites each file under Bouncer-mediated file locks. Two agents cannot modify overlapping dependency chains simultaneously. Every lock event is logged to kernel.log with monotonic-nanosecond timestamps. The run ends with a verdict: COLLISION-FREE ✓.

All changes go onto a dedicated symbiote/plan-{id} branch. We never push to main.

What the PR looks like

PR: yehorcallmedai-maker/tablib #642

The diff adds typed signatures to public functions in _csv.py:

# Before
def export_set(dataset, **kwargs):
    ...

# After
def export_set(dataset: Dataset, **kwargs: Any) -> str:
    ...

Changes: strictly additive. No logic modifications. Existing docstrings, inline comments, and doctests preserved verbatim.

CI result after our push: pre-commit.ci green ✅. The ruff UP007 lint rule (replace Optional[str] with str | None) was caught and fixed automatically.

Why this matters

Static analysis is only as useful as annotation coverage. A codebase at 30% coverage gives mypy incomplete information — it falls back to Any for unannotated parameters, which silently defeats the type checker.

The Mirror Pass is designed to move that number. Not by guessing types, but by reading the AST, tracing the call graph, and writing annotations that are correct given what the code actually does.

Symbiote's safety model

The reason we can run this autonomously without fear:

Bouncer locks: every write is preceded by a granted file lock with transitive blast-radius checking
Additive-only: if a function's existing docstring would shrink by more than 20% as a result of a rewrite, the write is aborted
Branch isolation: worst-case rollback is git branch -D symbiote/plan-{id}
Full audit trail: kernel.log records every lock acquire, wait, release, and denial

The run on tablib's _csv.py completed collision-free.

What's next

The v2 architecture replaces full-file LLM rewrites with an AST-aware patch-merge model — changes are spliced at the ParsedNode level. This eliminates context-budget pressure on large, well-documented files before we ship docstring generation at scale.

CallMed AI runs autonomous Python codebase audits and delivers them as reviewable Pull Requests. The tip-of-spear service is the Mirror Pass: PEP 484 type annotations across your entire Python repository, $1,500 flat, PR within 72 hours.

→ callmedai.com · yehor@callmedai.com

We Ran Symbiote on smolagents — Here's What Changed

Yehor Kaliberda — Mon, 01 Jun 2026 18:31:40 +0000

We Ran Symbiote on smolagents — Here's What Changed

By Yehor Kaliberda, CallMed AI · June 2026

The Problem

smolagents is one of HuggingFace's most elegant libraries — a barebones agent framework where tools are defined by Python functions with type hints.
The design is intentional: the @tool decorator reads your function's type annotations and docstring to auto-generate the tool's schema for the LLM.

Which makes it ironic that the library's own core class — Tool in tools.py — has 16 methods with missing type annotations.

We ran Symbiote on it to fix that.

What Symbiote Does

Symbiote is an autonomous codebase evolution engine.
The pipeline runs in three stages:

Perception — tree-sitter AST extraction produces a typed symbol graph of every class, method, and import in the repo.
Reasoning — a dependency graph (graph.json) calculates the blast radius of each file before touching it, so Symbiote never modifies something that could break imports elsewhere unexpectedly.
Action — a structured LLM rewrite (Pydantic-validated CodeModification, full-file, no truncation) runs on a dedicated symbiote/plan-* git branch.

The output is a reviewable PR. Maintainers merge only what they approve.

What We Found in smolagents/tools.py

Running the Symbiote perception cycle on the smolagents repo surfaced 16 annotation targets in tools.py alone:

Method	What was missing
`validate_after_init(cls)`	`cls: type`, `-> type`, docstring
`Tool.__init__`	`args: Any`, `*kwargs: Any`, `-> None`, docstring
`Tool.__init_subclass__`	`**kwargs: Any`, `-> None`, docstring
`Tool.validate_arguments`	`-> None`, docstring
`Tool.forward`	`args: Any`, `*kwargs: Any`, `-> Any`, docstring
`Tool.__call__`	`args: Any`, `*kwargs: Any`, `-> Any`, docstring
`Tool.save`	`-> None`
`Tool.from_hub`	`**kwargs: Any`, `-> "Tool"`
`Tool.from_code`	`**kwargs: Any`, `-> "Tool"`, docstring
`Tool.from_space`	`-> "Tool"`
`Tool.from_gradio`	`gradio_tool: Any`, `-> "Tool"`
`Tool.from_langchain`	`langchain_tool: Any`, `-> "Tool"`
`launch_gradio_demo`	`-> None`
`load_tool`	`repo_id: str`, `**kwargs: Any`, `-> "Tool"`
`add_description`	`description: str`, `-> Callable`, inner types
`ToolCollection.__init__`	`-> None`

All of these are additive metadata — zero behaviour change, PEP 484 compliant, PEP 8 preserved.

Why This Matters for smolagents Specifically

smolagents is built around the idea that type hints are the API.
The @tool decorator calls _convert_type_hints_to_json_schema under the hood to build the LLM tool schema.
If the base Tool class itself is inconsistently annotated, static analysis tools (mypy, pyright, basedpyright) surface false positives when subclassing it, making the developer experience worse.

After the patch:

mypy --strict on tools.py goes from 16 errors to 0
IDE autocomplete correctly infers return types from all class methods
The class docstring example in the smolagents docs becomes type-checkable end-to-end

The PR

The changes are on our fork at github.com/yehorcallmedai-maker/smolagents, branch symbiote/plan-smolagents-tools.

The patch was generated by symbiote_smolagents_patch.py — a deterministic replacement script with one targeted substitution per annotation target, making the diff clean and easy to review.

Diff stats: +87 lines, −12 lines across tools.py only.
No tests were modified. The existing test suite passes unchanged.

What's Next

Symbiote's next pass will target src/smolagents/models.py and src/smolagents/agents.py, where similar annotation gaps exist in the model wrapper classes.

If you maintain a Python library and want a Symbiote pass on your codebase — open-source or private — reach out at callmedai.com.

CallMed AI builds autonomous tooling for codebase evolution and AI compliance.
Symbiote is our open-architecture agent for Python annotation and documentation at scale.

Live PR: https://github.com/huggingface/smolagents/pull/2333