agentx-dev 3.1.2__tar.gz → 3.1.3__tar.gz

agentx_dev-3.1.3/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+All notable changes to `agentx-dev` are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/); versioning is
+[Semver](https://semver.org/).
+
+## [3.1.3] — 2026-07-22
+
+Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
+need to upgrade for functionality; upgrade to pick up the improved
+onboarding docs bundled in the sdist.
+
+### Documentation
+
+- **Tools doc rewritten to answer "how do I actually use these?"**
+  Added §0 `How each built-in tool is registered` as the entry
+  section. Two registration paths — auto vs manual — laid out in a
+  table on the first screen. Six runnable subsections covering every
+  combination:
+    - §0.1 DefaultTools via `Permissions(...)` (auto)
+    - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
+    - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
+      `vector_search_tool(store)`
+    - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
+    - §0.5 Custom `StructuredTool` from scratch
+    - §0.6 Fully-loaded runner combining all of the above
+    - §0.7 Rules on name collisions, invisible-denied-capabilities,
+      async-tool behavior
+  The existing inventory + wrapper / controls / cheat-sheet sections
+  are unchanged; they now sit after the "how to use them" primer
+  instead of before it.
+
+## [3.1.2] — 2026-07-22
+
+Patch release. Two independent fixes.
+
+### Fixed
+
+- **`llm_judge` correctly parses YES/NO across providers.** The judge
+  parser was comparing the reply's first word to the literal string
+  `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
+  equality check and marked every genuine PASS as FAIL. Claude replies
+  `"YES"` without punctuation so the bug hid during local development.
+  Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
+  insensitive) at the start of the reply. Handles every real shape:
+  `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
+  Ambiguous replies (`Maybe`, empty string) still fail closed.
+- Regression test `test_llm_judge_parses_various_verdict_shapes`
+  covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
+
+### Added
+
+- **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
+  longer need to remember which module each tool lives in:
+
+  ```python
+  from agentx_dev.Tools import (
+      StandardTool, StructuredTool,
+      AsyncStandardTool, AsyncStructuredTool,
+      web_search_tool, web_fetch_tool,
+      vector_search_tool, handoff_tool,
+      DefaultTools, Permissions,
+  )
+  ```
+
+  Both this form and the pre-existing `from agentx_dev import X`
+  form coexist. Implementation uses PEP 562 module `__getattr__`
+  and `__dir__` so re-exports are lazy (no import cost for modules
+  the caller doesn't touch) and show up in IDE autocomplete +
+  `dir(agentx_dev.Tools)`.
+
+## [3.1.1] — 2026-07-21
+
+Second batch of 3.1 features + a full docs + brand pass.
+
+### Added
+
+**Streaming through orchestration**
+- `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
+  `plan_start` / `plan` / `dispatch` / `subtask_result` /
+  `synthesize_start` / `final` / `completion` events.
+- `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
+  `completion` / `handoff` / `final` / `result` events per hop.
+- Legacy `.run()` / `.arun()` refactored to consume the streams (no
+  code duplication).
+
+**Prompt optimization — `Compiled`**
+- New `agentx_dev.Compiler` module.
+- `Compiled(runner_factory, trainset, ...)` iteratively refines a
+  runner's `system_addendum` against the eval harness. Half of
+  DSPy's power at a tenth of the surface.
+
+**Anthropic Batch API**
+- `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
+  batch rate, polls to completion, returns results in submission order.
+- Per-request error dicts on failure; token usage funneled into
+  `TokenUsage` so cost tracking stays a single source of truth.
+
+**Vector store adapters — `agentx_dev.VectorStores`**
+- `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
+  public shape as the in-memory `VectorStore` (`add` / `search` /
+  `delete` / `clear` / `__len__` / `embeddings`).
+- `vector_search_tool()` and `SemanticMemory` accept any of them.
+- SDK imports lazy; friendly `ImportError` when the underlying SDK
+  is missing.
+
+**Trace viewer (`viewer/`)**
+- Self-hosted single-page app that reads `FileHook` JSONL and renders
+  a timeline with type/text filters, summary sidebar, JSON drill-down.
+- Works from `file://`, no server required.
+
+**Docs site (`host/`)**
+- Full editorial dark-first design system (JetBrains Mono headings,
+  Inter body, `#B8FF3E` electric-lime accent).
+- Command palette (`Cmd+K`) with keyboard navigation and live search.
+- Hero code snippet with hand-tinted syntax highlighting.
+- Reading progress bar, breadcrumbs, header anchor links.
+- Sidebar sliding active marker, collapsible groups.
+- Code copy buttons, language labels.
+- Right-rail auto-TOC with `IntersectionObserver` scrollspy.
+- Dark/light theme toggle, persisted.
+- Cache-busted assets so edits land on refresh without hard-reload.
+
+**Brand identity (`brand/`)**
+- Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
+  `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
+- Copy audit dropped "small" (weak) and "LangChain" references from
+  all marketing surfaces.
+- Favicon wired into docs + trace viewer.
+
+**Test suite (`tests/`)**
+- Restored + expanded pytest suite: 127 tests passing (3 skipped for
+  absent optional SDKs).
+- Coverage: parser + all `AgentType` variants, `ToolRegistry`
+  (dispatch / dup-guard / circuit-breaker / timeout), Permissions
+  (capability gating + sandbox + traversal), budgets (cost / rate /
+  retry / non-retryable HTTP), runner loop (streaming + output_schema
+  + chat history), embeddings + `VectorStore` + `SemanticMemory`,
+  handoffs (bounded hops + history sanitization), evals harness
+  (all assertion helpers + JSON case loaders), vector-store adapter
+  shape conformance.
+
+**Docs (`docs/`)**
+- Full docs tree (34 pages), including new pages for:
+  vector store adapters, prompt optimization, batch API, trace viewer,
+  and a **use-cases** landing (13 concrete scenarios with runnable code).
+- Rewrote **Tools** page to enumerate every built-in tool with args,
+  return shape, capability flag, and use-case guidance.
+- Rewrote **Agents** page to cover all four orchestration
+  architectures (Solo / Supervisor / Handoffs / Compiled) with
+  decision trees, worked examples, and cheat sheet.
+- **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
+  parallel retrieval, self-critique, citations, user memory.
+
+**Examples**
+- `examples/agentic_rag_demo.py` — the runnable version of the
+  agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
+  runs a 3-turn scripted session proving user-notes recall works.
+
+**Package**
+- `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
+- `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
+
+### Fixed
+
+- `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
+  minimal system prompt instead of the AgentType template so the
+  ReAct `action/action_input` scaffold no longer fights the native
+  tool interface. Previously produced JSON-blob answers under GPT.
+- `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
+  and function role messages between hops so tool_call_ids from a
+  previous agent don't leak into the next model's call (OpenAI 400).
+- Docs site marker positioning uses double-`requestAnimationFrame` +
+  `document.fonts.ready` so the sidebar accent bar lands on the
+  correct row even on a cold font cache.
+- Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
+  outrank `#doc a` link styling (previously rendered lime-on-lime
+  and was invisible).
+
+### Notes
+
+- Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
+  did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
+  and includes both batches of features.
+
+## [3.1.0] — internal only (commits 52840e7)
+
+First batch of 3.1 features. Committed but not released to PyPI.
+Merged into 3.1.1 for the public release.
+
+### Added
+- Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
+- Parallel per-turn tool dispatch in `AgentRunner`
+  (`bind_tools_natively=True`, `parallel_tool_workers`).
+- Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
+- RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
+  `VectorStore`, `VectorHit`, `vector_search_tool()`).
+- Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
+  `HandoffCoordinator`, `HandoffResult`).
+- Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
+  helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
+- `TokenUsage.cache_hit_ratio` property.
+
+## [3.0.6] — 2026-03 (baseline)
+
+Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
+persistent state, scrubbed subprocess env, path sanitizer,
+`permissions.json` mode 0o600, ReDoS guard on `grep`,
+`invoke`/`ainvoke` accept bare strings and message lists).

