agentbyte 0.26.0__tar.gz → 0.26.2__tar.gz

{agentbyte-0.26.0 → agentbyte-0.26.2}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.26.2] - 2026-09-09
+
+### Fixed
+
+- Fixed `MiddlewareChain.execute_stream()` treating a middleware's `None` return from `process_error()` (meaning "not handled, propagate") as a recovered result, which swallowed the original exception and surfaced a generic "did not yield a final result" error instead.
+
+## [0.26.1] - 2026-09-04
+
+- Ensured release CI explicitly installs the optional GEPA optimization dependency and made its availability test independent of the environment's installed extras.
+- Updated the contracting example's skills provider and added chunking-strategy documentation.
+
 ## [0.26.0] - 2026-09-04
 
 ### Added

{agentbyte-0.26.0 → agentbyte-0.26.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.26.0
+Version: 0.26.2
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -86,7 +86,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.26.0**
+Current release: **0.26.2**
 
 ## Building an Agent
 
@@ -189,6 +189,14 @@ print(execution.state["route_output"])
 
 Steps can also wrap an agent (`AgentStep`), call HTTP endpoints (`HttpStep`), transform data (`TransformStep`), or nest another workflow (`SubWorkflowStep`) — with conditional routing, parallel branches, checkpoint/resume, and human-in-the-loop suspend/resume.
 
+### Choosing Agents or Graph-Based Orchestration
+
+Graph-based orchestration makes routing deterministic: after one defined step completes, the next defined step runs. It does not make an LLM's interpretation, tool selection, or output deterministic. Use a graph or `Workflow` when the business process is known, stable, and requires explicit control over every transition.
+
+Start with an `Agent` when the work requires the system to decide how to solve an open-ended request: researching, interpreting documents, selecting tools, synthesizing results, or handling long-tail exceptions. A single agent can complete many such multi-step tasks without encoding every anticipated reasoning path as graph infrastructure.
+
+Keep deterministic controls at operational boundaries. Validate structured output, apply policy checks and approvals, use idempotent writes, and emit audit records before an agent can produce external side effects. This separates deterministic process control from the model's inherently probabilistic reasoning, while allowing a workflow to be introduced where a stable business process truly needs one.
+
 ## Orchestrator Patterns
 
 Two different ways to combine multiple agents — pick based on who's in control:

{agentbyte-0.26.0 → agentbyte-0.26.2}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.26.0**
+Current release: **0.26.2**
 
 ## Building an Agent
 
@@ -105,6 +105,14 @@ print(execution.state["route_output"])
 
 Steps can also wrap an agent (`AgentStep`), call HTTP endpoints (`HttpStep`), transform data (`TransformStep`), or nest another workflow (`SubWorkflowStep`) — with conditional routing, parallel branches, checkpoint/resume, and human-in-the-loop suspend/resume.
 
+### Choosing Agents or Graph-Based Orchestration
+
+Graph-based orchestration makes routing deterministic: after one defined step completes, the next defined step runs. It does not make an LLM's interpretation, tool selection, or output deterministic. Use a graph or `Workflow` when the business process is known, stable, and requires explicit control over every transition.
+
+Start with an `Agent` when the work requires the system to decide how to solve an open-ended request: researching, interpreting documents, selecting tools, synthesizing results, or handling long-tail exceptions. A single agent can complete many such multi-step tasks without encoding every anticipated reasoning path as graph infrastructure.
+
+Keep deterministic controls at operational boundaries. Validate structured output, apply policy checks and approvals, use idempotent writes, and emit audit records before an agent can produce external side effects. This separates deterministic process control from the model's inherently probabilistic reasoning, while allowing a workflow to be introduced where a stable business process truly needs one.
+
 ## Orchestrator Patterns
 
 Two different ways to combine multiple agents — pick based on who's in control:

{agentbyte-0.26.0 → agentbyte-0.26.2}/pyproject.toml

@@ -210,6 +210,10 @@ all = [
     "youtube-transcript-api>=0.6",
     "gepa>=0.1",
 ]
+experiment = [
+    "tiktoken>=0.9.0",
+    "yake>=0.4.8",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

agentbyte-0.26.2/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.26.2"
+VERSION = __version__

{agentbyte-0.26.0 → agentbyte-0.26.2}/src/agentbyte/middleware/base.py

@@ -391,7 +391,7 @@ class MiddlewareChain:
                         ):
                             if self._is_event_item(item):
                                 yield item
-                            else:
+                            elif item is not None:
                                 yield item
                                 recovered = True
                                 return
@@ -492,7 +492,7 @@ class MiddlewareChain:
                         ):
                             if self._is_event_item(item):
                                 yield item
