acty-core 0.1.0__tar.gz

acty_core-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+__pycache__/
+.coverage
+.mypy_cache/

acty_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Konstantin Polev
+
+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.

acty_core-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: acty-core
+Version: 0.1.0
+Summary: Group-only runtime core for scheduling, lifecycle, events, and cache primitives
+Project-URL: Homepage, https://github.com/conspol/acty-core
+Project-URL: Repository, https://github.com/conspol/acty-core
+Project-URL: Issues, https://github.com/conspol/acty-core/issues
+Maintainer-email: Konstantin Polev <70580603+conspol@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,runtime,scheduler,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Requires-Dist: rich>=13.0.0
+Requires-Dist: structlog>=21.5.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.39.0; extra == 'dev'
+Requires-Dist: prometheus-client>=0.22.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# acty-core
+
+`acty-core` is the low-level runtime package behind the Acty ecosystem. It
+provides the scheduler, lifecycle controller, event bus, cache primitives, and
+lightweight demo executors without the higher-level TUI API.
+
+## Install
+
+```bash
+pip install acty-core
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Example
+
+Run the headless group demo:
+
+```bash
+python examples/group_headless.py --groups 3
+```
+
+Run the scheduler-only demo:
+
+```bash
+python examples/scheduler_headless.py --groups 3
+```
+
+Write JSONL events that can be inspected later:
+
+```bash
+python examples/scheduler_jsonl.py --event-jsonl /tmp/acty_events.jsonl
+```
+
+## What It Includes
+
+- `GroupLifecycleController` for primer/follower orchestration
+- `WorkStealingScheduler` and pool configuration
+- event bus primitives and JSONL-friendly event emission
+- cache registry and cache-handle propagation support
+- development executors such as `NoopExecutor`, `EchoExecutor`, and `SimulatedExecutor`
+
+## Logging
+
+`acty-core` uses `structlog`. For readable local logs and rich tracebacks:
+
+```python
+from acty_core import configure_logging
+
+configure_logging(handler="rich", show_locals=True)
+```
+
+## Cache Behavior
+
+When a group uses a cache registry, the lifecycle attaches the resolved cache
+handle to queued jobs as `job.cache_handle`. Executors can reuse provider
+metadata from the cache handle instead of creating duplicate cache entries.
+
+## Development
+
+- tests live under `tests/`
+- example programs live under `examples/`
+- the package is intentionally usable without the higher-level `acty` TUI layer

acty_core-0.1.0/README.md

@@ -0,0 +1,67 @@
+# acty-core
+
+`acty-core` is the low-level runtime package behind the Acty ecosystem. It
+provides the scheduler, lifecycle controller, event bus, cache primitives, and
+lightweight demo executors without the higher-level TUI API.
+
+## Install
+
+```bash
+pip install acty-core
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Example
+
+Run the headless group demo:
+
+```bash
+python examples/group_headless.py --groups 3
+```
+
+Run the scheduler-only demo:
+
+```bash
+python examples/scheduler_headless.py --groups 3
+```
+
+Write JSONL events that can be inspected later:
+
+```bash
+python examples/scheduler_jsonl.py --event-jsonl /tmp/acty_events.jsonl
+```
+
+## What It Includes
+
+- `GroupLifecycleController` for primer/follower orchestration
+- `WorkStealingScheduler` and pool configuration
+- event bus primitives and JSONL-friendly event emission
+- cache registry and cache-handle propagation support
+- development executors such as `NoopExecutor`, `EchoExecutor`, and `SimulatedExecutor`
+
+## Logging
+
+`acty-core` uses `structlog`. For readable local logs and rich tracebacks:
+
+```python
+from acty_core import configure_logging
+
+configure_logging(handler="rich", show_locals=True)
+```
+
+## Cache Behavior
+
+When a group uses a cache registry, the lifecycle attaches the resolved cache
+handle to queued jobs as `job.cache_handle`. Executors can reuse provider
+metadata from the cache handle instead of creating duplicate cache entries.
+
+## Development
+
+- tests live under `tests/`
+- example programs live under `examples/`
+- the package is intentionally usable without the higher-level `acty` TUI layer

acty_core-0.1.0/examples/attach_tui_later.md

@@ -0,0 +1,19 @@
+# Attach TUI Later (JSONL follow)
+
+1) Run a long job and write JSONL events:
+
+```bash
+python examples/scheduler_jsonl.py --event-jsonl /tmp/acty_events.jsonl
+```
+
+2) In another shell, attach the TUI and follow:
+
+```bash
+acty-tui follow /tmp/acty_events.jsonl
+```
+
+3) For a completed run, replay:
+
+```bash
+acty-tui replay /tmp/acty_events.jsonl --speed 2.0
+```

