V0.3.3.1

What's Changed

• Add workflow pointer rebase API and make weak cache thread-safe by @JohnRichard4096 in #16

Full Changelog: 0.3.3...0.3.3.1

V0.3.3

Release Summary: AmritaSense v0.3.3

We are pleased to announce the release of AmritaSense 0.3.3, which introduces important documentation enhancements, runtime safety improvements, and a formal policy for AI‑generated content.

---

🔐 New AIGC Content Licensing Policy (AACLP v1)

We have adopted the AmritaConstant AIGC Content Licensing Policy (AACLP v1) to provide clear guidelines for contributions involving AI‑generated content. This policy:

• Recognises AI tools as part of the development toolchain, while placing ultimate responsibility on human contributors.
• Sets out rules for core business logic, documentation, and test cases.
• Requires all AI‑assisted content to be reviewed by a human before submission.

The full policy is available in POLICY_OF_AIGC and referenced in the README and CONTRIBUTING.md.

---

📚 Documentation Overhaul

New Guide: External Interrupt Calls (4.4)

A comprehensive new section explains how external systems can safely inject subroutines using call_sub(interrupt=True) and the interpreter lock. This unlocks powerful debugging, monitoring, and dynamic control capabilities.

Expanded SuspendObjectStream API Reference

The reference documentation for SuspendObjectStream has been completely rewritten, covering:

• Two‑layer interrupt architecture (outer control‑flow suspend vs. inner data‑flow callback).
• The distinction between stateful suspend points and stateless polling.
• Detailed public methods, usage patterns, and concurrency safety.

Revised “Execution and Interrupt” (3.4)

The core concepts chapter now clearly distinguishes between:

• Internal interrupts – suppressible exceptions (Exception) vs. unsuppressible InterruptNotice.
• External interrupts – driven by call_sub(interrupt=True).
• Cooperative suspend – wait_to_suspend / resume for recoverable pauses.
  A new table summarises the differences, and the panic/recovery flow is now illustrated with a Mermaid diagram.

Other Documentation Updates

• Added local search to VitePress configuration.
• Updated Python version support to 3.10 – 3.15 in getting‑started guides.
• Improved examples and fixed arrow formatting (→ replaced by ->) across demos and guides.

---

⚙️ Runtime Improvements

• Safe call_sub lock checks: Added a runtime guard that raises a RuntimeError if call_sub is invoked without interrupt=True when the interpreter lock is not already held, preventing accidental misuse.
• Centralised reset on InterruptNotice: The reset() method now handles cleanup (clearing pointer, return‑address stack, and jump marks) for better maintainability.
• Version bump: amrita-sense now at 0.3.3.

---

🧪 CI and Testing

• Updated the CI script comment to reflect the pipeline steps.
• Expanded test coverage for the new lock check and interrupt reset behaviour.

---

🗑️ Miscellaneous

• Demos 03_dependency_injection.py, 06_try_catch.py, 08_interrupt_suspend.py, 12_inline_workflow.py, and 13_ret_far.py now use -> consistently for visual clarity.
• The CODE_OF_CONDUCT.md contact email has been updated.

Pull Requests

• Document interrupt model and enforce safe external sub-calls by @JohnRichard4096 in #13

---

We encourage all users to review the new AIGC policy and the enhanced documentation, especially the external interrupt and suspend‑object‑stream sections. Upgrade to 0.3.3 via pip:

pip install --upgrade amrita-sense

Happy workflows! 🚀

Full Changelog: 0.3.2...0.3.3

V0.3.2

Release Summary: amrita-sense v0.3.2

We are pleased to announce the release of amrita-sense v0.3.2. This version introduces a foundational concurrency primitive, the CLCA (Cross Loop Callback‑Allocate) design pattern, which enables safe cross‑event‑loop signalling and makes SuspendObjectStream fully thread‑ and coroutine‑safe. This unlocks new capabilities for sharing I/O streams across interpreters and threads without extra synchronization overhead.

---

✨ Major New Features

CLCA Design Pattern

• A new lightweight signal‑distribution pattern, CLCA, is now documented in both English and Chinese.
• CLCA decouples “suspend” and “resume” from complex flow control, providing a reusable cross‑event‑loop primitive for waking multiple waiters with a single signal.
• Two practical implementations are introduced:
  • Signal – coroutines voluntarily yield and wait for an external signal.
  • CheckpointSignal – external controllers set checkpoints where coroutines automatically suspend.
• This pattern is the backbone for the concurrency improvements in SuspendObjectStream.

SuspendObjectStream Now Fully Concurrency‑Safe

