agentbyte 0.22.0__tar.gz → 0.22.2__tar.gz

{agentbyte-0.22.0 → agentbyte-0.22.2}/.gitignore

@@ -7,8 +7,15 @@ wheels/
 *.egg-info
 
 # Virtual environments
-.venv
+.venv/
+venv/
+env/
+
+# Local environment files
 .env
+.env.*
+!.env.example
+!.env.*.example
 
 # IDE
 .vscode/
@@ -49,3 +56,7 @@ artifacts/
 
 # Machine-local agent config (each machine maintains its own)
 AGENTS.LOCAL.md
+data/datasets/
+
+# lean-ctx context runtime cache
+.lean-ctx/

{agentbyte-0.22.0 → agentbyte-0.22.2}/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.22.2] - 2026-07-05
+
+### Added
+
+- Added `AgentResponse.final_message` and `AgentResponse.structured_output` convenience accessors for consuming final assistant output without manually indexing `response.messages[-1]`.
+- Added the FastAPI agent API frontend integration updates, including the API-loaded agent landing page, contracting workspace routing, feedback UI flow, tool-step rendering, and context inspector refinements.
+
+### Changed
+
+- Updated the FastAPI agent API example to consume structured output through the new `AgentResponse.structured_output` accessor.
+- Updated the FastAPI study docs and UI developer guide to match the integrated API, session history, feedback, citation, and frontend behavior.
+
+## [0.22.1] - 2026-06-30
+
+### Added
+
+- Added `StreamEventLogger.log(event)` — a single dispatcher that routes any stream event to the correct log level, replacing the need for callers to invoke all five level methods per event.
+
+### Changed
+
+- `StepProgressEvent` is now logged at `INFO` (moved from `DEBUG`) so that step progress messages emitted via `context.emit_progress()` appear in standard Lambda/application logs without enabling debug output.
+
+## [0.22.0] - 2026-05-30
+
+### Added
+
+- Added async-first `SQLiteDataset` rewrite: `connect()` is now async, `__aenter__`/`__aexit__` context manager support added via `aiosqlite`.
+- Added `DatasetImportConfig` and `create_dataset()` importer that converts `list[dict]`, CSV file, and raw CSV string into dataset artifacts on disk.
+- Added `LocalDatasetWriteConfig` and `S3DatasetWriteConfig` as the write-side mirror of the existing source config pattern (`write_config.py`, `writers.py`).
+- Added spec `0020-dataset-importer` registered in `docs/specs/README.md`.
+- Added `hr-analyst` multifile skill demonstrating selective resource loading: agent loads only the schema file relevant to each question rather than injecting the full schema set into every prompt.
+- Added notebook `12.2-agent-skills-multifile-skill` for the HR-analyst pattern.
+- Added notebook `14.1-dataset-importer` covering 10 importer use cases (single/multi-table, all source types, overwrite protection, schema inspection, Pandas DataFrame path).
+- Added `agentbyte-runtime-skills` agent skill (`SKILL.md`) for skill authoring guidance.
+- Added study doc `03_topic_skills_provider.md` under `docs/study/08-skills_topics/`.
+
+### Changed
+
+- Reorganised usecase notebooks from flat numbered files into topic subfolders mirroring `notebooks/concepts/`: `agents/`, `configuration/`, `workflows/`, `tools/`, `skills/`, `eval/`, `dataset/`, `rag/`; numbers reset to `01` within each group.
+- Updated `docs/study` dataset topics and concept notebooks (`01-dataset-module-examples`, `02-loading-asmd-esmd-datasets`) for the async API.
+- Removed old `skill-authoring/SKILL.md`; replaced by `agentbyte-runtime-skills/SKILL.md`.
+
+---
+
 ## [0.21.0] - 2026-05-22
 
 ### Added

