agentx-dev 3.0.5__tar.gz → 3.1.1__tar.gz

{agentx_dev-3.0.5 → agentx_dev-3.1.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.0.5
-Summary: A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets.
+Version: 3.1.1
+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
         
@@ -36,23 +36,36 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: PyYAML>=5.3.1
 Requires-Dist: rich>=10.0
 Provides-Extra: anthropic
-Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Requires-Dist: anthropic>=0.36; extra == "anthropic"
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.1; extra == "mcp"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4; extra == "chroma"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.6; extra == "qdrant"
+Provides-Extra: pgvector
+Requires-Dist: psycopg[binary]>=3.1; extra == "pgvector"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
 Provides-Extra: all
-Requires-Dist: anthropic>=0.20; extra == "all"
+Requires-Dist: anthropic>=0.36; extra == "all"
 Requires-Dist: mcp>=0.1; extra == "all"
 Requires-Dist: opentelemetry-api>=1.20; extra == "all"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "all"
+Requires-Dist: chromadb>=0.4; extra == "all"
+Requires-Dist: qdrant-client>=1.6; extra == "all"
+Requires-Dist: psycopg[binary]>=3.1; extra == "all"
 Dynamic: license-file
 
 # agentx_dev
 
-A small, production-ready Python framework for building LLM agents.
-Think LangChain, minus the sprawl.
+A production-grade Python framework for building LLM agents.
+Nothing sprawls.
 
 This README walks you through real usage — start an agent, add tools,
 connect MCP servers, ship to production. Every code block is something
@@ -60,6 +73,220 @@ you can paste and run.
 
 ---
 
+## What's new in 3.1 — power features
+
+Six force-multipliers land in one release. All additive; existing code
+keeps working.
+
+| Feature | What you get |
+|---|---|
+| **Anthropic prompt caching** | `Claude(enable_prompt_cache=True)` marks the system prompt, tool schemas, and (for long chats) stable history segments with `cache_control: ephemeral`. Repeat calls that share those blocks read them from Anthropic's cache -- typically ~90% cheaper on cached input. `TokenUsage` now surfaces `cache_hit_ratio` so you can verify hits. |
+| **Parallel tool calls per turn (sync)** | `AgentRunner(bind_tools_natively=True)` binds your tools as native FC tools. When the LLM emits multiple `tool_use` blocks in one turn, they dispatch concurrently on a `ThreadPoolExecutor` (`parallel_tool_workers=8` by default). Async runner already had this; sync now matches. |
+| **Semantic long-term memory** | `SemanticMemory(embeddings=...)` embeds every message and retrieves the top-K most relevant older turns for the current query -- keeps recent tail verbatim, injects retrieved older context as a synthetic system message. Beats sliding-window on multi-topic conversations. |
+| **`vector_search` RAG tool** | `vector_search_tool(store)` gives your agent a native RAG tool. Backed by `VectorStore` -- in-memory cosine (numpy-accelerated when available), save/load to JSON. `HashEmbeddings` runs offline for dev + tests; `OpenAIEmbeddings` for production. |
+| **Agent-to-agent handoffs** | `handoff_tool("researcher")` + `HandoffCoordinator({...}, entry="triage")` let one agent transfer control to a peer mid-run (Swarm-style). Bounded by `max_hops`; conversation history propagates so the target agent starts fully informed. |
+| **Evals harness** | `EvalCase` + `EvalRunner` run declarative test cases against any runner, collect per-case latency + tokens + tool-error counts, and produce a pass/fail report. `contains`, `called_tool`, `matches_regex`, `llm_judge`, and more assertion helpers included. CLI: `python -m agentx_dev.Evals run tests/evals/ --config agent.yaml`. |
+
+### 3.1 API reference — everything new at a glance
+
+Grouped by module. All symbols below are exported at the package top level
+(`from agentx_dev import X`) unless marked `agentx_dev.X.Y`.
+
+**1. Prompt caching (`agentx_dev.ChatModel`)**
+
+New parameters on `Claude.__init__`:
+
+| Param | Type | Default | What it does |
+|---|---|---|---|
+| `enable_prompt_cache` | `bool` | `False` | Turn on Anthropic prompt caching. System prompt + tool schemas get `cache_control: ephemeral`. Second call reads them from cache. |
+| `cache_history_after` | `int` | `4` | When history has more than N turns, add a third cache breakpoint on the last stable assistant message so long chats also benefit. Max 3 breakpoints used (Anthropic allows 4). |
+
+New `TokenUsage` attributes + property:
+
+| Attribute | What it tracks |
+|---|---|
+| `total_cache_read_tokens` | Cumulative tokens served from cache (discounted rate). |
+| `total_cache_creation_tokens` | Cumulative tokens written into cache (small premium). |
+| `last_cache_read_tokens` | Cache read tokens from the most recent call. |
+| `last_cache_creation_tokens` | Cache creation tokens from the most recent call. |
+| `cache_hit_ratio` *(property)* | `total_cache_read_tokens / total_input_tokens`. Zero when no cache. |
+
+`TokenUsage.record()` gained two keyword args: `cache_read_tokens`, `cache_creation_tokens` (default `0` — providers that don't cache don't need to pass them).
+
+**2. Parallel per-turn tool dispatch (`agentx_dev.Runner.AgentRun`)**
+
+New parameters on `AgentRunner.__init__`:
+
+| Param | Type | Default | What it does |
+|---|---|---|---|
+| `bind_tools_natively` | `bool` | `False` | Skip the AgentType parser indirection; bind your tools directly as native FC tools so the LLM can call them (and multiple at once per turn). Mutually exclusive with `use_function_calling`. Mirrors the async runner's mode of the same name. |
+| `parallel_tool_workers` | `int` | `8` | Max threads in the pool that runs concurrent tool calls when native binding is on. Bounded by `min(workers, num_calls)` per turn. |
+
+Auto-registered when `bind_tools_natively=True`: a synthetic `respond` tool the LLM calls to end the loop with its final answer.
+
+**3. Embeddings + vector store + RAG (`agentx_dev.Embeddings`)**
+
+New module. Exports:
+
+| Symbol | Kind | What it is |
+|---|---|---|
+| `Embeddings` | ABC | Base class. `embed(texts) -> list[list[float]]`, `embed_one(text)`, `dim: int`. |
+| `OpenAIEmbeddings(model="text-embedding-3-small", api_key=None, base_url=None, batch_size=100)` | class | OpenAI-backed. Auto-batches up to 100 texts per request. |
+| `HashEmbeddings(dim=256)` | class | Zero-dep fallback. Deterministic char-trigram hash. For tests + dev. |
+| `VectorHit(id, text, score, metadata)` | dataclass | One search result. `score` is cosine similarity in `[-1, 1]`. |
+| `VectorStore(embeddings)` | class | In-memory store. Methods: `add(texts, ids=None, metadata=None) -> ids`, `search(query, top_k=5, min_score=0.0) -> [VectorHit]`, `delete(ids) -> count`, `clear()`, `save(path)`, `VectorStore.load(path, embeddings=...)`, `len(store)`. numpy-accelerated when available. |
+| `SemanticMemory(embeddings, recent_tail=6, top_k=4, min_score=0.15, preserve_system=True)` | class | `BaseMemory` implementation. Every message goes into a `VectorStore`; `get_messages()` returns system + retrieved-context + recent-tail. Call `set_query(text)` before each turn to focus retrieval. Access underlying store via `.store`. |
+| `vector_search_tool(store, name="vector_search", default_top_k=5, max_top_k=20, description=None)` | factory | Returns a `StructuredTool` the agent can call. Args schema: `{query, top_k, min_score}`. |
+
+`create_semantic_memory(embeddings=None, recent_tail=6, top_k=4)` — factory in `agentx_dev.Memory`. When `embeddings=None`, defaults to `HashEmbeddings(256)` so tests work with no keys.
+
+**4. Agent-to-agent handoffs (`agentx_dev.Handoffs`)**
+
+New module. Exports:
+
+| Symbol | Kind | What it is |
+|---|---|---|
+| `HandoffRequest(target, task="", context={})` | dataclass | Sentinel returned by a handoff tool. String form: `"HANDOFF -> <target>: <task>"` — coordinator detects this in `ToolCall.result`. |
+| `handoff_tool(target, description=None, tool_name=None)` | factory | Returns a `StructuredTool` named `handoff_to_<target>`. Args schema: `{task, rationale}`. |
+| `HandoffCoordinator(agents: dict, entry: str, max_hops=8)` | class | Runs the routing loop. `.run(query, chat_history=None) -> HandoffResult`, `.arun(...)` (async). Chat history propagates across hops. |
+| `HandoffResult(completion, hops)` | dataclass | Wraps the final `AgentCompletion` + ordered list of routing hops (`[{from, to, task, hop}, ...]`). Convenience props: `.content`, `.tool_calls`. |
+| `MAX_HANDOFF_HOPS = 8` | constant | Default hop cap. |
+
+**5. Evals harness (`agentx_dev.Evals`)**
+
+New module. Exports:
+
+| Symbol | Kind | What it is |
+|---|---|---|
+| `EvalCase(name, input, assertions=[], tags=[], metadata={})` | dataclass | One test case. |
+| `EvalResult(case, completion, passed, duration_sec, ...)` | dataclass | Outcome of one case. Also tracks `input_tokens`, `output_tokens`, `cache_read_tokens`, `tool_error_count`. |
+| `EvalReport(results)` | dataclass | Aggregate. Props: `passed`, `failed`, `total`, `pass_rate`, `total_duration_sec`, `total_input_tokens`, `total_output_tokens`, `total_cache_read_tokens`. Methods: `.summary() -> str`, `.to_dict()` for CI. |
+| `EvalRunner(runner_factory, verbose=True)` | class | `.run(cases) -> EvalReport`. Builds a FRESH runner per case via `runner_factory` so state doesn't leak. |
+
+Assertion helpers (all return an `(AgentCompletion) -> (passed, message)` callable):
+
+| Helper | Signature | Checks |
+|---|---|---|
+| `contains(needle, case_sensitive=False)` | | Final answer contains substring. |
+| `not_contains(needle, case_sensitive=False)` | | Final answer does NOT contain substring. |
+| `matches_regex(pattern, flags=re.IGNORECASE)` | | Final answer matches `re.search`. |
+| `called_tool(name)` | | Tool with that name was called at least once. |
+| `tool_count(*, min=0, max=None)` | | Total tool calls within bounds. |
+| `max_iterations(limit)` | | Steps taken `<= limit`. |
+| `llm_judge(judge_model, criterion)` | | Uses another chat model to grade yes/no. |
+
+`AssertionFn` type alias exported for typing custom assertions.
+
+Case loaders (declarative JSON files):
+
+| Function | What it loads |
+|---|---|
+| `load_case_from_dict(data: dict) -> EvalCase` | Recognizes `expected_substrings`, `forbidden_substrings`, `matches_regex`, `must_call_tools`, `max_iterations`. |
+| `load_cases_from_dir(path, pattern="*.eval.json") -> list[EvalCase]` | Walks a directory. Each file is one case dict, a list of dicts, or `{"cases": [...]}`. |
+
+CLI:
+
+```bash
+python -m agentx_dev.Evals run tests/evals/ --config agent.yaml [--pattern '*.eval.json'] [--json-out report.json]
+```
+
+Exits `0` on all-pass, `1` on any failure. Prints `EvalReport.summary()` to stdout.
+
+**6. Package exports (`agentx_dev`)**
+
+Everything above is re-exported at the top level. New entries in `__all__`:
+
+```
+create_semantic_memory,
+Embeddings, OpenAIEmbeddings, HashEmbeddings,
+VectorStore, VectorHit, SemanticMemory, vector_search_tool,
+HandoffRequest, HandoffResult, HandoffCoordinator, handoff_tool,
+EvalCase, EvalResult, EvalReport, EvalRunner,
+contains, not_contains, matches_regex,
+called_tool, tool_count, max_iterations, llm_judge,
+load_case_from_dict, load_cases_from_dir,
+```
+
+**7. Runnable demo**
+
+`examples/v3_1_features_demo.py` walks every 3.1 feature. Runs offline via
+`HashEmbeddings` + mock runners for the RAG / memory / handoffs / evals
+sections. Live sections (prompt caching, parallel tools) fall back to GPT
+when only `OPENAI_API_KEY` is set; use Claude when `ANTHROPIC_API_KEY` is
+set (prompt caching stays Anthropic-only).
+
+---
+
+Quick tour:
+
+```python
+from agentx_dev import (
+    Claude, AgentRunner, AgentType, Permissions,
+    VectorStore, HashEmbeddings, vector_search_tool,
+    SemanticMemory, HandoffCoordinator, handoff_tool,
+    EvalCase, EvalRunner, contains, called_tool,
+)
+
+# Prompt caching -- opt in on the model.
+llm = Claude(model="claude-sonnet-4-6", enable_prompt_cache=True)
+
+# RAG -- build a private store and hand the search tool to the agent.
+store = VectorStore(embeddings=HashEmbeddings())
+store.add(["Postgres uses MVCC for isolation.",
+           "SQLite stores the whole DB in one file."])
+runner = AgentRunner(
+    model=llm, agent=AgentType.ReAct,
+    tools=[vector_search_tool(store)],
+    permissions=Permissions.read_only(["./"]),
+)
+result = runner.invoke("How does Postgres handle concurrent writes?")
+
+# Parallel tool calls -- native binding + multi-worker dispatch.
+fast = AgentRunner(
+    model=llm, agent=AgentType.ReAct,
+    tools=[weather_tool, stock_tool, news_tool],
+    bind_tools_natively=True, parallel_tool_workers=4,
+)
+
+# Handoffs -- specialists that can hand back and forth.
+coord = HandoffCoordinator({
+    "triage": triage_runner,
+    "researcher": researcher_runner,
+    "writer": writer_runner,
+}, entry="triage")
+answer = coord.run("Write a 200-word summary of MVCC.")
+
+# Evals -- catch regressions before shipping.
+cases = [
+    EvalCase("capital", "What's the capital of France?",
+             assertions=[contains("Paris")]),
+    EvalCase("math", "137 * 91?",
+             assertions=[called_tool("calculator"), contains("12467")]),
+]
+report = EvalRunner(lambda: build_runner()).run(cases)
+print(report.summary())
+```
+
+---
+
+## What's new in 3.0.6 — security hardening release
+
+All seven findings from the third-party framework audit are now fixed.
+Every change is backwards-compatible: existing code keeps working; the
+new defaults are strictly safer.
+
+| Fix | What changed |
+|---|---|
+| **SSRF guard on `web_fetch`** | Rejects non-public destinations (loopback, RFC1918, 169.254.169.254 cloud-metadata, link-local, multicast) *and* re-validates every redirect hop. `WebTools.py` |
+| **`SpawnConfig.auto_spawn_allowed_caps`** | New allow-list gates which capabilities `auto_spawn=True` will silently grant. Prompt-injected tasks can no longer talk the planner into a `["code"]` or `["delete"]` spawn. Recommended: `{"web"}`. |
+| **Scrubbed subprocess env** | `run_python` / `run_shell` no longer inherit the full parent env. `print(os.environ)` inside `execute_python` cannot exfiltrate `OPENAI_API_KEY`, `AWS_*`, etc. Opt vars back in with `Permissions(subprocess_env_passthrough=[...])`; use `["*"]` for the pre-3.0.6 behaviour. |
+| **HMAC-signed persistent state** | Each `run_python` build generates a per-run HMAC key, kept in parent memory. A tampered or attacker-dropped `.run_python_state.pkl` fails verification and the header starts fresh instead of unpickling attacker `__reduce__` payloads. |
+| **`session_id` sanitizer** | `mint_session_dir` / `Permissions.new_session` now reject path separators, `..`, control chars, leading dots. `session_id="../../../tmp/pwn"` no longer escapes `base`. |
+| **`permissions.json` mode 0o600** | Config file is now written via `os.open(..., 0o600)`, blocking multi-user hijack where another local user pre-creates the config with `execute_python=True`. |
+| **ReDoS guard on `grep`** | 500-char pattern cap + 10s total-scan wall-clock budget. A catastrophic-backtracking regex from an untrusted planner can no longer freeze the agent. |
+| **`invoke` / `ainvoke` accept a bare string** | `BaseChatModel.invoke("hi")` now wraps to `[{"role":"user","content":"hi"}]` — same behaviour `with_structured_output(...).invoke("hi")` has always had. Silently forwarding a string to the provider used to produce an OpenAI `Invalid type for 'messages'` 400 that read like a caller-payload problem. Lists and `{"messages": [...]}` dicts pass through unchanged. Fully additive. |
+| **`AgentRunner.invoke` / `AsyncAgentRunner.ainvoke` accept a message list** | Parallel fix for the runner. Callers thinking in chat-model shapes can now pass `runner.invoke([{"role":"user","content":"prior"}, {"role":"assistant","content":"ok"}, {"role":"user","content":"NOW"}])` — the last user turn becomes the query and earlier non-system turns become the chat history (merged with any explicit `chat_history=`). Bare strings still work (classic path). `system` messages in the list are dropped because the runner assembles its own from the AgentType template + `system_addendum` + sandbox hint. `stream` / `astream` accept the same shapes. |
+
 ## What's new in 3.0
 
 - **Multi-agent orchestration** — `Supervisor` decomposes a task into