• SuspendObjectStream has been re‑engineered using the CLCA pattern:
  • Multiple coroutines (even across threads/event loops) can now safely share a single SuspendObjectStream instance.
  • Concurrent calls to wait_to_suspend(), resume(), yield_response(), and push_object() are properly serialized with an internal aiologic.Lock.
  • The previous one‑waiter limitation is gone; all waiters are woken atomically when resume() is called.
• This makes sharing the object_io stream between parent and child interpreters safe and efficient.

Child Interpreter Now Shares object_io by Default

• WorkflowInterpreter.fork_interpreter() now reuses the parent’s object_io instance when object_io=None (previously it created a new independent stream).
• Because SuspendObjectStream is now concurrency‑safe, sharing is safe across interpreters and threads.
• This reduces resource duplication and simplifies cross‑interpreter communication.

---

📚 Documentation Improvements

• Added comprehensive CLCA Design Pattern guide (/guide/practice/clca-design-pattern.md) with sequence diagrams, implementation details, and usage examples.
• Updated SuspendObjectStream API reference to highlight concurrency safety (v0.3.2+).
• Updated subgraph‑isolation documentation to reflect the new shared‑stream behavior.
• Both English and Chinese versions are provided.

---

🔧 CI & Dependency Updates

• CI pipeline: now triggers only on main branch pushes and pull requests; added Python 3.15 to the test matrix.
• Dependabot enabled for weekly dependency updates.
• Python version support: expanded to <3.16 (previously <3.15).
• Dependencies upgraded:
  • aiologic → 0.17.0
  • anyio → 4.14.0
  • Added explicit dependency on exceptiongroup >=1.3.1.
• Frontend docs dependencies updated (mermaid, markdown-it, dompurify, etc.).

---

🐛 Bug Fixes & Code Cleanup

• Fixed a finally block placement in hook/matcher.py that incorrectly suppressed logging and early return of block=True.
• Removed the deprecated _advance_pointer method (now use advance_pointer).
• Various internal improvements to SuspendObjectStream:
  • State transitions (suspend/resume, queue closure, callback registration) are now properly guarded by locks.
  • Cleaned up queue handling and callback logic.
• Added extensive test coverage for the new concurrency features (20+ new test cases).

---

📦 Upgrade Notes

• If you were relying on the old behavior where fork_interpreter() created a new independent object_io, be aware that it now shares the parent’s stream. This is safe, but if you explicitly need a fresh isolated stream, pass a new instance explicitly.
• The aiologic and anyio upgrades are backward‑compatible, but please review your own threading/async patterns if you heavily rely on these.

---

🙏 Acknowledgements

This release was driven by the need for reliable cross‑loop signalling in complex async workflows. The CLCA pattern is a distillation of lessons learned from real‑world usage. We hope it serves as a useful building block for your own projects.

---

Pull Requests

• fix: add exceptiongroup dependency and bump version to 0.3.1.post1 by @JohnRichard4096 in #2
• Configure Dependabot for uv and restrict CI to main branch by @JohnRichard4096 in #6
• build(deps): bump dompurify from 3.4.2 to 3.4.11 by @dependabot[bot] in #3
• build(deps): bump mermaid from 11.14.0 to 11.15.0 by @dependabot[bot] in #4
• build(deps): bump undici from 7.25.0 to 7.28.0 by @dependabot[bot] in #9
• build(deps): bump aiologic from 0.16.0 to 0.17.0 by @dependabot[bot] in #8
• build(deps): bump anyio from 4.13.0 to 4.14.0 by @dependabot[bot] in #7
• build(deps): bump markdown-it from 14.1.1 to 14.2.0 by @dependabot[bot] in #5
• Improve SuspendObjectStream concurrency and expand test coverage by @JohnRichard4096 in #11
• Update docs and API by @JohnRichard4096 in #12

New Contributors

• @dependabot[bot] made their first contribution in #3

Full Changelog: 0.3.1...0.3.2

V0.3.1.post1

What's Changed

• fix: add exceptiongroup dependency and bump version to 0.3.1.post1 by @JohnRichard4096 in #2

Full Changelog: 0.3.1...0.3.1.post1

V0.3.1

Release v0.3.1 — Panic & Recover, State Reset

This release introduces panic/recovery semantics to the workflow interpreter, improving debuggability and post-crash continuity. It also adds reset() for reinitializing execution state without recreating the interpreter.

✨ New Features

• Panic & Recover
  Unhandled exceptions now put the interpreter into a panic state, preserving the exception, program pointer, and entire call stack. Execution can be resumed by simply calling run() or run_step_by() again on the same interpreter — ideal for post-crash debugging, auditing, or continuation workflows.

• get_exception()
  Returns the last panic exception (or None if none occurred). Useful for inspecting crashes immediately after a failed run().

