agentforge-py 0.2.1__py3-none-any.whl

agentforge/templates/docs-qa/src/{{project_slug.replace('-', '_')}}/main.py

@@ -0,0 +1,32 @@
+"""Entry point for {{ project_name }}.
+
+Docs / source Q&A. Wires `file_read` + `web_search` so the agent
+can pull both local docs and external context. Outputs
+`NarrativeFinding`s (feat-008).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentforge import Agent
+from agentforge.tools import file_read, web_search
+
+
+async def run_agent(task: str) -> str:
+    async with Agent(tools=[file_read, web_search]) as agent:
+        result = await agent.run(task)
+        return str(result.output)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print('Usage: python -m {{ project_slug | replace("-", "_") }} "<question>"')
+        sys.exit(1)
+    output = asyncio.run(run_agent(" ".join(sys.argv[1:])))
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

agentforge/templates/minimal/.env.example

@@ -0,0 +1,11 @@
+# Environment variables for {{ project_name }}.
+# Copy this file to `.env` and fill in real values.
+
+{% if llm_provider == 'bedrock' -%}
+# AWS Bedrock credentials (or use AWS_PROFILE / instance role).
+AWS_REGION=us-east-1
+{% elif llm_provider == 'anthropic' -%}
+ANTHROPIC_API_KEY=
+{% else -%}
+OPENAI_API_KEY=
+{% endif %}

agentforge/templates/minimal/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Keep .agentforge-state checked in — it tracks framework managed
+# files for upgrade.

agentforge/templates/minimal/README.md

@@ -0,0 +1,28 @@
+# {{ project_name }}
+
+{{ description }}
+
+## Getting started
+
+```bash
+uv sync
+cp .env.example .env
+# Fill in credentials in .env, then:
+python -m {{ project_slug | replace('-', '_') }} "your task here"
+```
+
+## Configuration
+
+`agentforge.yaml` is the agent's wiring — model, budget, modules.
+See `agentforge config show` for the resolved config and
+`agentforge config validate` to check it.
+
+## Upgrades
+
+```bash
+agentforge upgrade
+```
+
+Pulls in framework updates while preserving your customisations.
+See `agentforge status` for what's managed-by-the-framework vs
+forked-by-you.

agentforge/templates/minimal/agentforge.yaml

@@ -0,0 +1,10 @@
+agent:
+  name: "{{ project_slug }}"
+  model: "{% if llm_provider == 'bedrock' %}bedrock:us.anthropic.claude-sonnet-4-5-20250929{% elif llm_provider == 'anthropic' %}anthropic:claude-sonnet-4-5{% else %}openai:gpt-4o{% endif %}"
+  budget:
+    usd: 2.0
+  max_iterations: 25
+
+logging:
+  level: "INFO"
+  format: "text"

agentforge/templates/minimal/copier.yml

@@ -0,0 +1,52 @@
+# Copier template: minimal AgentForge agent (feat-011).
+#
+# Simplest working starter: one Agent, one tool, one test. No
+# persistence, no evaluators, no observability. Good for proofs of
+# concept and for learning what a working agent looks like.
+
+_min_copier_version: "9.4.0"
+
+# Render the answer file so `agentforge upgrade` knows what to ask.
+_answers_file: ".agentforge-state/answers.yml"
+
+# Render every file's content as a Jinja template (Cookiecutter-
+# style). Default (templates_suffix=".jinja") would force every
+# file to be named `foo.py.jinja`, which is ugly.
+_templates_suffix: ""
+
+# No `_subdirectory` — template files live at the root and render
+# directly into the destination directory. The CLI passes
+# `dst_path = ./<project_slug>` so the rendered output has a clean
+# project root.
+
+project_name:
+  type: str
+  help: "Human-readable project name (e.g. 'My PR Reviewer')."
+  default: "My Agent"
+
+project_slug:
+  type: str
+  help: "Python package + directory name (kebab-case-ok, becomes snake_case in Python imports)."
+  default: "my-agent"
+  validator: >-
+    {% if not (project_slug | regex_search('^[a-z][a-z0-9-]*$')) %}
+    Must be lowercase alphanumeric + dashes, starting with a letter.
+    {% endif %}
+
+llm_provider:
+  type: str
+  help: "Which LLM provider to use?"
+  choices:
+    Bedrock (AWS): bedrock
+    Anthropic (direct): anthropic
+    OpenAI: openai
+  default: bedrock
+
+description:
+  type: str
+  help: "One-line description of the agent."
+  default: "An AgentForge agent."
+
+# Template metadata pulled into the lock-file marker header by the
+# `agentforge new` CLI after Copier finishes rendering.
+_template_name: "minimal"

agentforge/templates/minimal/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "{{ project_slug }}"
+version = "0.0.0"
+description = "{{ description }}"
+requires-python = ">=3.13"
+dependencies = [
+    "agentforge-py",
+{%- if llm_provider == 'bedrock' %}
+    "agentforge-bedrock",
+{%- endif %}
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_slug | replace('-', '_') }}"]

agentforge/templates/minimal/src/{{project_slug.replace('-', '_')}}/__init__.py

@@ -0,0 +1,5 @@
+"""{{ project_name }}: {{ description }}"""
+
+from {{ project_slug | replace('-', '_') }}.main import run_agent
+
+__all__ = ["run_agent"]

agentforge/templates/minimal/src/{{project_slug.replace('-', '_')}}/main.py

@@ -0,0 +1,34 @@
+"""Entry point for {{ project_name }}.
+
+Edit this file to add tools, prompts, evaluators, etc. The
+`Agent` constructor surface is feat-001's locked Public API — see
+`docs/features/feat-001-core-contracts-and-agent.md` in the
+agentforge-py repo for every kwarg.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentforge import Agent
+
+
+async def run_agent(task: str) -> str:
+    """Run the agent against `task` and return its output."""
+    async with Agent() as agent:
+        result = await agent.run(task)
+        return str(result.output)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print('Usage: python -m {{ project_slug | replace("-", "_") }} "<task>"')
+        sys.exit(1)
+    task = " ".join(sys.argv[1:])
+    output = asyncio.run(run_agent(task))
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

