Metadata-Version: 2.4
Name: fabricatio-question
Version: 0.1.7
Summary: An extension of fabricatio, which provide the capability to question user to make better planning and etc.
Project-URL: Homepage, https://github.com/Whth/fabricatio
Project-URL: Repository, https://github.com/Whth/fabricatio
Project-URL: Issues, https://github.com/Whth/fabricatio/issues
Author-email: Whth <zettainspector@foxmail.com>
License: MIT License
        
        Copyright (c) 2025 Whth Yotta
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Requires-Dist: fabricatio-core
Requires-Dist: questionary>=2.1.0
Description-Content-Type: text/markdown

# `fabricatio-question`

[MIT](https://img.shields.io/badge/license-MIT-blue.svg)
![Python Versions](https://img.shields.io/pypi/pyversions/fabricatio-question)
[![PyPI Version](https://img.shields.io/pypi/v/fabricatio-question)](https://pypi.org/project/fabricatio-question/)
[![PyPI Downloads](https://static.pepy.tech/badge/fabricatio-question/week)](https://pepy.tech/projects/fabricatio-question)
[![PyPI Downloads](https://static.pepy.tech/badge/fabricatio-question)](https://pepy.tech/projects/fabricatio-question)
[![Build Tool: uv](https://img.shields.io/badge/built%20with-uv-orange)](https://github.com/astral-sh/uv)

Interactive questioning extension for fabricatio agents. Generates LLM-driven selection prompts and presents them to users via terminal UI, enabling agents to gather structured feedback during planning and decision-making.

## Installation

```bash
pip install fabricatio[question]
# or
uv pip install fabricatio[question]
```

For a full installation including all fabricatio components:

```bash
pip install fabricatio[full]
```

## API

### Capability: `Questioning`

Extends `fabricatio_core.capabilities.propose.Propose`. Mix into an agent to add interactive questioning.

| Method | Description |
|---|---|
| `async selection(q: str, k: int = 1, **kwargs) -> str \| List[str]` | Generates a selection question via LLM, presents it interactively, and returns the user's choice(s). `k=1` returns a single string; `k>1` returns a list of up to `k` selections. |
| `async selection_string(q: str, k: int = 1, **kwargs) -> str` | Like `selection()`, but returns a formatted string with the question topic, options, and selected indices. |

### Model: `SelectionQuestion`

A `SketchedAble` model representing an interactive selection prompt. Generated by the LLM from a user-provided topic.

| Field | Type | Description |
|---|---|---|
| `q` | `str` | Question text displayed to the user. |
| `option` | `List[str]` | Available choices. |

| Method | Description |
|---|---|
| `async single() -> str` | Presents a single-choice selection via `questionary.select`. |
| `async multiple(k: int = 0) -> List[str]` | Presents a multi-choice checkbox. When `k > 0`, validates that exactly `k` options are selected. |

### Utilities

`fabricatio_question.utils`

| Function | Description |
|---|---|
| `async ask_retain(candidates: List[str]) -> List[str]` | Presents a checkbox list with all candidates pre-checked, returning the user's retained subset. |
| `async ask_retain(candidates, value_mapping) -> List[V]` | Overload that maps retained choices back through `value_mapping`. |
| `async ask_edit(text_seq: List[str]) -> List[str]` | Prompts the user to edit each string sequentially; only non-empty edits are returned. |

### Configuration

`fabricatio_question.config.question_config` — a `QuestionConfig` dataclass with template names used during question generation:

| Field | Default | Description |
|---|---|---|
| `selection_template` | `"built-in/selection"` | Template for generating the `SelectionQuestion` prompt. |
| `selection_display_template` | `"built-in/selection_display"` | Template for rendering `selection_string` output. |

## Usage

```python
from fabricatio_question.capabilities.questioning import Questioning

class MyAgent(Questioning):
    ...

async def example():
    agent = MyAgent()

    # Single choice — returns a str
    choice: str = await agent.selection("Pick a database backend")

    # Multiple choices — returns list[str]
    picks: list[str] = await agent.selection("Select features to enable", k=3)

    # Get a formatted response string
    result: str = await agent.selection_string("Choose a deployment target")
```

```python
from fabricatio_question.utils import ask_retain, ask_edit

# Let the user prune a candidate list
kept: list[str] = await ask_retain(["auth", "caching", "logging", "metrics"])

# Let the user edit a list of strings in-place
edited: list[str] = await ask_edit(["step 1", "step 2", "step 3"])
```

## Dependencies

- `fabricatio-core` — core interfaces and capabilities
- `questionary>=2.1.0` — interactive terminal prompts

## License

MIT — see [LICENSE](./LICENSE)
