Metadata-Version: 2.5
Name: specfill
Version: 0.1.0
Summary: Interactive TUI that interviews you about underspecified points in a project seed prompt and produces a refined prompt
Project-URL: Repository, https://github.com/kklemon/specfill
Project-URL: Issues, https://github.com/kklemon/specfill/issues
Author-email: Kristian Klemon <kristian.klemon@softmax-ai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,coding-agents,llm,prompt-engineering,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: keyring>=25
Requires-Dist: pydantic-ai-slim[anthropic,google,openai]>=2.0
Requires-Dist: pydantic-settings>=2.6
Requires-Dist: pyperclip>=1.9
Requires-Dist: textual>=1.0
Requires-Dist: tomli-w>=1.0
Description-Content-Type: text/markdown

# specfill

An interactive TUI that fills the gaps in your project seed prompts.

You paste a long "seed" prompt you intend to hand to a coding agent (or load it
from a file). An LLM agent researches the topic with model-native web search,
finds the aspects that are underspecified enough that the agent would have to
guess, and interviews you about them — plan-mode style, one question at a time,
with concrete arrow-key options, multi-select where it makes sense, an
"Other: enter text" escape hatch, and skipping. Questions come in adaptive
rounds (in the language of your prompt) until the spec is complete, or until
you press *Finish now*. The result is your original prompt, style and structure
faithfully preserved, with only the newly acquired information woven in — and
where an answer contradicts the original, the latest answer wins. Decisions you
left unresolved stay exactly as ambiguous as you wrote them; nothing is
invented.

## Installation

Requires Python ≥ 3.12 on macOS or Linux. Install as a
[uv tool](https://docs.astral.sh/uv/guides/tools/):

```sh
uv tool install specfill        # from a checkout: uv tool install .
```

On first launch a configuration wizard collects your provider preset
(**OpenAI**, **OpenAI-compatible**, **Anthropic**, or **Google**), model
identifier, API key, and an optional custom base URL. The API key is stored in
the system keyring, with a fallback to the config file (chmod 600) when no
keyring backend is available.

## Usage

```sh
specfill                  # paste your prompt into the editor
specfill my-prompt.md     # or prefill it from a file
```

Flow:

1. **Paste** your seed prompt, press `Ctrl+S` to analyze. The agent researches
   with web search before questioning (progress shown live); if your model has
   no native search, or search fails mid-session, it warns and continues.
2. **Answer** the questions — arrow keys + `Enter`/`Space` to select,
   type into *Other / details…* for free-text answers.
   `Ctrl+N` answer · `Ctrl+K` skip · `Ctrl+F` finish now.
3. **Result** streams into a scrollable preview. `c` copies it to the clipboard
   (with confirmation), `r` regenerates it from the same answers, and `p` quits
   and prints the revised prompt — and only that — to stdout.

Skipped questions are treated as "implementer's discretion" and never re-asked.

## Configuration

Settings live in `~/.config/specfill/config.toml` (honors `$XDG_CONFIG_HOME`)
and can be edited three ways: the in-app settings screen (`Ctrl+O` on the paste
screen), the CLI, or the file itself.

```sh
specfill config show                    # current configuration
specfill config path                    # config file location
specfill config set provider anthropic  # provider | model | base-url | web-search
specfill config set model claude-opus-5
specfill config set-key                 # store the API key (hidden prompt)
```

Every setting can also be overridden per-invocation via `SPECFILL_*`
environment variables (e.g. `SPECFILL_MODEL`, `SPECFILL_WEB_SEARCH=false`).
API keys resolve from the keyring first, then the config file /
`$SPECFILL_API_KEY`, then the provider's conventional variable
(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`).

LLM inference is provider-agnostic via [Pydantic AI](https://ai.pydantic.dev/)
(default model: OpenAI GPT-5.6 Sol); the UI is
[Textual](https://textual.textualize.io/).

## Development

```sh
uv sync
uv run pytest    # offline tests (scripted models, no network)
```