agentforge/templates/patch-bot/.env.example

@@ -0,0 +1,8 @@
+# Credentials for {{ project_name }}.
+{% if llm_provider == 'bedrock' -%}
+AWS_REGION=us-east-1
+{% elif llm_provider == 'anthropic' -%}
+ANTHROPIC_API_KEY=
+{% else -%}
+OPENAI_API_KEY=
+{% endif %}

agentforge/templates/patch-bot/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

agentforge/templates/patch-bot/README.md

@@ -0,0 +1,13 @@
+# {{ project_name }}
+
+{{ description }} Emits `PatchFinding`s — structured unified diffs
+with rationale + confidence — for downstream consumers to apply.
+
+```bash
+uv sync
+cp .env.example .env
+python -m {{ project_slug | replace('-', '_') }} "replace deprecated time.clock() in src/"
+```
+
+The agent does NOT apply the patches itself — the consumer (CI
+bot, codemod script, etc.) reads `result.findings` and decides.

agentforge/templates/patch-bot/agentforge.yaml

@@ -0,0 +1,15 @@
+agent:
+  name: "{{ project_slug }}"
+  model: "{% if llm_provider == 'bedrock' %}bedrock:us.anthropic.claude-sonnet-4-5-20250929{% elif llm_provider == 'anthropic' %}anthropic:claude-sonnet-4-5{% else %}openai:gpt-4o{% endif %}"
+  system_prompt: |
+    You generate patches. For each fix, emit a `PatchFinding` with
+    a unified-diff `patch`, a one-line `rationale`, and a
+    `confidence` in [0, 1]. Only return patches you can defend with
+    evidence from the source.
+  budget:
+    usd: 5.0
+  max_iterations: 40
+
+logging:
+  level: "INFO"
+  format: "text"

agentforge/templates/patch-bot/copier.yml

@@ -0,0 +1,31 @@
+# Copier template: patch-bot agent (feat-011).
+#
+# Emits PatchFinding — structured diffs with rationale and
+# confidence. Use for codemod / auto-fix workflows where the
+# downstream consumer applies the patch.
+
+_min_copier_version: "9.4.0"
+_answers_file: ".agentforge-state/answers.yml"
+_templates_suffix: ""
+
+project_name:
+  type: str
+  default: "Patch Bot"
+
+project_slug:
+  type: str
+  default: "patch-bot"
+
+llm_provider:
+  type: str
+  choices:
+    Bedrock (AWS): bedrock
+    Anthropic (direct): anthropic
+    OpenAI: openai
+  default: bedrock
+
+description:
+  type: str
+  default: "A patch-emitting AgentForge agent."
+
+_template_name: "patch-bot"

agentforge/templates/patch-bot/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "{{ project_slug }}"
+version = "0.0.0"
+description = "{{ description }}"
+requires-python = ">=3.13"
+dependencies = [
+    "agentforge-py",
+{%- if llm_provider == 'bedrock' %}
+    "agentforge-bedrock",
+{%- endif %}
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_slug | replace('-', '_') }}"]

agentforge/templates/patch-bot/src/{{project_slug.replace('-', '_')}}/__init__.py