• reset()
  Resets the interpreter’s internal state (pointer, return stack, jump flag, waiter future, panic exception) to initial values. This is independent of recovery — use it when you want to restart a workflow from scratch without creating a new interpreter.

📖 Documentation

• Added comprehensive Panic/Recover section to the API reference, including a comparison table with Try-Catch.
• Documented get_exception() and reset() in both English and Chinese docs.

🔧 Internal Improvements

• Improved logging on panic: the interpreter logs the exception, pointer location, and interpreter ID before dumping state.
• Enhanced waiter future finalization to avoid hanging on interpreter reset.

🐛 Fixes

• Proper handling of waiter future status during reset to prevent stale waits.

---

Upgrade:

pip install --upgrade amrita-sense

Full Changelog: 0.3.0...0.3.1

V0.3.0

Release Summary – v0.3.0

We’re excited to announce AmritaSense 0.3.0! This release introduces a powerful interpreter tree model, isolated sub‑workflow execution, safe low‑level tuning flags, and several quality‑of‑life improvements.

🚀 Major New Features

Interpreter Tree & Subgraph Isolation

• fork_interpreter() – create child interpreters that form a tree. Each interpreter has its own lifecycle, middleware, and I/O stream.
• FUN_BLOCK instruction – execute a compiled NodeCompose as an isolated sub‑workflow in a dedicated child interpreter. Supports reusable or one‑time interpreters.
• Lifecycle management – terminate(), terminate_all(), wait_all(), and wait_all_forks() give you full control over graceful shutdown and parallel execution.
• Tree inspection – parent, top_interpreter, sub_interpreters, and all_sub_interpreters properties let you navigate the interpreter tree.

Unsafe Configuration Flags

A new _unsafe.__flags__ module exposes internal engine switches for rare edge cases. Flags are locked after first assignment to ensure predictable behaviour.

• FORCE_NOT_WRAP_TO_ASYNC – run synchronous nodes on the event loop thread (bypass asyncio.to_thread).
• DISABLE_EXC_IGNORED – prevent automatic penetration of InterruptNotice / BreakLoop through TRY/CATCH.
• ALLOW_CALL_NODECOMPOSE – allow direct _call() on a NodeCompose.
• NO_DEPENDENCY_META_CACHE – re‑resolve dependency metadata on every call.
• NO_SHARED_MIDDLEWARE – disable automatic middleware inheritance when forking.

Improved Manual Stack Management

• PUSH_AND_GOTO(from_adr, to_adr) – a convenience instruction that combines PUSH_STACK + GOTO into a single node.

📚 Documentation

• New guides: Unsafe Features (/guide/advanced/unsafe) and Subgraph Isolation (/guide/practice/subgraph-isolation).
• Updated manual stack management documentation with PUSH_AND_GOTO.
• Expanded API reference for the interpreter tree, IllegalState, and search_exceptions().
• Chinese translations for all new content.

🧪 New Demos & Tests

• demos/16_subgraph_isolation.py – parallel execution, interpreter tree properties, early termination.
• demos/17_unsafe_flags.py – flag configuration and locking behaviour.
• Comprehensive unit & integration tests for FUN_BLOCK, PUSH_AND_GOTO, and interpreter tree APIs.

🔧 Other Changes

• Moved sign_func from hook.matcher to hook.fun_typing for cleaner imports.
• NodeCompose now rejects NodeComposeRendered elements (type safety).
• Added IllegalState exception for operations on non‑top‑level interpreters or when an interpreter is not running.
• TRY/CATCH and loop instructions respect DISABLE_EXC_IGNORED.
• Fixed a potential deadlock in child interpreter cleanup.

⚠️ Migration Notes

• Backward compatible – existing workflows continue to work unchanged.
• If you used PUSH_STACK or RET_FAR from amrita_sense.instructions, the import path is unchanged and behaviour is identical.
• The _advance_pointer alias is now fully deprecated (use advance_pointer).

🙏 Acknowledgements

Thanks to all contributors and early testers who helped shape this release.

---

Upgrade today:
pip install --upgrade amrita-sense

Full Changelog: 0.2.4...0.3.0

V0.2.4

Release v0.2.4

This release introduces a new PUSH_STACK instruction for explicit return address stack management, making manual stack operations more ergonomic. The execution pointer advancement logic is now exposed as a public advance_pointer() method, and ARCHIVED_NODES has been generalized to accept any BaseNode.

✨ New Features