-                            else:
+                            elif item is not None:
                                 yield item
                                 recovered = True
                                 return

{agentbyte-0.26.0 → agentbyte-0.26.2}/tests/middleware/test_middleware_chain.py

@@ -358,6 +358,59 @@ async def test_middleware_chain_execute_stream_yields_events_and_result() -> Non
     assert items[2] == {"value": "ok", "stream": True}
 
 
+@pytest.mark.asyncio
+async def test_execute_stream_propagates_error_when_request_handler_declines() -> None:
+    """A None-returning process_error during process_request must not be treated as recovery."""
+    chain = MiddlewareChain([FailingRequestMiddleware()])
+
+    async def operation() -> str:
+        return "should-not-run"
+
+    with pytest.raises(RuntimeError, match="request middleware failed"):
+        async for _ in chain.execute_stream(
+            operation="model_call",
+            agent_name="assistant",
+            agent_context=AgentContext(),
+            data={"payload": "x"},
+            func=operation,
+        ):
+            pass
+
+
+@pytest.mark.asyncio
+async def test_execute_stream_propagates_error_when_response_handler_declines() -> None:
+    """A None-returning process_error during process_response must not be treated as recovery."""
+
+    class FailingResponseMiddleware(BaseMiddleware):
+        async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+            return context
+
+        async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
+            raise RuntimeError("response middleware failed")
+
+        async def process_error(
+            self,
+            context: MiddlewareContext,
+            error: Exception,
+        ) -> Optional[Any]:
+            return None
+
+    chain = MiddlewareChain([FailingResponseMiddleware()])
+
+    async def operation() -> str:
+        return "ok"
+
+    with pytest.raises(RuntimeError, match="response middleware failed"):
+        async for _ in chain.execute_stream(
+            operation="model_call",
+            agent_name="assistant",
+            agent_context=AgentContext(),
+            data={"payload": "x"},
+            func=operation,
+        ):
+            pass
+
+
 @pytest.mark.asyncio
 async def test_approval_middleware_emits_event_for_matching_tool() -> None:
     chain = MiddlewareChain([ApprovalMiddleware(tool_names=["sensitive_tool"])])

{agentbyte-0.26.0 → agentbyte-0.26.2}/tests/optim/test_gepa.py

