fabricatio-capabilities

MIT

High-level LLM agent capabilities for structured extraction, content rating, sequence ordering, text compaction, 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.
• Compact raw text to a target length (characters, words, or sentences) while preserving its core meaning.
• 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
 │   ├── compact.py        # Compact + LengthType — length-constrained text compaction
 │   └── 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"
compact_template = "built-in/compact"

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 Compaction

from fabricatio_capabilities.capabilities.compact import Compact, LengthType

class MyAgent(Compact, YourBaseAgent):
    ...

agent = MyAgent()
compacted = await agent.compact(
    raw,
    requirement="keep the key facts and the formal tone",
    target_length=200,
    length_type=LengthType.Chars,  # Chars (default), Words, or Sentences
)

The output is validated to be at most target_length units (measured after stripping); oversized LLM responses are retried and, after three failed attempts, the method returns None.

When a single pass keeps missing the bound, force_compact feeds each oversized output back as the input of the next pass until the bound is met (max_iterations=5 by default); if the bound stays unreachable it returns the shortest attempt:

compacted = await agent.force_compact(
    raw,
    requirement="keep the key facts and the formal tone",
    target_length=200,
    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