nextloop 0.1.0rc1__tar.gz

nextloop-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 12bitsD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nextloop-0.1.0rc1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: nextloop
+Version: 0.1.0rc1
+Summary: An embeddable AgentLoop with explicit event, tool, recovery, and delivery semantics
+Author-email: 12bitsD <bis12@163.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/12bitsD/nextloop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.23
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.13; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
+Requires-Dist: ruff<1,>=0.8; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Requires-Dist: types-jsonschema<5,>=4.23; extra == "dev"
+Dynamic: license-file
+
+# nextloop
+
+A small, embeddable Python AgentLoop with explicit execution, recovery, and delivery semantics.
+
+Current version: **0.1.0rc1**.
+
+## Install
+
+```bash
+python -m pip install nextloop==0.1.0rc1
+```
+
+For local development:
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python -e '.[dev]'
+```
+
+## What it provides
+
+- DSH-aligned Session/Turn/Step execution with 4D integer coordinates and writer fencing.
+- Append-only Trajectory and O(Δ) `surface_op` watermark projection.
+- In-memory `Inbox` serialization for steer and final commitment.
+- Whole-batch Tool Schema validation, bounded parallel calls, and exclusive failure barriers.
+- Closed five-variant `ToolOutcome`: `Completed`, `Skipped`, `Cancelled`, `UncertainSettled`, `UncertainHanging`.
+- Bounded Provider retries, protocol correction, WorkingContext, Compaction, and cancellation.
+- SQLite and in-memory EventStores, crash closers, and delivery-only recovery.
+- OpenAI-compatible and Anthropic streaming Provider adapters.
+
+It is a library, not an HTTP service, product bot, Router, EventBus, or multi-agent framework.
+
+## Public API
+
+```python
+AgentLoop.run(TurnContext) -> TurnOutcome
+AgentLoop.steer(session_id, content, *, input_id=None) -> bool
+AgentLoop.cancel(session_id, cause="user_stop") -> bool
+AgentLoop.recover(session_id, store, delivery) -> RecoveryOutcome
+```
+
+The only four Adapter protocols are `EventStore`, `ModelProvider`, `ToolRuntime`, and `DeliveryOwner`. Context projection and Compaction are built in and configured through `LoopConfig`.
+
+`ToolRegistry` is the built-in `ToolRuntime` implementation:
+
+```python
+from nextloop import ToolRegistry, ToolSpec, ToolExecutionMode
+
+registry = ToolRegistry()
+registry.register(
+    ToolSpec(
+        "read",
+        "Read a file",
+        {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"],
+        },
+        mode=ToolExecutionMode.PARALLEL,
+    ),
+    lambda arguments, context: "file contents",
+)
+```
+
+Run the complete fake-Provider example:
+
+```bash
+python examples/basic.py
+```
+
+It executes model → Tool → Observation → model → delivery without a hosted model.
+
+## Code structure
+
+```text
+src/nextloop/
+  contracts.py       # public schemas, ToolOutcome, four Protocols, LoopConfig
+  loop.py            # AgentLoop and active Session registry
+  driver.py          # thin Turn/Step orchestration and SessionActor
+  events/            # pure projection, response/outcome folds, crash repair
+  execute/           # model retries, Tool registration, batch scheduling
+  adapters/          # SQLite, memory, OpenAI, Anthropic
+```
+
+`events/` performs no I/O. `execute/` owns side effects and classified failures. `driver.py` only composes them.
+
+## Verification
+
+The release-candidate checks cover:
+
+- text, Tool, multi-Step, mixed, empty, truncated, and malformed responses;
+- whole-batch rejection and parallel/exclusive scheduling with deterministic gates;
+- steer/final ordering, cancellation, WorkingContext, and Compaction;
+- protocol exhaustion, exact-byte retry, and partial-output failure;
+- resource-lock recovery, conflict prevention, and explicit release;
+- real subprocess exits during Tool execution and final delivery, followed by SQLite recovery;
+- recorded OpenAI and Anthropic SSE streams;
+- `ruff`, `mypy`, wheel/sdist builds, `twine check`, and clean wheel installation.
+
+Current limits:
+
+- Hosted-model smoke and nika integration are separate acceptance work.
+- Concurrent writers across multiple processes fail closed; they are not coordinated.
+- Large-asset lifecycle, backup, and GC are not part of this release candidate.
+
+## Documents
+
+- [AgentLoop design](docs/design/agent-loop.md)
+- [Public interface](docs/design/loop-interface.md)
+- [ReAct protocol](docs/design/react-protocol.md)
+- [Verification matrix](docs/design/verification-matrix.md)
+- [Development plan](docs/architecture/development-plan.md)
+- [Changelog](CHANGELOG.md)
+- [ADR-0002](docs/adr/0002-dsh-aligned-agent-loop.md) and [ADR-0003](docs/adr/0003-python-and-centralized-contracts.md)
+
+## Release
+
+CI covers Python 3.11, 3.12, and 3.13. A `v*` tag runs the release workflow, which verifies the package, publishes wheel and sdist to PyPI through Trusted Publishing, and creates a GitHub Release.
+
+This is a public repository. Do not commit credentials, private trajectories, internal endpoints, or personal data.

nextloop-0.1.0rc1/README.md

@@ -0,0 +1,120 @@
+# nextloop
+
+A small, embeddable Python AgentLoop with explicit execution, recovery, and delivery semantics.
+
+Current version: **0.1.0rc1**.
+
+## Install
+
+```bash
+python -m pip install nextloop==0.1.0rc1
+```
+
+For local development:
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python -e '.[dev]'
+```
+
+## What it provides
+
+- DSH-aligned Session/Turn/Step execution with 4D integer coordinates and writer fencing.
+- Append-only Trajectory and O(Δ) `surface_op` watermark projection.
+- In-memory `Inbox` serialization for steer and final commitment.
+- Whole-batch Tool Schema validation, bounded parallel calls, and exclusive failure barriers.
+- Closed five-variant `ToolOutcome`: `Completed`, `Skipped`, `Cancelled`, `UncertainSettled`, `UncertainHanging`.
+- Bounded Provider retries, protocol correction, WorkingContext, Compaction, and cancellation.
+- SQLite and in-memory EventStores, crash closers, and delivery-only recovery.
+- OpenAI-compatible and Anthropic streaming Provider adapters.
+
+It is a library, not an HTTP service, product bot, Router, EventBus, or multi-agent framework.
+
+## Public API
+
+```python
+AgentLoop.run(TurnContext) -> TurnOutcome
+AgentLoop.steer(session_id, content, *, input_id=None) -> bool
+AgentLoop.cancel(session_id, cause="user_stop") -> bool
+AgentLoop.recover(session_id, store, delivery) -> RecoveryOutcome
+```
+
+The only four Adapter protocols are `EventStore`, `ModelProvider`, `ToolRuntime`, and `DeliveryOwner`. Context projection and Compaction are built in and configured through `LoopConfig`.
+
+`ToolRegistry` is the built-in `ToolRuntime` implementation:
+
+```python
+from nextloop import ToolRegistry, ToolSpec, ToolExecutionMode
+
+registry = ToolRegistry()
+registry.register(
+    ToolSpec(
+        "read",
+        "Read a file",
+        {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"],
+        },
+        mode=ToolExecutionMode.PARALLEL,
+    ),
+    lambda arguments, context: "file contents",
+)
+```
+
+Run the complete fake-Provider example:
+
+```bash
+python examples/basic.py
+```
+
+It executes model → Tool → Observation → model → delivery without a hosted model.
+
+## Code structure
+
+```text
+src/nextloop/
+  contracts.py       # public schemas, ToolOutcome, four Protocols, LoopConfig
+  loop.py            # AgentLoop and active Session registry
+  driver.py          # thin Turn/Step orchestration and SessionActor
+  events/            # pure projection, response/outcome folds, crash repair
+  execute/           # model retries, Tool registration, batch scheduling
+  adapters/          # SQLite, memory, OpenAI, Anthropic
+```
+
+`events/` performs no I/O. `execute/` owns side effects and classified failures. `driver.py` only composes them.
+
+## Verification
+
+The release-candidate checks cover:
+
+- text, Tool, multi-Step, mixed, empty, truncated, and malformed responses;
+- whole-batch rejection and parallel/exclusive scheduling with deterministic gates;
+- steer/final ordering, cancellation, WorkingContext, and Compaction;
+- protocol exhaustion, exact-byte retry, and partial-output failure;
+- resource-lock recovery, conflict prevention, and explicit release;
+- real subprocess exits during Tool execution and final delivery, followed by SQLite recovery;
+- recorded OpenAI and Anthropic SSE streams;
+- `ruff`, `mypy`, wheel/sdist builds, `twine check`, and clean wheel installation.
+
+Current limits:
+
+- Hosted-model smoke and nika integration are separate acceptance work.
+- Concurrent writers across multiple processes fail closed; they are not coordinated.
+- Large-asset lifecycle, backup, and GC are not part of this release candidate.
+
+## Documents
+
+- [AgentLoop design](docs/design/agent-loop.md)
+- [Public interface](docs/design/loop-interface.md)
+- [ReAct protocol](docs/design/react-protocol.md)
+- [Verification matrix](docs/design/verification-matrix.md)
+- [Development plan](docs/architecture/development-plan.md)
+- [Changelog](CHANGELOG.md)
+- [ADR-0002](docs/adr/0002-dsh-aligned-agent-loop.md) and [ADR-0003](docs/adr/0003-python-and-centralized-contracts.md)
+
+## Release
+
+CI covers Python 3.11, 3.12, and 3.13. A `v*` tag runs the release workflow, which verifies the package, publishes wheel and sdist to PyPI through Trusted Publishing, and creates a GitHub Release.
+
+This is a public repository. Do not commit credentials, private trajectories, internal endpoints, or personal data.