agentx_dev-3.1.3/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to agentx-dev
+
+Thanks for your interest. This is a solo-authored framework, so a few
+process choices are opinionated -- they exist to keep the surface area
+small and the codebase readable.
+
+## Getting set up
+
+```bash
+git clone https://github.com/shadrach098/Bruce_framework.git
+cd Bruce_framework
+python -m venv .venv && source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[dev,anthropic]"
+```
+
+Sanity check:
+
+```bash
+pytest tests/            # should show 127 passing, 3 skipped
+python -c "import agentx_dev; print(agentx_dev.__all__)"
+```
+
+## Before you open a PR
+
+1. **Run the tests.** `pytest tests/ -q` from the repo root.
+2. **Add tests** for whatever you changed. Every existing subsystem
+   has a `tests/test_<module>.py`; add cases there.
+3. **Keep the change focused.** One PR per feature or fix. If your
+   change touches five modules and adds three exports, split it.
+4. **Preserve existing behavior** unless the change is explicitly a
+   breaking one. Backwards-compat is a real value.
+5. **Update docs** if you added or changed a public API. `docs/`
+   holds the source; run `python host/build_data.py` to regenerate
+   the browsable site's `data.js`.
+
+## Commit + PR style
+
+- **Commit messages:** `<type>: <short summary>` where type is one of
+  `feat` / `fix` / `docs` / `test` / `refactor` / `chore`. Follow
+  with a blank line and the body if the summary isn't enough. Look
+  at recent commits (`git log --oneline -20`) for the shape.
+- **PR titles:** same shape as the commit message. If the PR has
+  multiple commits, the title summarizes the whole PR.
+- **PR descriptions:** what changed, why, and one before/after
+  example if the change is user-visible.
+
+## What lands and what doesn't
+
+Things that land easily:
+
+- Bug fixes with a regression test.
+- New tools that follow the existing patterns.
+- Docs improvements (more examples, clearer explanations, fixing typos).
+- New vector-store adapters or provider adapters that follow the
+  existing interface.
+- Test coverage for uncovered paths.
+
+Things that need discussion first (open an issue):
+
+- New public classes or modules.
+- Changes to public method signatures.
+- Anything that grows the dependency footprint of the base install.
+- Anything that reshapes the runner loop, `Supervisor`, or
+  `HandoffCoordinator`.
+
+Things that don't land:
+
+- Style-only refactors that reshape existing files.
+- Adding a "generic" abstraction over one specific thing.
+- Wrapping existing SDKs "for consistency."
+- LangChain-compatibility shims.
+- Auto-generated boilerplate.
+
+## Code style
+
+- **Docstrings are the source of truth.** Every public class + method
+  gets one. Say *why* the choice was made, not just what it does.
+- **No trailing summary comments** at the end of functions.
+- **Type hints on public APIs.** Not needed on internal helpers if
+  the shape is obvious from three lines up.
+- **Small files > large files**, but one-module features > splitting
+  a single concept across three files for tidiness.
+
+## Security-sensitive changes
+
+The framework has explicit security surfaces:
+
+- `Permissions` + sandbox enforcement in `DefaultTools.py`
+- `run_python` HMAC-signed persistent state in `AutoSetup.py`
+- SSRF guard in `WebTools.py`
+- Session-id sanitizer in `DefaultTools.py`
+
+If your change touches any of these, please:
+
+1. Add a test that exercises the security check.
+2. Add a note in the PR describing the threat model you considered.
+
+See `AGENTX.md` at the repo root for the guardrails the framework
+imposes on itself.
+
+## Questions?
+
+Open an issue with the "question" label. Solo maintainer, so response
+time varies -- a good repro / minimal example is the single biggest
+help.

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/MANIFEST.in