• PUSH_STACK(alias_or_idata) – Push a return address onto _ret_addr_stack directly from the composition chain, eliminating the need for manual node-based pushes. Pair with GOTO and RET_FAR for custom call/return patterns.
• WorkflowInterpreter.advance_pointer(ptr=None) – Public method for advancing the execution pointer through nested workflows. Supports external pointer preview without mutating interpreter state.

📝 Improvements

• ARCHIVED_NODES now accepts arbitrary BaseNode (not only AliasNode), enabling more flexible subroutine storage patterns.
• Documentation updated across English and Chinese guides to reflect the new PUSH_STACK instruction, including a new "subroutine-like pattern with ARCHIVED_NODES" example.
• Demo 13_ret_far.py refactored to use PUSH_STACK instead of manual stack push in a custom node.

⚠️ Deprecations

• WorkflowInterpreter._advance_pointer (property) is deprecated. Use advance_pointer() instead. The old property will be removed in v0.3.0.

🐛 Fixes

• Improved error message when attempting to call a NodeComposeRendered via _call().

🔧 Internal

• Version bumped to 0.2.4.
• Type hints and imports cleaned up (typing_extensions, TYPE_CHECKING).

Full Changelog: 0.2.3...0.2.4

V0.2.3

Release v0.2.3

🔧 Demos & Documentation Overhaul

• All demo scripts simplified — removed unnecessary trailing NOP, reduced reliance on return‑value dependency injection, and converted many nodes to parameter‑less or state‑based patterns. Demos are now shorter, clearer, and focus on one concept at a time.
• Inline workflow pattern refined — the SimpleWorkflow demo now uses self.value as shared state instead of passing return values between nodes. Documentation clarifies that node return values do not automatically flow to the next node’s DI context; use instance fields for cross‑node state.
• Manual stack management re‑envisioned — RET_FAR is no longer shown as a return value inside a node. The new demo and guide demonstrate manual push → GOTO → RET_FAR pop‑and‑return, giving you explicit control over the return address stack without relying on CALL/call_sub.

🐍 Python Version Support

• Added Python 3.14 to the CI matrix.
• Constrained requires-python to >=3.10, <3.15 (explicitly disallows future 3.15 until tested).

🧹 Internal Improvements

• AliasNode now accepts any BaseNode (not only Node), making it more flexible.
• NodeCompose implements __len__, fixing several pointer‑advancement corner cases.
• WorkflowInterpreter._advance_pointer uses __len__ and boolean checks, improving robustness when entering nested containers.
• Cleaned up type annotations and imports.

📝 Documentation Updates

• English and Chinese guides for inline workflows and manual stack management synchronised with the new demos.
• API reference examples now use NodeType explicitly where synchronous lambdas are required.

---

Upgrade
pip install --upgrade amrita-sense

Full Changelog: 0.2.2...0.2.3

V0.2.2

Release v0.2.2

✨ New Features

• Event System Enhancement
  Introduced ConstructableEvent and TRIGGER_EVENT instruction – events can now be constructed on‑demand inside a workflow composition, enabling decoupled event dispatch without manual instantiation.

• Manual Stack Management
  Added RET_FAR instruction for explicit control over the return address stack. Perfect for early exit from nested CALL scopes or custom stack unwinding.

• Middleware Support
  WorkflowInterpreter now accepts an optional middleware callable, allowing custom logic to wrap every node execution (e.g., logging, metrics, injection).

• Inline Workflow Pattern
  New guide and demos for encapsulating workflows inside classes – nodes as instance methods, state on self, and a clean run() API. LangGraph‑style development without the builder boilerplate.

🚀 Improvements

• Try/Catch Stability
  Added an escape sentinel (NOP) to all TRY blocks, ensuring control flow never falls through into the enclosing composition.

• Dependency Injection
  Refined matching rules between extra_args and extra_kwargs – better error messages and predictable fallback behavior.

• Node Composition
  SelfCompileInstruction now supports the >> operator directly, making it even easier to mix custom instructions with regular nodes.

📚 Documentation & Examples

• 15 new runnable demos covering everything from minimal workflows to RET_FAR, TRIGGER_EVENT, step‑by‑step debugging, and custom self‑compile instructions.
• New advanced guides on manual stack management and inline workflows (both English and Chinese).
• Expanded API reference for WorkflowInterpreter (jump methods, middleware, far calls) and event types.

🔧 Development & CI

• Added ci.sh and companion scripts for full pipeline: environment init, linting, type checking, testing, coverage, package build, and docs build.
• Updated Ruff and Pyright configurations for stricter checks.

🌟 Other Changes

• Project motto updated: “Sense is all you need.”

---

Upgrade
pip install --upgrade amrita-sense

Full Changelog: 0.2.1...0.2.2

V0.2.1

Full Changelog: 0.2.0...0.2.1