nextloop-0.1.0rc1/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nextloop"
+version = "0.1.0rc1"
+description = "An embeddable AgentLoop with explicit event, tool, recovery, and delivery semantics"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "12bitsD", email = "bis12@163.com"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "jsonschema>=4.23,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "mypy>=1.13,<2",
+  "pytest>=8,<10",
+  "pytest-asyncio>=0.24,<2",
+  "ruff>=0.8,<1",
+  "twine>=5,<7",
+  "types-jsonschema>=4.23,<5",
+]
+
+[project.urls]
+Repository = "https://github.com/12bitsD/nextloop"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nextloop = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["nextloop"]

nextloop-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nextloop-0.1.0rc1/src/nextloop/__init__.py

@@ -0,0 +1,96 @@
+from .adapters.anthropic import AnthropicProvider
+from .adapters.memory import InMemoryEventStore
+from .adapters.openai import OpenAIProvider
+from .adapters.sqlite import SQLiteEventStore
+from .contracts import (
+    API_VERSION,
+    EVENT_SCHEMA_VERSION,
+    Cancelled,
+    CandidateRequest,
+    CapacityError,
+    Completed,
+    DeliveryOwner,
+    Event,
+    EventStore,
+    EventType,
+    FinalMessage,
+    FinishReason,
+    InvariantViolation,
+    LoopConfig,
+    Message,
+    ModelProvider,
+    ModelResponse,
+    ModelUsage,
+    NewEvent,
+    NextloopError,
+    ProtocolExhausted,
+    ProviderError,
+    RecoveryOutcome,
+    Skipped,
+    SurfaceOp,
+    ToolCall,
+    ToolExecutionMode,
+    ToolOutcome,
+    ToolRuntime,
+    ToolSpec,
+    TurnContext,
+    TurnOutcome,
+    TurnStatus,
+    UncertainHanging,
+    UncertainSettled,
+    ValidatedCall,
+    ValidationIssue,
+    new_id,
+    utc_now,
+)
+from .execute.tools import ToolContext, ToolRegistry
+from .loop import AgentLoop
+
+__all__ = [
+    "API_VERSION",
+    "EVENT_SCHEMA_VERSION",
+    "AgentLoop",
+    "AnthropicProvider",
+    "CandidateRequest",
+    "Cancelled",
+    "CapacityError",
+    "Completed",
+    "DeliveryOwner",
+    "Event",
+    "EventStore",
+    "EventType",
+    "FinalMessage",
+    "FinishReason",
+    "InMemoryEventStore",
+    "InvariantViolation",
+    "LoopConfig",
+    "Message",
+    "ModelProvider",
+    "ModelResponse",
+    "ModelUsage",
+    "NewEvent",
+    "NextloopError",
+    "OpenAIProvider",
+    "ProtocolExhausted",
+    "ProviderError",
+    "RecoveryOutcome",
+    "SQLiteEventStore",
+    "Skipped",
+    "SurfaceOp",
+    "ToolCall",
+    "ToolContext",
+    "ToolExecutionMode",
+    "ToolOutcome",
+    "ToolRegistry",
+    "ToolRuntime",
+    "ToolSpec",
+    "TurnContext",
+    "TurnOutcome",
+    "TurnStatus",
+    "UncertainHanging",
+    "UncertainSettled",
+    "ValidatedCall",
+    "ValidationIssue",
+    "new_id",
+    "utc_now",
+]

nextloop-0.1.0rc1/src/nextloop/adapters/__init__.py

@@ -0,0 +1,6 @@
+from .anthropic import AnthropicProvider
+from .memory import InMemoryEventStore
+from .openai import OpenAIProvider
+from .sqlite import SQLiteEventStore
+
+__all__ = ["AnthropicProvider", "InMemoryEventStore", "OpenAIProvider", "SQLiteEventStore"]

nextloop-0.1.0rc1/src/nextloop/adapters/_sse.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import httpx
+
+
+async def data_events(response: httpx.Response) -> AsyncIterator[tuple[str, str]]:
+    event = "message"
+    data: list[str] = []
+    async for line in response.aiter_lines():
+        if not line:
+            if data:
+                yield event, "\n".join(data)
+            event = "message"
+            data = []
+            continue
+        if line.startswith(":"):
+            continue
+        if line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:"):
+            data.append(line[5:].lstrip())
+    if data:
+        yield event, "\n".join(data)