{agentbyte-0.22.0 → agentbyte-0.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.22.0
+Version: 0.22.2
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -30,6 +30,8 @@ Provides-Extra: azureopenai
 Requires-Dist: azure-identity>=1.25.1; extra == 'azureopenai'
 Requires-Dist: openai>=1.107.1; extra == 'azureopenai'
 Provides-Extra: coding
+Provides-Extra: dataset
+Requires-Dist: aiosqlite>=0.22.1; extra == 'dataset'
 Provides-Extra: dev
 Requires-Dist: ipykernel>=7.1.0; extra == 'dev'
 Requires-Dist: nbclient>=0.10.4; extra == 'dev'
@@ -76,7 +78,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.21.0**
+Current release: **0.22.2**
 
 ## Current Capabilities
 

{agentbyte-0.22.0 → agentbyte-0.22.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.21.0**
+Current release: **0.22.2**
 
 ## Current Capabilities
 

{agentbyte-0.22.0 → agentbyte-0.22.2}/pyproject.toml

@@ -38,6 +38,9 @@ webui = [
     "fastapi>=0.135.2",
     "uvicorn[standard]>=0.44.0",
 ]
+dataset = [
+    "aiosqlite>=0.22.1",
+]
 sql = [
     "sqlmodel>=0.0.38",
     "asyncpg>=0.31.0",
@@ -139,6 +142,9 @@ otel = [
     "opentelemetry-exporter-otlp-proto-http>=1.39.1",
     "opentelemetry-sdk>=1.39.1",
 ]
+dataset = [
+    "aiosqlite>=0.22.1",
+]
 sql = [
     "sqlmodel>=0.0.38",
     "asyncpg>=0.31.0",
@@ -175,6 +181,7 @@ all = [
     "openai>=1.107.1",
     "azure-identity>=1.25.1",
     "aioboto3>=15.5.0",
+    "aiosqlite>=0.22.1",
     "opentelemetry-api>=1.39.1",
     "opentelemetry-exporter-otlp-proto-http>=1.39.1",
     "opentelemetry-sdk>=1.39.1",

agentbyte-0.22.2/src/agentbyte/__about__.py

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

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/agents/types.py

@@ -8,7 +8,7 @@ from typing import Any, Dict, List, Literal, Optional, Sequence, Union
 from pydantic import BaseModel, ConfigDict, Field
 
 from agentbyte.context import AgentContext, ToolApprovalRequest
-from agentbyte.messages import Message, Usage
+from agentbyte.messages import AssistantMessage, Message, Usage
 from agentbyte.types import ToolResult
 
 
@@ -213,6 +213,24 @@ class AgentResponse(BaseModel):
             return ""
         return self.context.messages[-1].content
 
+    @property
+    def final_message(self) -> AssistantMessage | None:
+        """Final assistant message if the run ended with one."""
+        if not self.context.messages:
+            return None
+        message = self.context.messages[-1]
+        if isinstance(message, AssistantMessage):
+            return message
+        return None
+
+    @property
+    def structured_output(self) -> BaseModel | None:
+        """Structured output attached to the final assistant message, if any."""
+        final_message = self.final_message
+        if final_message is None:
+            return None
+        return final_message.structured_content
+
     def __str__(self) -> str:
         """Returns a user-friendly string representation with messages and usage."""
         # Concat all message str representations

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/dataset/__init__.py

@@ -113,6 +113,7 @@ from agentbyte.dataset.sqlite import (
     SqliteColumn,
     SqliteSchema,
 )
+from agentbyte.dataset.sqlite_db import SQLiteDbDataset
 
 __all__ = [
     # Source configuration
@@ -134,6 +135,7 @@ __all__ = [
     "BaseDataset",
     # Implementations
     "SQLiteDataset",
+    "SQLiteDbDataset",
     "JSONDataset",
     "DatasetPublisher",
     "S3DatasetPublisher",

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/dataset/base.py

@@ -87,11 +87,15 @@ class DatasetConfig(BaseModel):
     engine: str = Field(default="sqlite", description="Database engine")
     table_name: str = Field(default="", description="Table name for single-table datasets")
     tables: list[TableDef] = Field(default_factory=list, description="Table definitions for multi-table datasets")
+    table_names: list[str] = Field(default_factory=list, description="Table names for sqlite_db engine")
     in_memory: bool = Field(default=True, description="Use in-memory storage")
     description: str = Field(default="", description="Dataset description")
 
     @model_validator(mode="after")
     def _validate_table_mode(self) -> "DatasetConfig":
+        # sqlite_db uses table_names instead of table_name/tables
+        if self.engine == "sqlite_db":
+            return self
         has_single = bool(self.table_name)
         has_multi = bool(self.tables)
         if has_single and has_multi:

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/dataset/importer.py

@@ -286,6 +286,69 @@ def _assemble_all_files(
     return files
 
 
+# ---------------------------------------------------------------------------
+# sqlite_db binary file assembly — pure sqlite3 + thread, no aiosqlite
+# ---------------------------------------------------------------------------
+
+
+def _build_db_files(
+    config: "DatasetImportConfig",
+    sources: list[DataSource],
+) -> dict[str, bytes]:
+    """Build config.json + dataset.db bytes for the sqlite_db engine.
+
+    Runs in a thread (called via asyncio.to_thread). Uses only stdlib sqlite3
+    and sqlite3.Connection.backup() which is available since Python 3.7.
+    """
+    import os
+    import sqlite3
+    import tempfile
+    from pathlib import Path as _Path
+
+    table_names: list[str] = []
+    mem = sqlite3.connect(":memory:")
+    try:
+        for source in sources:
+            records = source.load()
+            schema = _infer_schema(records)
+            serialized = _serialize_for_sqlite(records, schema)
+            mem.execute(_build_create_table_sql(source.name, schema))
+            if serialized:
+                col_names = [col["name"] for col in schema]
+                placeholders = ", ".join(["?"] * len(col_names))
+                insert_sql = (
+                    f"INSERT INTO {source.name} ({', '.join(col_names)}) "
+                    f"VALUES ({placeholders})"
+                )
+                mem.executemany(
+                    insert_sql,
+                    [tuple(r.get(c) for c in col_names) for r in serialized],
+                )
+            table_names.append(source.name)
+        mem.commit()
+
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            tmp = f.name
+        try:
+            with sqlite3.connect(tmp) as dst:
+                mem.backup(dst)
+            db_bytes = _Path(tmp).read_bytes()
+        finally:
+            os.unlink(tmp)
+    finally:
+        mem.close()
+
+    cfg_dict = {
+        "engine": "sqlite_db",
+        "table_names": table_names,
+        "description": config.description,
+    }
+    return {
+        "config.json": json.dumps(cfg_dict, indent=2).encode(),
+        "dataset.db": db_bytes,
+    }
+
+
 # ---------------------------------------------------------------------------
 # aiosqlite validation — runs before writing any files
 # ---------------------------------------------------------------------------
@@ -361,10 +424,13 @@ class DatasetImporter:
                 "Set overwrite=True to replace it."
             )
 
-        if self._config.engine == "sqlite":
-            await _validate_with_aiosqlite(self._config, sources)
+        if self._config.engine == "sqlite_db":
+            files = await asyncio.to_thread(_build_db_files, self._config, sources)
+        else:
+            if self._config.engine == "sqlite":
+                await _validate_with_aiosqlite(self._config, sources)
+            files = await asyncio.to_thread(_assemble_all_files, self._config, sources)
 
-        files = await asyncio.to_thread(_assemble_all_files, self._config, sources)
         return await asyncio.to_thread(writer.write_files, self._config.dataset_id, files)
 
 

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/dataset/loader.py

@@ -5,6 +5,7 @@ from agentbyte.dataset.config import DatasetSourceConfig
 from agentbyte.dataset.json import JSONDataset
 from agentbyte.dataset.sources import DatasetFiles
 from agentbyte.dataset.sqlite import SQLiteDataset
+from agentbyte.dataset.sqlite_db import SQLiteDbDataset
 
 # Engine registry: maps engine name → BaseDataset subclass.
 # Third-party engines can register themselves via register_engine().
@@ -35,6 +36,7 @@ def register_engine(name: str, cls: type[BaseDataset]) -> None:
 # Pre-register built-in engines
 register_engine("sqlite", SQLiteDataset)
 register_engine("json", JSONDataset)
+register_engine("sqlite_db", SQLiteDbDataset)
 
 
 async def load_dataset(dataset_id: str, config: DatasetSourceConfig) -> BaseDataset:
@@ -94,6 +96,14 @@ def _build_dataset(dataset_id: str, dataset_files: DatasetFiles) -> BaseDataset:
             f"Registered engines: {registered}. "
             f"Use register_engine() to add a new engine."
         )
+    if config.engine == "sqlite_db":
+        return cls(
+            dataset_id=dataset_id,
+            config=config,
+            source_uri=dataset_files.source_uri,
+            db_path=dataset_files.db_path,
+            db_bytes=dataset_files.db_bytes,
+        )
     return cls(
         dataset_id=dataset_id,
         config=config,

{agentbyte-0.22.0 → agentbyte-0.22.2}/src/agentbyte/dataset/sources.py

@@ -46,6 +46,7 @@ class DatasetFiles:
 
     For single-table datasets: ``data_text`` and ``schema_text`` are populated.
     For multi-table datasets: ``table_files`` is populated; ``data_text`` is empty.
+    For sqlite_db datasets: ``db_path`` (local) or ``db_bytes`` (S3) is populated.
     """
 
     dataset_id: str
@@ -54,6 +55,8 @@ class DatasetFiles:
     data_text: str = ""
     schema_text: str | None = None
     table_files: list[TableFiles] = field(default_factory=list)
+    db_path: "Path | None" = None
+    db_bytes: bytes | None = None
 
 
 def validate_dataset_id(dataset_id: str) -> None:
@@ -99,6 +102,17 @@ class LocalDatasetSource(DatasetSource):
         config_text = self._read_required_text(config_path, "Config file not found")
         config = DatasetConfig(**json.loads(config_text))
 
+        if config.engine == "sqlite_db":
+            db_path = dataset_dir / "dataset.db"
+            if not db_path.exists():
+                raise FileNotFoundError(f"dataset.db not found: {db_path}")
+            return DatasetFiles(
+                dataset_id=dataset_id,
+                config=config,
+                source_uri=str(dataset_dir),
+                db_path=db_path,
+            )
+
         if config.is_multi_table:
             table_files = []
             for td in config.tables:
@@ -167,6 +181,16 @@ class S3DatasetSource(DatasetSource):
 
         source_uri = f"s3://{self.config.s3_bucket}/{self._dataset_prefix(dataset_id)}"
 
+        if config.engine == "sqlite_db":
+            db_key = self._build_key(dataset_id, "dataset.db")
+            db_bytes = self._read_required_bytes(db_key)
+            return DatasetFiles(
+                dataset_id=dataset_id,
+                config=config,
+                source_uri=source_uri,
+                db_bytes=db_bytes,
+            )
+
         if config.is_multi_table:
             table_files = []
             for td in config.tables:
@@ -209,6 +233,12 @@ class S3DatasetSource(DatasetSource):
         except FileNotFoundError as exc:
             raise FileNotFoundError(f"Dataset object not found: s3://{self.config.s3_bucket}/{key}") from exc
 
+    def _read_required_bytes(self, key: str) -> bytes:
+        try:
+            return self._read_raw_bytes(key)
+        except FileNotFoundError as exc:
+            raise FileNotFoundError(f"Dataset object not found: s3://{self.config.s3_bucket}/{key}") from exc
+
     def _read_optional_text(self, key: str) -> str | None:
         try:
             return self._read_text(key)
@@ -216,6 +246,10 @@ class S3DatasetSource(DatasetSource):
             return None
 
     def _read_text(self, key: str) -> str:
+        body = self._read_raw_bytes(key)
+        return body.decode("utf-8")
+
+    def _read_raw_bytes(self, key: str) -> bytes:
         client = self._get_client()
         try:
             response = client.get_object(Bucket=self.config.s3_bucket, Key=key)
@@ -223,11 +257,8 @@ class S3DatasetSource(DatasetSource):
             if self._is_not_found_error(exc):
                 raise FileNotFoundError(f"s3://{self.config.s3_bucket}/{key}") from exc
             raise
-
         body = response["Body"].read()
-        if isinstance(body, bytes):
-            return body.decode("utf-8")
-        return body
+        return body if isinstance(body, bytes) else body.encode("utf-8")
 
     @staticmethod
     def _is_not_found_error(exc: Exception) -> bool:

agentbyte-0.22.2/src/agentbyte/dataset/sqlite_db.py

@@ -0,0 +1,172 @@
+"""SQLite .db binary dataset backed by a native SQLite file via aiosqlite."""
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+from agentbyte.dataset.base import BaseDataset, DatasetConfig
+from agentbyte.dataset.sqlite import SqliteColumn, SqliteSchema, validate_sqlite_identifier
+
+
+class SQLiteDbDataset(BaseDataset):
+    """Async SQLite dataset backed by a native .db binary file.
+
+    For local sources the .db file is opened directly. For S3 sources the
+    binary bytes are written to a temp file which is deleted on ``aclose()``.
+
+    Use as an async context manager:
+
+        async with load_dataset("hr/employees", LocalDatasetConfig(...)) as ds:
+            rows = await ds.fetch_all()
+
+    Or call ``aclose()`` explicitly when done.
+
+    Attributes:
+        dataset_id: Canonical ``category/name`` identifier.
+        config: Dataset configuration (engine, table_names, description).
+        source_uri: Human-readable dataset location.
+    """
+
+    def __init__(
+        self,
+        dataset_id: str,
+        config: DatasetConfig,
+        source_uri: str,
+        db_path: Path | None = None,
+        db_bytes: bytes | None = None,
+        # Accept and ignore these for compatibility with _build_dataset()
+        data_text: str = "",
+        schema_text: str | None = None,
+        table_files: list | None = None,
+    ) -> None:
+        if config.engine != "sqlite_db":
+            raise ValueError(
+                f"SQLiteDbDataset requires engine='sqlite_db', got {config.engine!r}."
+            )
+        if db_path is None and db_bytes is None:
+            raise ValueError("Either db_path or db_bytes must be provided.")
+        self.dataset_id = dataset_id
+        self.config = config
+        self.source_uri = source_uri
+        self._db_path = db_path
+        self._db_bytes = db_bytes
+        self._connection: aiosqlite.Connection | None = None
+        self._tmp_path: str | None = None
+        self._schema: SqliteSchema | None = None
+
+    @property
+    def engine(self) -> str:
+        return "sqlite_db"
+
+    @property
+    def table_name(self) -> str:
+        """First table name, or empty string for multi-table datasets."""
+        names = self.config.table_names
+        return names[0] if names else ""
+
+    @property
+    def table_names(self) -> list[str]:
+        return self.config.table_names
+
+    @property
+    def schema(self) -> SqliteSchema | None:
+        """Schema for single-table datasets (populated on first connect())."""
+        return self._schema
+
+    async def _open_connection(self) -> aiosqlite.Connection:
+        if self._db_path is not None:
+            conn = await aiosqlite.connect(str(self._db_path))
+        else:
+            with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+                f.write(self._db_bytes)  # type: ignore[arg-type]
+                self._tmp_path = f.name
+            conn = await aiosqlite.connect(self._tmp_path)
+        conn.row_factory = aiosqlite.Row
+        return conn
+
+    async def _load_schema(self, conn: aiosqlite.Connection, table_name: str) -> SqliteSchema:
+        """Derive SqliteSchema from PRAGMA table_info + index_list."""
+        unique_cols: set[str] = set()
+        async with conn.execute(f"PRAGMA index_list({table_name})") as cur:
+            indexes = await cur.fetchall()
+        for idx in indexes:
+            if idx["unique"]:
+                async with conn.execute(f"PRAGMA index_info({idx['name']})") as cur:
+                    for info in await cur.fetchall():
+                        unique_cols.add(info["name"])
+
+        async with conn.execute(f"PRAGMA table_info({table_name})") as cur:
+            rows = await cur.fetchall()
+
+        columns = [
+            SqliteColumn(
+                name=row["name"],
+                type=row["type"] or "TEXT",
+                primary_key=bool(row["pk"]),
+                not_null=bool(row["notnull"]),
+                unique=row["name"] in unique_cols,
+            )
+            for row in rows
+        ]
+        return SqliteSchema(columns=columns)
+
+    async def connect(self) -> aiosqlite.Connection:
+        """Open (or return cached) aiosqlite connection to the .db file.
+
+        Populates ``schema`` for single-table datasets on first call.
+
+        Returns:
+            aiosqlite.Connection ready to query.
+        """
+        if self._connection is not None:
+            return self._connection
+        conn = await self._open_connection()
+        if len(self.config.table_names) == 1:
+            self._schema = await self._load_schema(conn, self.config.table_names[0])
+        self._connection = conn
+        return conn
+
+    async def fetch_all(self) -> list[dict[str, Any]] | dict[str, list[dict[str, Any]]]:
+        """Return all rows as a list (single-table) or dict of lists (multi-table).
+
+        - Single-table: returns ``list[dict[str, Any]]`` — one dict per row.
+        - Multi-table: returns ``dict[str, list[dict[str, Any]]]`` — one key per table.
+
+        Use ``connect()`` directly for SQL JOINs across tables.
+        """
+        conn = await self.connect()
+        if len(self.config.table_names) <= 1:
+            table = validate_sqlite_identifier(self.table_name, field_name="table_name")
+            async with conn.execute(f"SELECT * FROM {table}") as cursor:  # noqa: S608
+                return [dict(row) for row in await cursor.fetchall()]
+        result: dict[str, list[dict[str, Any]]] = {}
+        for name in self.config.table_names:
+            table = validate_sqlite_identifier(name, field_name="table_name")
+            async with conn.execute(f"SELECT * FROM {table}") as cursor:  # noqa: S608
+                result[name] = [dict(row) for row in await cursor.fetchall()]
+        return result
+
+    async def aclose(self) -> None:
+        """Close the connection and delete any S3-sourced temp file."""
+        if self._connection is not None:
+            await self._connection.close()
+            self._connection = None
+        if self._tmp_path is not None:
+            try:
+                os.unlink(self._tmp_path)
+            except OSError:
+                pass
+            self._tmp_path = None
+
+    async def __aenter__(self) -> "SQLiteDbDataset":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        tables = ", ".join(self.config.table_names)
+        return f"SQLiteDbDataset(id='{self.dataset_id}', tables=[{tables}])"