@@ -24,6 +24,7 @@ from agentbyte.messages import AssistantMessage, Usage
 from agentbyte.optim import GEPA_AVAILABLE, AgentConfig, CostLog, OptimizationSpec, InstructionTunable
 from agentbyte.optim.gepa import (
     AgentbyteGepaAdapter,
+    _gepa,
     _CostTrackingReflectionLM,
     _GepaTraceCallback,
     optimize_with_gepa,
@@ -84,8 +85,8 @@ class ScriptedModelClient(BaseChatCompletionClient):
 
 
 def test_gepa_available_reflects_import_state() -> None:
-    # gepa is genuinely not installed in this dev environment
-    assert GEPA_AVAILABLE is False
+    """The optional dependency may be present in CI but absent locally."""
+    assert GEPA_AVAILABLE is (_gepa is not None)
 
 
 @pytest.mark.asyncio

agentbyte-0.26.2/tests/test_vanilla_chunker.py

@@ -0,0 +1,213 @@
+"""Regression coverage for the standalone chunking example."""
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip('tiktoken')
+pytest.importorskip('yake')
+SOURCE = Path(__file__).parents[1] / 'examples/chunking/vanilla_chunker.py'
+SPEC = importlib.util.spec_from_file_location('vanilla_chunker', SOURCE)
+module = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = module
+SPEC.loader.exec_module(module)
+
+
+@pytest.fixture(autouse=True)
+def offline_encoding(monkeypatch):
+    # Real BPE encoding with a local vocabulary: no tokenizer download in unit tests.
+    ranks = {bytes([i]): i for i in range(256)}
+    for word in (b'Alpha', b'Beta', b'Gamma', b'word'):
+        for end in range(2, len(word) + 1):
+            ranks.setdefault(word[:end], len(ranks))
+    encoding = module.tiktoken.Encoding(
+        name='offline', pat_str=r'\s+|\w+|[^\w\s]+',
+        mergeable_ranks=ranks, special_tokens={},
+    )
+    monkeypatch.setattr(module.tiktoken, 'get_encoding', lambda name: encoding)
+
+
+def chunker(budget=60, overlap=10):
+    return module.VanillaChunker(module.ChunkerConfig(
+        project_id='project', doc_id='doc', max_tokens=budget, token_overlap=overlap,
+        min_tokens=0, document_type='prose',
+    ))
+
+
+def test_unmarked_paragraphs_overlap_and_schema():
+    c = chunker(60, 12)
+    paragraphs = [' '.join([word] * 20) + '.' for word in ('Alpha', 'Beta', 'Gamma')]
+    docs = c.chunk_text('\n\n'.join(paragraphs), 'plain.md')
+    assert len(docs) == 1
+    doc = docs[0]
+    assert len(doc.chunks) == 3
+    for paragraph, chunk in zip(paragraphs, doc.chunks):
+        assert paragraph in chunk.content
+        assert chunk.page_start == chunk.page_end == 1
+        assert chunk.token_count == c._count_tokens(chunk.content) <= 60
+    assert 'Alpha' in doc.chunks[1].content.split('\n\n')[0]
+
+
+def test_long_paragraph_unicode_and_empty_input():
+    c = chunker(30, 5)
+    docs = c.chunk_text('界' * 100, 'unicode.md')
+    assert len(docs) == 1
+    assert len(docs[0].chunks) > 1
+    assert all(chunk.token_count <= 30 for chunk in docs[0].chunks)
+    assert all('\ufffd' not in chunk.content for chunk in docs[0].chunks)
+    assert sum(chunk.content.count('界') for chunk in docs[0].chunks) >= 100
+    assert c.chunk_text('', 'empty.md') == []
+
+
+def test_cross_page_table_headers_and_rows():
+    c = chunker(70, 0)
+    header = '| Item | Value |\n| --- | --- |'
+    rows = [f'| item{i} | value{i} |' for i in range(12)]
+    raw = '<!-- page: {"page": 4} -->\n## Costs\n' + header + '\n'
+    raw += '\n'.join(rows[:6]) + '\n<!-- page: {"page": 5} -->\n'
+    raw += '\n'.join(rows[6:])
+    docs = c.chunk_text(raw, 'table.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert len(chunks) > 2
+    for chunk in chunks:
+        assert header in chunk.content
+        assert chunk.token_count == c._count_tokens(chunk.content) <= 70
+    combined = '\n'.join(chunk.content for chunk in chunks)
+    assert all(combined.count(row) == 1 for row in rows)
+    assert chunks[0].page_start == 4
+    assert chunks[-1].page_end == 5
+
+
+def test_table_context_cleared_by_heading_and_adjacent_prose():
+    c = chunker()
+    blocks = c._parse_section_blocks([(1, '| A |\n| --- |\n| one |\nprose\n| two |\n## New\n| three |')])
+    assert all(not b['table_header'] for b in blocks if 'two' in b['text'] or 'three' in b['text'])
+
+
+def test_oversized_table_row_fails_explicitly():
+    c = chunker(20, 0)
+    with pytest.raises(ValueError, match='one row'):
+        c.chunk_text('| A |\n| --- |\n| ' + 'word ' * 100 + '|', 'table.md')
+
+
+def test_oversized_table_header_fails_explicitly():
+    with pytest.raises(ValueError, match='Table header exceeds'):
+        chunker(20, 0).chunk_text('| ' + 'word ' * 100 + '|\n| --- |', 'table.md')
+
+
+def test_preamble_preserved():
+    docs = chunker().chunk_text('Introduction\n<!-- page: {"page": 3} -->\nBody', 'doc.md')
+    assert len(docs) == 1
+    assert 'Introduction' in docs[0].chunks[0].content
+    assert docs[0].chunks[0].page_start == 3
+
+
+def test_skipped_heading_levels_are_siblings_and_preserved():
+    c = chunker(500, 0)
+    raw = '# Agreement\n#### First\nAlpha\n#### Second\nBeta\n##### Exhibit A\nGamma'
+    docs = c.chunk_text(raw, 'doc.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert [chunk.section_title for chunk in chunks] == ['Agreement', 'First', 'Second', 'Exhibit A']
+    assert chunks[2].heading_path == ['Agreement', 'Second']
+    assert chunks[3].heading_path == ['Agreement', 'Second', 'Exhibit A']
+    assert '#### Second' in chunks[2].content
+    assert all(chunk.token_count == c._count_tokens(chunk.content) for chunk in chunks)
+
+
+def test_signature_artifacts_keep_section_and_content():
+    c = chunker(500, 0)
+    raw = ('# Agreement\n##### Adelphi Values LLC\nby: Docusigned by:\n'
+           '**### | | ...**\nBy: By:\n**# FEDIEBAD219E44F.**\n'
+           'D21C3301ADS44AS.\n##### (Exhibit A) BUDGET AND PAYMENT SCHEDULE\nPayment')
+    docs = c.chunk_text(raw, 'signature.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert len(chunks) == 3
+    signature = chunks[1]
+    assert signature.section_title == 'Adelphi Values LLC'
+    assert signature.heading_path == ['Agreement', 'Adelphi Values LLC']
+    assert '**# FEDIEBAD219E44F.**' in signature.content
+    assert 'D21C3301ADS44AS.' in signature.content
+    assert '**### | | ...**' in signature.content
+    assert chunks[2].heading_path == ['Agreement', '(Exhibit A) BUDGET AND PAYMENT SCHEDULE']
+
+
+def test_identifier_without_signature_context_remains_heading():
+    blocks = chunker()._parse_section_blocks([(1, '# FEDIEBAD219E44F.\nContent')])
+    assert blocks[0]['type'] == 'heading'
+
+
+def test_artifact_does_not_reset_cross_page_table_context():
+    c = chunker(500, 0)
+    blocks = c._parse_section_blocks([
+        (1, '# Signatures\nDocuSigned by:\n| Name |\n| --- |\n| Alice |'),
+        (2, '# FEDIEBAD219E44F.\n| Bob |'),
+        (3, '#### New section\n| Carol |'),
+    ])
+    bob = next(b for b in blocks if b['text'] == '| Bob |')
+    carol = next(b for b in blocks if b['text'] == '| Carol |')
+    assert bob['table_header'] == '| Name |\n| --- |'
+    assert bob['heading_path'] == ['Signatures']
+    assert carol['table_header'] == ''
+    docs = c._build_records(c._accumulate_chunks(blocks), 'doc.md', c._kw)
+    assert len(docs) == 1
+    assert '| Name |\n| --- |\n| Bob |' in docs[0].chunks[0].content
+
+
+def test_configured_heading_depth_uses_actual_level():
+    c = chunker(500, 0)
+    c.cfg.section_split_depth = 2
+    docs = c.chunk_text('# Root\n#### Child\nText', 'doc.md')
+    assert len(docs) == 1
+    assert docs[0].chunks[0].section_title == 'Root'
+    assert '#### Child' in docs[0].chunks[0].content
+
+
+def test_auto_form_labels_pack_but_exhibit_still_splits():
+    c = chunker(500, 0)
+    c.cfg.document_type = 'auto'
+    raw = ('# Form\n##### Name\nAlice\n##### Date\nToday\n'
+           '##### Value\n100\n##### Exhibit A\nTerms')
+    docs = c.chunk_text(raw, 'form.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert len(chunks) == 2
+    assert all(label in chunks[0].content for label in ('Name', 'Date', 'Value'))
+    assert chunks[1].section_title == 'Exhibit A'
+
+
+def test_small_chunks_merge_without_content_loss():
+    c = chunker(500, 0)
+    c.cfg.min_tokens = 100
+    raw = '# Root\n##### Label\nValue\n##### Other\nMore'
+    docs = c.chunk_text(raw, 'form.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert len(chunks) == 1
+    assert all(line in chunks[0].content for line in raw.splitlines())
+    assert chunks[0].heading_path == ['Root']
+    assert chunks[0].token_count == c._count_tokens(chunks[0].content)
+
+
+def test_minimum_does_not_merge_across_pages_or_exceed_maximum():
+    c = chunker(60, 0)
+    c.cfg.min_tokens = 50
+    raw = '<!-- page: {"page":1} -->\n# A\n<!-- page: {"page":2} -->\n# B'
+    docs = c.chunk_text(raw, 'pages.md')
+    assert len(docs) == 1
+    assert len(docs[0].chunks) == 2
+    raw = '# A\n' + 'x' * 40 + '\n# B\n' + 'y' * 40
+    docs = c.chunk_text(raw, 'budget.md')
+    assert len(docs) == 1
+    chunks = docs[0].chunks
+    assert len(chunks) == 2
+    assert all(chunk.token_count <= 60 for chunk in chunks)
+
+
+@pytest.mark.parametrize('budget,overlap', [(0, 0), (10, -1), (10, 10)])
+def test_invalid_config(budget, overlap):
+    with pytest.raises(ValueError):
+        chunker(budget, overlap)

agentbyte-0.26.0/src/agentbyte/__about__.py

@@ -1,2 +0,0 @@
-__version__ = "0.26.0"
-VERSION = __version__