acty_core-0.1.0/examples/group_headless.py

@@ -0,0 +1,256 @@
+"""Group-only headless harness for acty-core."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+from acty_core.core.types import Job, JobResult
+from acty_core.events import EventBus, JsonlEventSink
+from acty_core.lifecycle import (
+    FollowerDispatchPolicy,
+    GroupLifecycleController,
+    GroupSpec,
+    GroupTaskKind,
+)
+from acty_core.results import AsyncQueueResultSink
+from acty_core.scheduler import PoolConfig, WorkStealingScheduler
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class DemoConfig:
+    groups: int = 3
+    followers_per_group: int = 5
+    open_groups: bool = False
+    warm_delay_s: float = 0.0
+    max_followers_inflight: int = 2
+    follower_dispatch_policy: FollowerDispatchPolicy = field(default_factory=FollowerDispatchPolicy)
+    primer_workers: int = 1
+    follower_workers: int = 2
+    min_delay_s: float = 0.01
+    max_delay_s: float = 0.05
+    event_jsonl: str | None = None
+    seed: int = 0
+    result_queue_size: int = 0
+    result_drop_policy: str = "drop_oldest"
+
+
+class DemoExecutor:
+    def __init__(
+        self,
+        controller: GroupLifecycleController,
+        *,
+        rng: random.Random,
+        min_delay_s: float,
+        max_delay_s: float,
+    ) -> None:
+        self._controller = controller
+        self._rng = rng
+        self._min_delay_s = min_delay_s
+        self._max_delay_s = max_delay_s
+
+    async def execute(self, job: Job, *, pool: str) -> JobResult:
+        group_id = str(job.group_id) if job.group_id is not None else ""
+        delay = self._rng.uniform(self._min_delay_s, self._max_delay_s)
+        if job.kind == GroupTaskKind.PRIMER.value:
+            await self._controller.mark_primer_started(group_id)
+            await asyncio.sleep(delay)
+            await self._controller.mark_primer_done(group_id)
+        elif job.kind == GroupTaskKind.FOLLOWER.value:
+            await asyncio.sleep(delay)
+            await self._controller.mark_follower_done(group_id)
+        else:
+            await asyncio.sleep(delay)
+        return JobResult(job_id=job.id, kind=job.kind, ok=True, output={"payload": job.payload})
+
+
+async def _drain_results(
+    queue: asyncio.Queue[JobResult],
+    done_event: asyncio.Event,
+) -> tuple[int, int]:
+    ok = 0
+    failed = 0
+    last_timeout_log = 0.0
+    log_interval_s = 2.0
+    while True:
+        if done_event.is_set() and queue.empty():
+            break
+        try:
+            result = await asyncio.wait_for(queue.get(), timeout=0.1)
+        except asyncio.TimeoutError:
+            now = time.monotonic()
+            if now - last_timeout_log >= log_interval_s:
+                last_timeout_log = now
+                logger.debug(
+                    "Result queue wait timed out; continuing",
+                    done_event_set=done_event.is_set(),
+                    queue_size=queue.qsize(),
+                )
+            continue
+        if result.ok:
+            ok += 1
+        else:
+            failed += 1
+        queue.task_done()
+    return ok, failed
+
+
+async def run_headless(config: DemoConfig) -> None:
+    sinks = []
+    jsonl_sink = None
+    if config.event_jsonl:
+        jsonl_sink = JsonlEventSink(Path(config.event_jsonl))
+        sinks.append(jsonl_sink)
+    event_bus = EventBus(sinks) if sinks else None
+
+    result_sink = AsyncQueueResultSink(
+        maxsize=config.result_queue_size,
+        drop_policy=config.result_drop_policy,
+    )
+
+    controller = GroupLifecycleController(
+        event_bus=event_bus,
+        follower_dispatch_policy=config.follower_dispatch_policy,
+    )
+
+    scheduler = WorkStealingScheduler(
+        pools=[
+            PoolConfig(name="primer", preferred_kinds=[GroupTaskKind.PRIMER.value], workers=config.primer_workers),
+            PoolConfig(
+                name="follower",
+                preferred_kinds=[GroupTaskKind.FOLLOWER.value],
+                workers=config.follower_workers,
+            ),
+        ],
+        event_bus=event_bus,
+        result_sink=result_sink,
+    )
+
+    rng = random.Random(config.seed)
+    executor = DemoExecutor(
+        controller,
+        rng=rng,
+        min_delay_s=config.min_delay_s,
+        max_delay_s=config.max_delay_s,
+    )
+
+    group_ids: list[str] = []
+    for idx in range(config.groups):
+        group_id = f"group-{idx + 1}"
+        spec = GroupSpec(
+            group_id=group_id,
+            followers_total=None if config.open_groups else config.followers_per_group,
+            warm_delay_s=config.warm_delay_s,
+            max_followers_inflight=config.max_followers_inflight,
+            payload={"group_id": group_id, "primer": True},
+        )
+        await controller.add_group(spec)
+        if config.open_groups:
+            payloads = [
+                {"group_id": group_id, "follower": i + 1}
+                for i in range(config.followers_per_group)
+            ]
+            await controller.add_followers(group_id, payloads)
+            await controller.close_group(group_id)
+        group_ids.append(group_id)
+
+    scheduler_task = asyncio.create_task(scheduler.run(controller, executor))
+
+    done_event = asyncio.Event()
+    results_task = asyncio.create_task(_drain_results(result_sink.queue, done_event))
+
+    await asyncio.gather(*(controller.wait_group_done(gid) for gid in group_ids))
+    await controller.close()
+    report = await scheduler_task
+    done_event.set()
+    ok, failed = await results_task
+
+    if jsonl_sink is not None:
+        jsonl_sink.close()
+
+    print("Run complete.")
+    print(f"Queued: {report.queued}")
+    print(f"Finished: {report.finished}")
+    print(f"Failed: {report.failed}")
+    print(f"Results OK: {ok} Failed: {failed} Dropped: {result_sink.dropped}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run acty-core group-only headless demo.")
+    parser.add_argument("--groups", type=int, default=3)
+    parser.add_argument("--followers-per-group", type=int, default=5)
+    parser.add_argument("--open-groups", action="store_true")
+    parser.add_argument("--warm-delay-s", type=float, default=0.0)
+    parser.add_argument("--max-followers-inflight", type=int, default=2)
+    parser.add_argument("--dispatch-mode", type=str, default="target", choices=["serial", "target", "eager"])
+    parser.add_argument("--dispatch-target-total", type=int, default=None)
+    parser.add_argument("--dispatch-min-per-group", type=int, default=0)
+    parser.add_argument("--dispatch-max-per-group", type=int, default=None)
+    parser.add_argument("--primer-workers", type=int, default=1)
+    parser.add_argument("--follower-workers", type=int, default=2)
+    parser.add_argument("--min-delay-s", type=float, default=0.01)
+    parser.add_argument("--max-delay-s", type=float, default=0.05)
+    parser.add_argument("--event-jsonl", type=str, default="")
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--result-queue-size", type=int, default=0)
+    parser.add_argument(
+        "--result-drop-policy",
+        type=str,
+        default="drop_oldest",
+        choices=["block", "drop_newest", "drop_oldest"],
+    )
+    return parser
+
+
+def _normalize_optional_int(value: int | None) -> int | None:
+    if value is None or value == 0:
+        return None
+    return value
+
+
+def build_demo_config(args: argparse.Namespace) -> DemoConfig:
+    target_total = _normalize_optional_int(args.dispatch_target_total)
+    max_per_group = _normalize_optional_int(args.dispatch_max_per_group)
+    if args.dispatch_mode == "target" and target_total is None:
+        target_total = max(1, args.follower_workers)
+    return DemoConfig(
+        groups=args.groups,
+        followers_per_group=args.followers_per_group,
+        open_groups=args.open_groups,
+        warm_delay_s=args.warm_delay_s,
+        max_followers_inflight=args.max_followers_inflight,
+        follower_dispatch_policy=FollowerDispatchPolicy(
+            mode=args.dispatch_mode,
+            target_total=target_total,
+            min_per_group=args.dispatch_min_per_group,
+            max_per_group=max_per_group,
+        ),
+        primer_workers=args.primer_workers,
+        follower_workers=args.follower_workers,
+        min_delay_s=args.min_delay_s,
+        max_delay_s=args.max_delay_s,
+        event_jsonl=args.event_jsonl or None,
+        seed=args.seed,
+        result_queue_size=args.result_queue_size,
+        result_drop_policy=args.result_drop_policy,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config = build_demo_config(args)
+    asyncio.run(run_headless(config))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

acty_core-0.1.0/examples/groups_with_cache_registry.py

@@ -0,0 +1,168 @@
+"""Group-only example using CacheRegistry with SQLite storage."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import random
+from dataclasses import dataclass
+
+from acty_core.cache import CacheRegistry
+from acty_core.cache.storage_sqlite import SQLiteStorage
+from acty_core.core.types import Job, JobResult
+from acty_core.lifecycle import GroupLifecycleController, GroupSpec, GroupTaskKind
+from acty_core.scheduler import PoolConfig, WorkStealingScheduler
+
+
+class DemoCacheProvider:
+    name = "demo"
+
+    def fingerprint(self, primer, context=None) -> str:
+        return f"{primer}:{context}"
+
+    async def create(self, primer, context=None) -> str | None:
+        return f"ref:{primer}"
+
+    async def wait_ready(self, provider_ref, timeout_s=None) -> None:
+        return None
+
+    async def invalidate(self, provider_ref) -> None:
+        return None
+
+
+@dataclass
+class DemoCounters:
+    primer_jobs: int = 0
+    follower_jobs: int = 0
+
+
+@dataclass(frozen=True)
+class DemoConfig:
+    followers_per_group: int = 3
+    primer_workers: int = 1
+    follower_workers: int = 2
+    min_delay_s: float = 0.01
+    max_delay_s: float = 0.05
+    seed: int = 0
+    cache_path: str = "cache.sqlite"
+
+
+class DemoExecutor:
+    def __init__(
+        self,
+        controller: GroupLifecycleController,
+        counters: DemoCounters,
+        *,
+        rng: random.Random,
+        min_delay_s: float,
+        max_delay_s: float,
+    ) -> None:
+        self._controller = controller
+        self._counters = counters
+        self._rng = rng
+        self._min_delay_s = min_delay_s
+        self._max_delay_s = max_delay_s
+
+    async def execute(self, job: Job, *, pool: str) -> JobResult:
+        group_id = str(job.group_id) if job.group_id is not None else ""
+        delay = self._rng.uniform(self._min_delay_s, self._max_delay_s)
+        if job.kind == GroupTaskKind.PRIMER.value:
+            self._counters.primer_jobs += 1
+            await self._controller.mark_primer_started(group_id)
+            await asyncio.sleep(delay)
+            await self._controller.mark_primer_done(group_id)
+        elif job.kind == GroupTaskKind.FOLLOWER.value:
+            self._counters.follower_jobs += 1
+            await asyncio.sleep(delay)
+            await self._controller.mark_follower_done(group_id)
+        else:
+            await asyncio.sleep(delay)
+        return JobResult(job_id=job.id, kind=job.kind, ok=True, output={"payload": job.payload})
+
+
+async def run_pass(label: str, registry: CacheRegistry, config: DemoConfig) -> None:
+    controller = GroupLifecycleController(cache_registry=registry)
+    scheduler = WorkStealingScheduler(
+        pools=[
+            PoolConfig(name="primer", preferred_kinds=[GroupTaskKind.PRIMER.value], workers=config.primer_workers),
+            PoolConfig(
+                name="follower",
+                preferred_kinds=[GroupTaskKind.FOLLOWER.value],
+                workers=config.follower_workers,
+            ),
+        ],
+    )
+
+    counters = DemoCounters()
+    rng = random.Random(config.seed)
+    executor = DemoExecutor(
+        controller,
+        counters,
+        rng=rng,
+        min_delay_s=config.min_delay_s,
+        max_delay_s=config.max_delay_s,
+    )
+
+    group_id = f"{label}-group"
+    await controller.add_group(
+        GroupSpec(
+            group_id=group_id,
+            followers_total=config.followers_per_group,
+            payload={"group_id": group_id},
+            cache_group_id="shared-cache",
+            primer_content="primer-v1",
+        )
+    )
+
+    await scheduler.run(controller, executor)
+    await controller.wait_group_done(group_id)
+    await controller.close()
+
+    print(f"{label}: primer_jobs={counters.primer_jobs} follower_jobs={counters.follower_jobs}")
+
+
+async def run_demo(config: DemoConfig) -> None:
+    storage = SQLiteStorage(config.cache_path)
+    provider = DemoCacheProvider()
+
+    registry = CacheRegistry(provider, storage=storage)
+    await run_pass("first", registry, config)
+    await storage.close()
+
+    # New registry + storage simulates a new process using the same SQLite cache.
+    storage = SQLiteStorage(config.cache_path)
+    registry2 = CacheRegistry(DemoCacheProvider(), storage=storage)
+    await run_pass("second", registry2, config)
+    await storage.close()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run group-only demo with CacheRegistry + SQLite.")
+    parser.add_argument("--followers-per-group", type=int, default=3)
+    parser.add_argument("--primer-workers", type=int, default=1)
+    parser.add_argument("--follower-workers", type=int, default=2)
+    parser.add_argument("--min-delay-s", type=float, default=0.01)
+    parser.add_argument("--max-delay-s", type=float, default=0.05)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--cache-path", type=str, default="cache.sqlite")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config = DemoConfig(
+        followers_per_group=args.followers_per_group,
+        primer_workers=args.primer_workers,
+        follower_workers=args.follower_workers,
+        min_delay_s=args.min_delay_s,
+        max_delay_s=args.max_delay_s,
+        seed=args.seed,
+        cache_path=args.cache_path,
+    )
+    asyncio.run(run_demo(config))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())