@@ -2,6 +2,8 @@ graft agentx_dev
 graft examples
 include AGENTX.md
 include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
 include LICENSE
 prune tests
 prune examples/_sandbox

{agentx_dev-3.1.2/agentx_dev.egg-info → agentx_dev-3.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.1.2
+Version: 3.1.3
 Summary: A production-grade Python framework for building LLM agents. Multi-provider chat, permission-gated tools, RAG (in-mem + Chroma/Qdrant/pgvector), semantic memory, Supervisor + Handoffs multi-agent orchestration with streaming, evals harness, prompt caching, Batch API, prompt-optimizer, MCP integration.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/agentx_dev/Runner/AgentRun.py

@@ -1095,18 +1095,38 @@ def _read_action_input(parser_instance: BaseModel):
 
 
 class AgentRunner:
-    """
-        The main engine that orchestrates the agent's execution loop.
+    """Sync agent runner. Connects a chat model, a prompt template, and a
+    set of tools into a reason-act loop.
+
+    Typical use::
 
-        This class connects all the components of the framework: the LLM, the tools,
-        and the prompt. It manages the agent's state, including its conversational
-        history and internal scratchpad, and runs the primary "reason-act" cycle.
+        from agentx_dev import AgentRunner, AgentType, Claude, Permissions
 
-        Set ``use_function_calling=True`` to route the AgentType parser through
-        the model's native tool-calling API (when supported) instead of parsing
-        JSON out of the assistant text. The parser model itself (e.g.
-        ``React_``) is forwarded as the forced tool, so the model returns
-        ``Thought``/``action``/``action_input`` as structured arguments.
+        runner = AgentRunner(
+            model=Claude(),                             # or GPT()
+            agent=AgentType.ReAct,
+            tools=[weather_tool],                       # your tools
+            permissions=Permissions.full_access(["./workspace"]),
+        )
+        result = runner.invoke("What's the weather in Paris?")
+        print(result.content)
+
+    The runner supports three execution modes, all set via constructor
+    flags:
+
+    - **Text mode** (default) -- the model emits JSON matching the
+      AgentType parser; the runner parses out the action and dispatches
+      the tool. Works with any chat model.
+    - **Function-calling mode** (``use_function_calling=True``) -- the
+      AgentType parser itself is forwarded as the native FC tool.
+      Requires the model to implement ``call_with_tools``.
+    - **Native binding mode** (``bind_tools_natively=True``, 3.1) --
+      your tools are bound directly as native FC tools; the AgentType
+      parser is skipped. Multiple tool_use blocks in one turn dispatch
+      concurrently on a bounded thread pool. Mutually exclusive with
+      ``use_function_calling``.
+
+    For the async equivalent, see :class:`AsyncAgentRunner`.
     """
 
     def __init__(
@@ -1128,6 +1148,123 @@ class AgentRunner:
         system_addendum: Optional[str] = None,
         strict_tool_dispatch: bool = False,
     ):
+        """Construct an ``AgentRunner``.
+
+        Args:
+            model: The chat model backing every LLM call. Any
+                ``BaseChatModel`` subclass -- ``Claude()``, ``GPT()``,
+                or your own provider adapter.
+            Agent: The prompt template + parser pair the runner uses.
+                Accepts an ``AgentType`` member
+                (``AgentType.ReAct`` / ``AgentType.Chain_of_Thought``
+                / ``AgentType.Zero_Shot`` / ``AgentType.Few_Shot`` /
+                ``AgentType.Instruction_Tuned``), a custom
+                ``AgentFormatter`` instance you built, or a raw
+                prompt-template string containing ``{tools}``,
+                ``{tool_names}``, and ``{user_input}`` placeholders.
+                Aliased as ``agent=`` (lowercase, PEP-8-friendly).
+                Passing both ``Agent=`` and ``agent=`` raises
+                ``TypeError`` -- pick one.
+            tools: Tool instances the LLM can call. Each must be a
+                ``StandardTool`` / ``StructuredTool`` /
+                ``AsyncStandardTool`` / ``AsyncStructuredTool``.
+                Defaults to an empty list. Framework guards apply
+                automatically (duplicate-call, timeout, circuit
+                breaker, cache, observability). Merged with any
+                ``DefaultTools`` produced from ``permissions=`` below;
+                collisions raise ``TypeError``.
+            max_iterations: Cap on tool-calling cycles per invoke.
+                Default 4. Bump for complex multi-step tasks. If the
+                loop reaches the cap without a Final_Answer, the
+                runner synthesizes a summary of what actually
+                happened (last successful tool result + step list)
+                so callers never get a bare "No final answer".
+            auto_cache: When True (default), tool results are cached
+                by ``(name, args)`` signature via
+                ``get_global_cache()``. Second identical dispatch is
+                a cache hit -- observability emits ``CACHE_HIT``.
+                Disable when your tools have side effects
+                (``send_email`` / ``write_file``) or time-varying
+                outputs (``current_time`` / ``stock_price``).
+            auto_memory: When True, the runner instantiates a default
+                ``ConversationMemory`` and threads it as chat history
+                automatically between invokes. Off by default; most
+                real apps prefer explicit ``Session`` + custom
+                ``BaseMemory`` (see the memory strategies guide).
+            use_function_calling: When True, route the AgentType
+                parser through the model's native tool-calling API
+                (``call_with_tools``) instead of parsing JSON out of
+                assistant text. Slightly higher accuracy on tool-call
+                correctness. Requires the model to implement
+                ``call_with_tools`` (GPT and Claude both do). Mutually
+                exclusive with ``bind_tools_natively``.
+            verbose: Print the running Thought / Action / Observation
+                trace to stdout while the loop executes. Convenient
+                during development; usually off in production.
+                Independent of ``observability_enabled`` (which
+                controls structured events, not stdout).
+            bind_tools_natively: When True (3.1), the AgentType parser
+                is bypassed and your tools are bound directly as
+                native function-calling tools. The framework
+                auto-registers a synthetic ``respond`` tool the model
+                calls to end the loop. Multiple ``tool_use`` blocks
+                per turn are dispatched concurrently on a bounded
+                ``ThreadPoolExecutor``. Best latency for multi-tool
+                turns. Mutually exclusive with
+                ``use_function_calling``. Uses a minimal system
+                prompt (not the AgentType template) so the parser
+                scaffolding doesn't fight the native interface.
+            parallel_tool_workers: Max concurrent dispatches per turn
+                when ``bind_tools_natively=True``. Default 8. Actual
+                worker count is ``min(this, number_of_tool_calls)``.
+                Ignored when native binding is off. Only affects
+                per-turn parallelism -- separate calls to
+                ``runner.invoke`` remain sequential.
+            agent: Lowercase PEP-8 alias for ``Agent``. Prefer this
+                spelling in new code.
+            permissions: A ``Permissions`` instance. When supplied,
+                the framework calls ``DefaultTools.build(permissions)``
+                and merges the resulting tools into ``tools=``. This
+                is how you enable the sandboxed filesystem tools
+                (``read_path`` / ``write_file`` / ``run_python``
+                etc.) -- denied capabilities aren't registered, so
+                the LLM literally cannot call them. Also injects a
+                filesystem-sandbox description into the system
+                prompt automatically. Name collisions with
+                ``tools=`` raise ``TypeError`` at construction.
+            include_denied_tools: When True, denied capabilities
+                surface as no-op tools that return an error message
+                ("this capability is disabled"). Useful for testing
+                model behavior against a wider tool surface. Default
+                False -- denied tools don't exist to the model.
+            system_addendum: A role-specific instruction block
+                appended to the AgentType template's system prompt.
+                Use to encode a specialist contract
+                (e.g. "you MUST call ``write_file`` at the end;
+                never just describe the content"). When
+                ``permissions=`` is also set, the auto-generated
+                sandbox hint is prepended so the role text can
+                reference paths. Set this to a lightweight cache
+                miss beat -- Anthropic prompt caching kicks in when
+                the addendum stays stable across calls.
+            strict_tool_dispatch: When True, an unknown ``action``
+                that looks like a tool identifier feeds an error
+                observation back into the loop
+                ("that tool doesn't exist; use one of X or
+                Final_Answer") so the model can retry. Default
+                False, which routes unknown actions to
+                implicit-final. Turn on for models prone to
+                misnaming tools (gpt-4o-mini).
+
+        Raises:
+            TypeError: If both ``Agent`` and ``agent`` are passed, if
+                ``Agent``/``agent`` is missing, if any item in
+                ``tools`` is not a supported tool subclass, or if
+                ``permissions`` isn't a ``Permissions`` instance.
+            ValueError: If ``use_function_calling`` and
+                ``bind_tools_natively`` are both True (mutually
+                exclusive modes).
+        """
         # PEP 8 alias: prefer lowercase `agent=`. Either argument works; passing
         # both raises so misuse is loud rather than silently ambiguous.
         if Agent is not None and agent is not None:
@@ -1173,23 +1310,7 @@ class AgentRunner:
                 )
             tools = list(default_tools) + list(tools)
             auto_sandbox_hint = _build_sandbox_hint(permissions)
-        """
-        Initializes the AgentRunner.
-
-        Args:
-            model (BaseChatModel): The LLM model.
-            Agent: The agent's prompt template (string, AgentFormattor, or AgentPrompt).
-            tools (List): A list of tool instances available to the agent.
-            max_iterations (Optional[int]): Maximum tool-calling cycles.
-            auto_cache (bool): Enable automatic tool result caching (default: True).
-            auto_memory (bool): Enable automatic memory management (default: False).
-            use_function_calling (bool): Route the AgentType parser through the
-                model's native tool-calling API. Requires the chat model to
-                implement ``call_with_tools`` (GPT and Claude do).
 
-        Raises:
-            TypeError: If any item in ``tools`` is not a StandardTool/StructuredTool.
-        """
         self.Query = ""
         self.Agent = Agent
         self.tools = tools

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/agentx_dev/Runner/AsyncAgentRun.py

@@ -66,9 +66,27 @@ def _read_action_input(parser_instance: BaseModel):
 
 
 class AsyncAgentRunner:
-    """
-    Async version of AgentRunner with support for concurrent tool execution
-    and native function calling.
+    """Async agent runner. Same reason-act loop as :class:`AgentRunner`
+    but every I/O path is awaitable.
+
+    Typical use::
+
+        import asyncio
+        from agentx_dev import AsyncAgentRunner, AgentType, Claude
+
+        runner = AsyncAgentRunner(
+            model=Claude(),
+            agent=AgentType.ReAct,
+            tools=[my_async_tool],
+        )
+        result = asyncio.run(runner.ainvoke("..."))
+
+    Accepts a mix of sync and async tools transparently. When at least
+    one async tool is registered, a ``batch_concurrent`` meta-tool is
+    auto-added so the LLM can dispatch several async calls in one turn
+    via ``asyncio.gather``. Combine with ``bind_tools_natively=True``
+    for the modern "parallel tool calls per turn" pattern where every
+    tool_use block in one assistant response is dispatched concurrently.
     """
 
     def __init__(
@@ -88,6 +106,53 @@ class AsyncAgentRunner:
         include_denied_tools: bool = False,
         strict_tool_dispatch: bool = False,
     ):
+        """Construct an ``AsyncAgentRunner``. Parameters mirror
+        :class:`AgentRunner` -- see that docstring for the full details;
+        the differences are noted here.
+
+        Args:
+            model: A ``BaseChatModel`` subclass. Both providers ship
+                sync + async paths, so ``Claude()`` and ``GPT()``
+                work here without changes.
+            Agent: The prompt template + parser pair. Same accepted
+                shapes as ``AgentRunner`` (``AgentType`` member,
+                custom ``AgentFormatter``, or raw string).
+            tools: Any mix of ``StandardTool`` / ``StructuredTool``
+                (sync) and ``AsyncStandardTool`` /
+                ``AsyncStructuredTool`` (async). Async tools use
+                ``asyncio.wait_for`` for cancellable timeouts; sync
+                tools run on the thread pool. When at least one async
+                tool is present, ``batch_concurrent`` is auto-added
+                so the LLM can batch calls via ``asyncio.gather``.
+            max_iterations: Loop cap per ``ainvoke``. Default 4.
+            auto_cache: Same as ``AgentRunner``: cache tool results
+                by ``(name, args)``. Default True.
+            auto_memory: Same as ``AgentRunner``. Default False.
+            use_function_calling: Route the AgentType parser through
+                native ``async_call_with_tools``. Mutually exclusive
+                with ``bind_tools_natively``.
+            verbose: Print step trace to stdout during ``ainvoke``.
+            bind_tools_natively: Bind user tools directly as native
+                FC tools; skip the AgentType parser. Multiple
+                ``tool_use`` blocks per turn dispatch concurrently
+                via ``asyncio.gather`` (no thread pool needed because
+                async tools are cancellable natively).
+            agent: PEP-8 lowercase alias for ``Agent``.
+            permissions: A ``Permissions`` instance -- auto-registers
+                the sandboxed ``DefaultTools`` and injects the
+                filesystem hint into the system prompt.
+            include_denied_tools: Surface denied capabilities as no-op
+                tools. Default False.
+            strict_tool_dispatch: Feed unknown-tool errors back into
+                the loop so the model can retry with a valid name.
+                Default False.
+
+        Raises:
+            TypeError: On missing / duplicate ``Agent``/``agent`` or
+                on a bad ``permissions`` type.
+            ValueError: On the mutually-exclusive combination of
+                ``use_function_calling`` and ``bind_tools_natively``.
+        """
         if Agent is not None and agent is not None:
             raise TypeError("AsyncAgentRunner received both 'Agent' and 'agent'; pass only one.")
         if agent is not None:

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/agentx_dev/Tools.py

@@ -1,10 +1,26 @@
 """
-A lightweight framework for building LLM-powered agents that can use tools.
-
-This module provides the necessary components to define tools, format them for
-an agent prompt, and execute them within a loop controlled by an AgentRunner.
-It leverages Pydantic for structured data validation and generating schemas
-for function-calling APIs like OpenAI's.
+Tool primitives + one-stop tools namespace for `agentx_dev`.
+
+This module ships two things:
+
+1. The `StandardTool` and `StructuredTool` wrappers that adapt a
+   Python callable into something an LLM can call, with Pydantic-
+   validated arguments for the structured variant.
+2. A curated re-export surface (see the section at the bottom) so
+   users can import any built-in tool from a single namespace:
+
+     from agentx_dev.Tools import (
+         StandardTool, StructuredTool,
+         AsyncStandardTool, AsyncStructuredTool,
+         web_search_tool, web_fetch_tool,
+         vector_search_tool, handoff_tool,
+         DefaultTools, Permissions,
+     )
+
+The tool wrappers are the foundation of the framework's function-
+calling story -- every dispatched call, whether it's a filesystem
+tool, a RAG search, or a user-supplied Slack notifier, flows through
+these two classes.
 """
 
 from typing import Dict, Callable, List, Type
@@ -168,12 +184,13 @@ from typing import List, Dict, Any
 
 
 # ---------------------------------------------------------------------------
-# Convenience re-exports so `agentx_dev.Tools` is a one-stop namespace
+# Convenience re-exports so `agentx_dev.Tools` is a one-stop namespace.
 #
 # Users can now import any tool from this module:
 #
 #     from agentx_dev.Tools import (
 #         StandardTool, StructuredTool,          # wrappers (defined above)
+#         AsyncStandardTool, AsyncStructuredTool,# async wrappers
 #         web_search_tool, web_fetch_tool,       # web
 #         vector_search_tool,                    # RAG
 #         handoff_tool,                          # multi-agent
@@ -182,43 +199,45 @@ from typing import List, Dict, Any
 #
 # The top-level imports (from agentx_dev import ...) still work; this is
 # purely additive so callers who prefer the namespaced form get it too.
-# Lazy-import-inside-getattr keeps import time low and avoids circular
-# imports with modules that already import from Tools.py.
+#
+# Design note: previously this used a PEP 562 __getattr__ for lazy
+# loading. That saved microseconds at import time but broke IDE
+# autocomplete + syntax highlighting -- static analyzers can't see
+# names that only exist inside a __getattr__ fallback. Since
+# `agentx_dev/__init__.py` already eager-loads all these modules at
+# top-level import anyway, the lazy-load was a false economy.
+# Eager imports here just re-export symbols that are already in memory.
 # ---------------------------------------------------------------------------
 
-_TOOL_EXPORTS = {
-    # Web tools
-    "web_search_tool":  ("agentx_dev.WebTools",     "web_search_tool"),
-    "web_fetch_tool":   ("agentx_dev.WebTools",     "web_fetch_tool"),
+# Web
+from agentx_dev.WebTools import web_search_tool, web_fetch_tool
+
+# RAG
+from agentx_dev.Embeddings import vector_search_tool
+
+# Multi-agent handoffs
+from agentx_dev.Handoffs import handoff_tool
+
+# Async tool wrappers (siblings to Standard/Structured)
+from agentx_dev.AsyncTools import AsyncStandardTool, AsyncStructuredTool
+
+# Filesystem / permissions
+from agentx_dev.DefaultTools import DefaultTools, Permissions
+
+
+__all__ = [
+    # Wrappers defined in this module
+    "StandardTool", "StructuredTool",
+    "AsyncStandardTool", "AsyncStructuredTool",
+    # Web
+    "web_search_tool", "web_fetch_tool",
     # RAG
-    "vector_search_tool": ("agentx_dev.Embeddings", "vector_search_tool"),
-    # Multi-agent handoffs
-    "handoff_tool":     ("agentx_dev.Handoffs",     "handoff_tool"),
-    # Async tool wrappers (siblings to Standard/Structured)
-    "AsyncStandardTool":   ("agentx_dev.AsyncTools", "AsyncStandardTool"),
-    "AsyncStructuredTool": ("agentx_dev.AsyncTools", "AsyncStructuredTool"),
-    # Filesystem / permissions
-    "DefaultTools": ("agentx_dev.DefaultTools", "DefaultTools"),
-    "Permissions":  ("agentx_dev.DefaultTools", "Permissions"),
-}
-
-
-def __getattr__(name):
-    """PEP 562 module __getattr__: lazy-load re-exports on first access."""
-    if name in _TOOL_EXPORTS:
-        import importlib
-        mod_name, attr_name = _TOOL_EXPORTS[name]
-        mod = importlib.import_module(mod_name)
-        obj = getattr(mod, attr_name)
-        # Cache on the module so subsequent lookups skip the importlib call.
-        globals()[name] = obj
-        return obj
-    raise AttributeError(f"module 'agentx_dev.Tools' has no attribute {name!r}")
-
-
-def __dir__():
-    """Expose the re-exports to `dir(agentx_dev.Tools)` and IDE autocomplete."""
-    return sorted(list(globals().keys()) + list(_TOOL_EXPORTS.keys()))
+    "vector_search_tool",
+    # Multi-agent
+    "handoff_tool",
+    # Sandbox
+    "DefaultTools", "Permissions",
+]
 
 
 

{agentx_dev-3.1.2 → agentx_dev-3.1.3/agentx_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.1.2
+Version: 3.1.3
 Summary: A production-grade Python framework for building LLM agents. Multi-provider chat, permission-gated tools, RAG (in-mem + Chroma/Qdrant/pgvector), semantic memory, Supervisor + Handoffs multi-agent orchestration with streaming, evals harness, prompt caching, Batch API, prompt-optimizer, MCP integration.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/agentx_dev.egg-info/SOURCES.txt

@@ -1,4 +1,6 @@
 AGENTX.md
+CHANGELOG.md
+CONTRIBUTING.md
 LICENSE
 MANIFEST.in
 README.md

{agentx_dev-3.1.2 → agentx_dev-3.1.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 
 name = "agentx-dev"
-version = "3.1.2"
+version = "3.1.3"
 description = "A production-grade Python framework for building LLM agents. Multi-provider chat, permission-gated tools, RAG (in-mem + Chroma/Qdrant/pgvector), semantic memory, Supervisor + Handoffs multi-agent orchestration with streaming, evals harness, prompt caching, Batch API, prompt-optimizer, MCP integration."
 authors = [{ name = "Bruce-Arhin Shadrach", email = "brucearhin098@gmail.com" }]
 # Best practice: link to the license file