@@ -0,0 +1,5 @@
+"""{{ project_name }}: {{ description }}"""
+
+from {{ project_slug | replace('-', '_') }}.main import run_agent
+
+__all__ = ["run_agent"]

agentforge/templates/patch-bot/src/{{project_slug.replace('-', '_')}}/main.py

@@ -0,0 +1,32 @@
+"""Entry point for {{ project_name }}.
+
+Emits PatchFinding (feat-008) — structured unified diffs with
+rationale + confidence. Tools include `file_read` so the bot can
+pull source context before proposing a patch.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentforge import Agent
+from agentforge.tools import file_read
+
+
+async def run_agent(task: str) -> str:
+    async with Agent(tools=[file_read]) as agent:
+        result = await agent.run(task)
+        return str(result.output)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print('Usage: python -m {{ project_slug | replace("-", "_") }} "<task>"')
+        sys.exit(1)
+    output = asyncio.run(run_agent(" ".join(sys.argv[1:])))
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

agentforge/templates/research/.env.example

@@ -0,0 +1,8 @@
+# Credentials for {{ project_name }}.
+{% if llm_provider == 'bedrock' -%}
+AWS_REGION=us-east-1
+{% elif llm_provider == 'anthropic' -%}
+ANTHROPIC_API_KEY=
+{% else -%}
+OPENAI_API_KEY=
+{% endif %}

agentforge/templates/research/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

agentforge/templates/research/README.md

@@ -0,0 +1,14 @@
+# {{ project_name }}
+
+{{ description }} Open-ended research with citations. Uses the
+Plan-Execute strategy + web_search to break a complex question
+into sub-tasks, then synthesises a `NarrativeFinding`.
+
+```bash
+uv sync
+cp .env.example .env
+python -m {{ project_slug | replace('-', '_') }} "what changed in claude-sonnet 4.5 vs 4.7?"
+```
+
+Defaults to `web_search` (DuckDuckGo HTML scrape). Replace with a
+serper / tavily backend by passing `search_fn=` to `WebSearchTool`.

agentforge/templates/research/agentforge.yaml

@@ -0,0 +1,17 @@
+agent:
+  name: "{{ project_slug }}"
+  model: "{% if llm_provider == 'bedrock' %}bedrock:us.anthropic.claude-sonnet-4-5-20250929{% elif llm_provider == 'anthropic' %}anthropic:claude-sonnet-4-5{% else %}openai:gpt-4o{% endif %}"
+  strategy: "plan-execute"
+  system_prompt: |
+    You answer open-ended research questions. Plan the sub-tasks,
+    execute them (use web_search liberally), then synthesise into a
+    NarrativeFinding: `body` is the markdown answer; `references`
+    is every URL you actually used. Don't cite sources you didn't
+    open.
+  budget:
+    usd: 5.0
+  max_iterations: 50
+
+logging:
+  level: "INFO"
+  format: "text"

agentforge/templates/research/copier.yml

@@ -0,0 +1,31 @@
+# Copier template: research agent (feat-011).
+#
+# Long-form research with citations. Uses Plan-Execute strategy for
+# multi-step questions, web_search for sources, NarrativeFinding for
+# the output shape.
+
+_min_copier_version: "9.4.0"
+_answers_file: ".agentforge-state/answers.yml"
+_templates_suffix: ""
+
+project_name:
+  type: str
+  default: "Research Agent"
+
+project_slug:
+  type: str
+  default: "research-agent"
+
+llm_provider:
+  type: str
+  choices:
+    Bedrock (AWS): bedrock
+    Anthropic (direct): anthropic
+    OpenAI: openai
+  default: bedrock
+
+description:
+  type: str
+  default: "A research AgentForge agent."
+
+_template_name: "research"

agentforge/templates/research/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "{{ project_slug }}"
+version = "0.0.0"
+description = "{{ description }}"
+requires-python = ">=3.13"
+dependencies = [
+    "agentforge-py",
+{%- if llm_provider == 'bedrock' %}
+    "agentforge-bedrock",
+{%- endif %}
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_slug | replace('-', '_') }}"]

agentforge/templates/research/src/{{project_slug.replace('-', '_')}}/__init__.py

@@ -0,0 +1,5 @@
+"""{{ project_name }}: {{ description }}"""
+
+from {{ project_slug | replace('-', '_') }}.main import run_agent
+
+__all__ = ["run_agent"]

agentforge/templates/research/src/{{project_slug.replace('-', '_')}}/main.py

@@ -0,0 +1,31 @@
+"""Entry point for {{ project_name }}.
+
+Research with citations. Plan-Execute strategy + web_search.
+Outputs NarrativeFinding (feat-008).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentforge import Agent
+from agentforge.tools import web_search
+
+
+async def run_agent(question: str) -> str:
+    async with Agent(tools=[web_search]) as agent:
+        result = await agent.run(question)
+        return str(result.output)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print('Usage: python -m {{ project_slug | replace("-", "_") }} "<research question>"')
+        sys.exit(1)
+    output = asyncio.run(run_agent(" ".join(sys.argv[1:])))
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

