fabricatio-capabilities

MIT

High-level LLM agent capabilities for structured extraction, content rating, sequence ordering, text summarization, and task dispatch. Built on fabricatio-core.

Installation

pip install fabricatio[capabilities]
# or
uv pip install fabricatio[capabilities]

For the full Fabricatio suite:

pip install fabricatio[full]

Overview

fabricatio-capabilities provides opinionated, composable mixins that give agents higher-level reasoning abilities:

• Extract structured data from unstructured text into Pydantic models.
• Rate content against multi-criteria rubrics, including automated criteria drafting, weighted composite scoring, and top-k selection.
• Order sequences of items (strings or WithBriefing objects) by a requirement or by computed scores.
• Summarize raw text into a length-bounded summary (characters, words, or sentences).
• Propose & dispatch tasks to candidate roles based on semantic matching.
• Patch and persist Pydantic models with type-safe update mechanisms.

Every capability is an ABC mixin — subclass alongside your agent's base to compose exactly the abilities you need.

Package Structure

fabricatio_capabilities/
 ├── capabilities/         # Mixin classes
 │   ├── extract.py        # Extract — structured extraction from text
 │   ├── rating.py         # Rating — multi-criteria rating, criteria drafting, composite scoring, best-k selection
 │   ├── rating_image.py   # RatingImage — rate attached images via a vision-capable LLM
 │   ├── summarize.py      # Summarize + LengthType — length-window-bounded summarization
 │   └── task.py           # ProposeTask, DispatchTask — task proposal and delegation
 ├── models/               # Reusable Pydantic base models
 │   ├── generic.py        # Patch, SequencePatch, PersistentAble, FinalizedDumpAble, ModelHash, UpdateFrom, etc.
 │   └── kwargs_types.py   # TypedDict kwargs: CompositeScoreKwargs, OrderStringKwargs, ReferencedKwargs
 └── config.py             # Template name configuration (CapabilitiesConfig)

Key Classes

Capabilities

Models

Kwargs Types

CompositeScoreKwargs, BestKwargs, OrderStringKwargs, ReferencedKwargs[T] — TypedDicts that extend ValidateKwargs with capability-specific parameters (topic, criteria, weights, manual, reference).

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.capabilities] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.capabilities] in pyproject.toml, or via FABRICATIO_EXT__CAPABILITIES__<FIELD_UPPER> environment variables.

[ext.capabilities]
extract_template = "built-in/extract"
as_prompt_template = "built-in/as_prompt"
dispatch_task_template = "built-in/dispatch_task"
rate_fine_grind_template = "built-in/rate_fine_grind"
rate_image_template = "built-in/rate_image"
draft_rating_manual_template = "built-in/draft_rating_manual"
draft_rating_criteria_template = "built-in/draft_rating_criteria"
extract_reasons_from_examples_template = "built-in/extract_reasons_from_examples"
extract_criteria_from_reasons_template = "built-in/extract_criteria_from_reasons"
draft_rating_weights_klee_template = "built-in/draft_rating_weights_klee"
order_string_template = "built-in/order_string"
order_briefed_template = "built-in/order_briefed"
summarize_template = "built-in/summarize"

Usage

Structured Extraction

from pydantic import BaseModel
from fabricatio_capabilities.capabilities.extract import Extract

class Person(BaseModel):
    name: str
    age: int

class MyAgent(Extract, YourBaseAgent):
    ...

agent = MyAgent()
person = await agent.extract(Person, "Alice is 30 years old.")
assert person.name == "Alice"

Multi-Criteria Rating

from fabricatio_capabilities.capabilities.rating import Rating

class MyAgent(Rating, YourBaseAgent):
    ...

agent = MyAgent()
manual = await agent.draft_rating_manual("essay quality", {"clarity", "argument"})
scores = await agent.rate("The essay is well-structured.", manual, (0.0, 10.0))

Text Summarization

from fabricatio_capabilities.capabilities.summarize import LengthType, Summarize

class MyAgent(Summarize, YourBaseAgent):
    ...

caption = await agent.summarize(
    raw,
    max_length=200,                # box width, in length_type units
    min_length=160,                # optional floor; default = 80% of max_length
    requirement="keep the key facts and the formal tone",
    length_type=LengthType.Chars,  # Chars (default), Words, or Sentences
)

The output is validated to land inside the [min_length, max_length] window (measured after stripping); out-of-window responses are retried and, after three failed attempts, the method returns None. Bounds are optional: pass neither max_length nor min_length for unconstrained summarization, or pass only min_length for a floor with no ceiling.

When a single pass keeps missing the window, force_summarize feeds each oversized output back as the input of the next pass and restarts from the raw text after under-min outputs (max_iterations=5 by default); if the window stays unreachable it returns the attempt closest to the window:

summary = await agent.force_summarize(
    raw,
    max_length=200,
    requirement="keep the key facts and the formal tone",
    max_iterations=5,
)

Sequence Ordering

from fabricatio_capabilities.capabilities.order import Ordering

class MyAgent(Ordering, YourBaseAgent):
    ...

agent = MyAgent()
ordered = await agent.order(
    ["clean kitchen", "buy groceries", "pay bills"],
    "by urgency",
)

Task Dispatch

from fabricatio_capabilities.capabilities.task import ProposeTask, DispatchTask

class MyAgent(ProposeTask, DispatchTask, YourBaseAgent):
    ...

agent = MyAgent()
task = await agent.propose_task("Summarize this document.")
result = await agent.dispatch_task(task, candidates={role_a, role_b})

Patching Models

from pydantic import BaseModel
from fabricatio_capabilities.models.generic import Patch

class User(BaseModel):
    name: str
    age: int
    email: str = ""

class UserPatch(Patch[User], BaseModel):
    name: str | None = None
    email: str | None = None

user = User(name="Alice", age=30)
patch = UserPatch(name="Bob")
updated = patch.apply(user)
assert updated.name == "Bob" and updated.age == 30

Dependencies

• fabricatio-core — core interfaces (Propose, UseLLM, Task, Role, TEMPLATE_MANAGER)
• orjson — fast JSON serialization
• pydantic — model validation and schema generation
• more-itertools — utility iterators

License

MIT — see LICENSE