Bits & Flames
bitsandflames/fyron

LLM

fyron.llm provides a lightweight interface for prompts over text, files, images, DataFrames, and directories. It is designed for narrative assistance, extraction prototypes, and methods-documentation support. Keep statistical analysis and clinical decisions in explicit code.

Treat LLM outputs as generated annotations that need review. The module is most useful for summarizing documents, drafting methods text, extracting candidate labels for later validation, or applying the same prompt across a DataFrame. Keep prompts versioned and store outputs next to the input identifiers.

Responsible Use Pattern

  • Keep prompts explicit and reusable.
  • Store the source text/file identifier with every generated answer.
  • Review outputs before using them as labels or report text.
  • Use deterministic code for final statistics and clinical endpoints.
  • Avoid sending sensitive data to external providers unless the deployment has been approved.

Import

python
from fyron import LLMAgent

LLMAgent

python
agent = LLMAgent(
    provider="openai",
    api_key="...",
    model="gpt-4.1-mini",
)

Constructor Parameters

ParameterRequiredTypeDefaultDescription
providerno`strNone`env LLM_PROVIDER or "openai""openai", "anyllm", or "custom".
base_urlno`strNone`env LLM_BASE_URL or OpenAI URLAPI base URL or custom endpoint.
api_keyconditionally`strNone`env LLM_API_KEYRequired for openai and anyllm unless auth_required=False.
modelno`strNone`env LLM_MODEL or "gpt-4.1-mini"Model name.
timeoutno`intNone`env LLM_TIMEOUT or 30Request timeout.
extra_headersno`dictNone`NoneAdditional HTTP headers.
auth_requiredno`boolNone`provider-dependentWhether missing API key should raise.
verify_sslnoboolTrueVerify TLS certificates.

prompt / chat

Sends one prompt. chat is an alias for prompt.

python
response = agent.prompt("Summarize the cohort in three bullet points.")
ParameterRequiredDefaultDescription
user_promptyesnonePrompt text.
image_pathnoNoneOptional image path for multimodal mode.
file_pathnoNoneOptional file path for multimodal/file mode.
modeno"text""text" or a provider-supported multimodal mode.

Returns the model response as a string.

prompt_dataframe

Runs a prompt over a DataFrame text column and appends an output column.

python
out = agent.prompt_dataframe(
    df=notes_df,
    text_col="note_text",
    prompt="Extract clinically relevant adverse events.",
    output_col="adverse_events",
    output_csv="notes_with_adverse_events.csv",
)
ParameterRequiredDefaultDescription
dfyesnoneInput DataFrame.
text_colyesnoneColumn containing text.
promptyesnonePrompt or instruction prepended/appended to each row.
output_colno"llm_output"Name of generated output column.
output_csvnoNoneOptional CSV path to write results.
format_funcnoNoneCallable to format prompt per row.
image_colnoNoneColumn containing image paths.
file_colnoNoneColumn containing file paths.
modeno"text"Text or multimodal mode.

Aliases: prompt_df, run_prompt_on_dataframe. Lower-level method: run_on_dataframe.

prompt_documents

Runs a prompt over a list of text strings or file paths.

python
results = agent.prompt_documents(
    documents=["note text", "/path/to/report.txt"],
    prompt="Summarize clinically relevant findings.",
    output_csv="doc_summaries.csv",
)
ParameterRequiredDefaultDescription
documentsyesnoneList of text strings or file paths.
promptyesnonePrompt applied to each document.
output_csvnoNoneOptional CSV output.
modeno"text"Text or multimodal mode.

Alias/lower-level method: run_on_documents.

describe_python_file

Generates a methods-style markdown description of a Python file.

python
md = agent.describe_python_file(
    file_path="src/project/pipeline.py",
    output_md="docs/methods_pipeline.md",
)
ParameterRequiredDefaultDescription
file_pathyesnonePython file to describe.
output_mdyesnoneMarkdown file to write.
promptnoNoneCustom prompt.

Returns generated markdown text.

prompt_directory

Runs a prompt over files in a directory.

python
results = agent.prompt_directory(
    input_dir="notes",
    prompt="Extract diagnoses.",
    glob="*.txt",
)
ParameterRequiredDefaultDescription
input_diryesnoneDirectory to scan.
promptyesnonePrompt applied to each file.
globno"*.txt"File pattern.
modeno"text"Text or multimodal mode.

Alias: run_on_directory.

Practical Tips

  • Do not send protected health information to external APIs unless your deployment and agreements allow it.
  • Use output_csv for batch prompts so runs are auditable.
  • Keep prompts version-controlled when using LLM outputs in research workflows.
  • Treat LLM outputs as extracted/narrative assistance, not ground truth.