agentforge/templates/triage/.env.example

@@ -0,0 +1,8 @@
+# Credentials for {{ project_name }}.
+{% if llm_provider == 'bedrock' -%}
+AWS_REGION=us-east-1
+{% elif llm_provider == 'anthropic' -%}
+ANTHROPIC_API_KEY=
+{% else -%}
+OPENAI_API_KEY=
+{% endif %}

agentforge/templates/triage/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

agentforge/templates/triage/README.md

@@ -0,0 +1,14 @@
+# {{ project_name }}
+
+{{ description }} Classifies incoming items by severity + category.
+Uses Haiku-tier models — triage is high-volume; the smaller model
+keeps cost bounded.
+
+```bash
+uv sync
+cp .env.example .env
+python -m {{ project_slug | replace('-', '_') }} "triage this issue text..."
+```
+
+Add a `Coverage` evaluator with a known-issue reference set to
+score how completely the agent classifies a batch.

agentforge/templates/triage/agentforge.yaml

@@ -0,0 +1,25 @@
+agent:
+  name: "{{ project_slug }}"
+  model: "{% if llm_provider == 'bedrock' %}bedrock:us.anthropic.claude-haiku-4-5{% elif llm_provider == 'anthropic' %}anthropic:claude-haiku-4-5{% else %}openai:gpt-4o-mini{% endif %}"
+  system_prompt: |
+    You triage incoming issues / tickets / alerts. For each item
+    emit a `SimpleFinding` with `severity` in
+    {critical, warning, suggestion, info}, a one-word `category`,
+    a one-line `message`, and an actionable `recommendation`.
+    Classify, don't speculate.
+  budget:
+    usd: 1.0
+  max_iterations: 15
+
+# Pair with a Coverage evaluator once you have a known-issue
+# reference set:
+#
+# modules:
+#   evaluators:
+#     - name: coverage
+#       config:
+#         reference: ["security-issue-1", "perf-issue-2", ...]
+
+logging:
+  level: "INFO"
+  format: "text"

agentforge/templates/triage/copier.yml

@@ -0,0 +1,31 @@
+# Copier template: triage agent (feat-011).
+#
+# Classifies incoming issues / tickets / alerts by severity +
+# category. Emits SimpleFinding per item; pairs well with a
+# Coverage evaluator against a known-issue set.
+
+_min_copier_version: "9.4.0"
+_answers_file: ".agentforge-state/answers.yml"
+_templates_suffix: ""
+
+project_name:
+  type: str
+  default: "Triage"
+
+project_slug:
+  type: str
+  default: "triage"
+
+llm_provider:
+  type: str
+  choices:
+    Bedrock (AWS): bedrock
+    Anthropic (direct): anthropic
+    OpenAI: openai
+  default: bedrock
+
+description:
+  type: str
+  default: "A triage AgentForge agent."
+
+_template_name: "triage"

agentforge/templates/triage/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "{{ project_slug }}"
+version = "0.0.0"
+description = "{{ description }}"
+requires-python = ">=3.13"
+dependencies = [
+    "agentforge-py",
+{%- if llm_provider == 'bedrock' %}
+    "agentforge-bedrock",
+{%- endif %}
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_slug | replace('-', '_') }}"]

agentforge/templates/triage/src/{{project_slug.replace('-', '_')}}/__init__.py

@@ -0,0 +1,5 @@
+"""{{ project_name }}: {{ description }}"""
+
+from {{ project_slug | replace('-', '_') }}.main import run_agent
+
+__all__ = ["run_agent"]

agentforge/templates/triage/src/{{project_slug.replace('-', '_')}}/main.py

@@ -0,0 +1,30 @@
+"""Entry point for {{ project_name }}.
+
+Triage: classify incoming items into severity + category. No
+external tools by default — the agent works from the text alone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentforge import Agent
+
+
+async def run_agent(item: str) -> str:
+    async with Agent() as agent:
+        result = await agent.run(item)
+        return str(result.output)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print('Usage: python -m {{ project_slug | replace("-", "_") }} "<item to triage>"')
+        sys.exit(1)
+    output = asyncio.run(run_agent(" ".join(sys.argv[1:])))
+    print(output)
+
+
+if __name__ == "__main__":
+    main()