arachnite 0.10.1__tar.gz

arachnite-0.10.1/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[all,dev,benchmarks]"
+      - name: Run tests
+        run: pytest
+
+  static:
+    name: static
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check arachnite tests benchmarks
+      - name: Mypy
+        run: mypy arachnite
+
+  coverage:
+    name: coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[all,dev,benchmarks]"
+      - name: Run tests with coverage
+        run: pytest --cov=arachnite --cov-report=xml --cov-report=term-missing --cov-fail-under=85
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-xml
+          path: coverage.xml

arachnite-0.10.1/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets — never commit these
+.env.local
+.env.*.local
+secrets.yaml
+*.pem
+*.key
+
+# Distribution
+*.tar.gz
+*.whl
+
+# Quick-launch script
+arachnite.bat

arachnite-0.10.1/LICENSE

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

arachnite-0.10.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: arachnite
+Version: 0.10.1
+Summary: A biologically-inspired reactive agent framework for Python
+Project-URL: Homepage, https://github.com/memrecolak/arachnite-oss
+Project-URL: Repository, https://github.com/memrecolak/arachnite-oss
+Project-URL: Issues, https://github.com/memrecolak/arachnite-oss/issues
+Project-URL: Documentation, https://github.com/memrecolak/arachnite-oss/tree/main/spec
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,framework,iot,reactive,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: msgpack>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typing-extensions>=4.5; python_version < '3.12'
+Provides-Extra: all
+Requires-Dist: aiomqtt>=2.0; extra == 'all'
+Requires-Dist: anthropic>=0.25; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: llama-cpp-python>=0.2; extra == 'all'
+Requires-Dist: nats-py>=2.7; extra == 'all'
+Requires-Dist: numpy>=1.26; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: psutil>=5.9; extra == 'all'
+Requires-Dist: redis<7,>=5.0; extra == 'all'
+Requires-Dist: uvicorn>=0.27; extra == 'all'
+Provides-Extra: benchmarks
+Requires-Dist: psutil>=5.9; extra == 'benchmarks'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.25; extra == 'llm'
+Provides-Extra: local-llm
+Requires-Dist: llama-cpp-python>=0.2; extra == 'local-llm'
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt>=2.0; extra == 'mqtt'
+Provides-Extra: nats
+Requires-Dist: nats-py>=2.7; extra == 'nats'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.26; extra == 'numpy'
+Provides-Extra: ollama
+Requires-Dist: openai>=1.0; extra == 'ollama'
+Provides-Extra: redis
+Requires-Dist: redis<7,>=5.0; extra == 'redis'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn>=0.27; extra == 'web'
+Description-Content-Type: text/markdown
+
+# Arachnite
+
+A biologically-inspired reactive agent framework for Python.
+
+The architecture models the nervous system of arachnids — `sense → context →
+reflex → instinct → decide → act`. Developers extend abstract base classes
+to build agents that run on edge devices (Raspberry Pi, Jetson Nano), laptops,
+or cloud servers, all connected by a pluggable transport layer.
+
+- **Async-first**: every node interface is `asyncio`-native
+- **Typed**: strict type annotations throughout (mypy strict)
+- **Pluggable transports**: in-process, MQTT, NATS, Redis
+- **Distributed by manifest**: declarative multi-device deployment
+- **Reflex co-location**: safety-critical reflexes are validated at deploy time
+- **Python 3.10+**
+
+## Install
+
+```bash
+pip install arachnite
+```
+
+With optional extras:
+
+```bash
+pip install "arachnite[all]"            # every optional dependency
+pip install "arachnite[mqtt]"           # MQTT transport
+pip install "arachnite[nats]"           # NATS transport
+pip install "arachnite[redis]"          # Redis transport
+pip install "arachnite[web]"            # bundled signal dashboard
+pip install "arachnite[llm]"            # Anthropic LLM provider
+pip install "arachnite[benchmarks]"     # psutil for RSS measurement
+```
+
+Development install from source:
+
+```bash
+git clone https://github.com/memrecolak/arachnite-oss.git arachnite
+cd arachnite
+pip install -e ".[all,dev]"
+```
+
+## Quick start
+
+A minimal agent: a sensor that reads temperature, an instinct that fires
+when it gets hot, and an action that cools things down.
+
+```python
+import asyncio
+import time
+
+from arachnite import (
+    BaseActionNode,
+    BaseInstinctNode,
+    BaseSenseNode,
+    Proposal,
+    Result,
+    RuntimeBuilder,
+    Signal,
+)
+
+
+class TempSense(BaseSenseNode):
+    node_id = "TempSense"
+    signal_kind = "temperature"
+
+    async def read(self) -> Signal:
+        return Signal(
+            source=self.node_id,
+            kind=self.signal_kind,
+            value=42.0,
+            confidence=1.0,
+            timestamp=time.monotonic(),
+        )
+
+
+class HotInstinct(BaseInstinctNode):
+    node_id = "HotInstinct"
+    priority = 80
+
+    async def evaluate(self, ctx) -> Proposal | None:
+        hot = [s for s in ctx.signals if s.kind == "temperature" and s.value > 40.0]
+        if hot:
+            return Proposal(
+                instinct_id=self.node_id,
+                action_id="CoolDown",
+                priority=self.priority,
+                urgency=0.9,
+            )
+        return None
+
+
+class CoolDown(BaseActionNode):
+    node_id = "CoolDown"
+
+    async def execute(self, proposal) -> Result:
+        print(f"Cooling down! params={proposal.parameters}")
+        return Result(action_id=self.node_id, success=True)
+
+
+async def main() -> None:
+    rt = (
+        RuntimeBuilder()
+        .sense(TempSense)
+        .instinct(HotInstinct)
+        .action(CoolDown)
+        .tick_rate(5.0)
+        .build()
+    )
+    await rt.start()
+    await asyncio.sleep(5.0)
+    await rt.stop()
+
+
+asyncio.run(main())
+```
+
+See the [`examples/`](examples) directory for more complete programs:
+reflex nodes, multi-step actions, supervisor restart policies, and a
+web dashboard.
+
+## Documentation
+
+- [`tutorials/`](tutorials) — step-by-step lessons starting at
+  [tutorials/01_welcome.md](tutorials/01_welcome.md). Advanced topics
+  (multi-step actions, supervisors, distributed deployment, LLM instincts,
+  active inference, safety monitors) live under
+  [`tutorials/advanced/`](tutorials/advanced).
+- [`spec/`](spec) — the formal framework specification, eight numbered
+  sections covering architecture, nodes, runtime, distributed deployment,
+  infrastructure, and the benchmark suite.
+
+## Core concepts
+
+### Nodes
+
+Five node families, each with an abstract base and a master that owns the
+registered instances:
+
+| Node          | Returns      | When to use                                 |
+| ------------- | ------------ | ------------------------------------------- |
+| `BaseSenseNode`     | `Signal`        | Read hardware/state, emit one signal per tick |
+| `BaseInstinctNode`  | `Proposal` or `None` | Evaluate context, propose an action     |
+| `BaseReflexInstinctNode` | `Proposal` or `None` | Same as instinct, but bypasses the decision layer (priority ≥ 200, co-located with target action) |
+| `BaseDecisionNode`  | `Decision`      | Pick which proposal to execute (Greedy / Weighted / Random / ActiveInference built-ins, or your own) |
+| `BaseActionNode`    | `Result`        | Carry out the work — must always return, never raise |
+| `MultiStepActionNode` | `Result`      | Long-running actions with interrupt/rollback policies |
+
+### Priority convention
+
+- **200+** — reflex instincts only
+- **100–199** — safety / survival
+- **50–99** — goal-directed
+- **1–49** — exploratory / maintenance
+- **0** — reserved (inactive)
+
+### Architectural rules
+
+1. Nodes never hold references to each other; communication goes through `SignalBus`.
+2. `ReflexInstinctNode` and its target `ActionNode` must be on the same `AgentNode`.
+3. `MultiStepActionNode` mandatory blocks cannot be interrupted (except `emergency_stop`).
+4. `execute()` on any `ActionNode` must always return a `Result` — never raise.
+5. `evaluate()` on any `InstinctNode` must return `None` when not applicable — never raise.
+6. All node I/O must be async — wrap blocking hardware calls in `asyncio.to_thread()`.
+
+## Distributed deployments
+
+A `DeploymentManifest` declares which nodes run on which `AgentNode`. The
+manifest validator enforces co-location rules and fails loudly on missing
+environment variables.
+
+```yaml
+agents:
+  vision:
+    transport: nats
+    transport_url: ${NATS_URL}
+    nodes:
+      - ProximitySense
+      - ObjectDetectionSense
+  control:
+    transport: nats
+    transport_url: ${NATS_URL}
+    nodes:
+      - JointPositionSense
+      - CollisionReflex     # priority 250, reflex
+      - EmergencyRetract    # co-located target
+      - GraspInstinct
+      - PickAndPlace
+```
+
+See [`examples/robot_arm/`](examples/robot_arm) for a runnable two-agent
+case study.
+
+## Benchmarks
+
+A reproducible benchmark suite ships under [`benchmarks/`](benchmarks):
+
+```bash
+# Full suite (30 runs, JSON output)
+python benchmarks/suite.py
+
+# Quick run (5 runs)
+python benchmarks/suite.py --runs 5
+
+# Individual benchmarks
+python benchmarks/tick_latency.py
+python benchmarks/reflex_latency.py
+python benchmarks/scalability_sweep.py
+python benchmarks/transport_latency.py
+```
+
+Benchmarks include tick latency, per-stage breakdown, reflex arc timing,
+memory footprint, scalability sweeps, multi-step action interrupt latency,
+long-horizon stability soak, and transport publish-to-deliver latency.
+All emit JSON with bootstrap CIs for median / P95 / P99.
+
+### Cross-framework comparison (optional)
+
+[`baselines/`](baselines) holds comparison harnesses against
+[py_trees](https://github.com/splintered-reality/py_trees),
+[ROS 2](https://docs.ros.org/), and the [Jason](https://jason-lang.github.io/)
+AgentSpeak BDI engine. **These are not part of the framework** — they are
+not installed by `pip install arachnite` and are excluded from the wheel.
+They require external toolchains (JVM, ROS 2) to run. See
+[`baselines/README.md`](baselines/README.md) for setup.
+
+## Development
+
+```bash
+# Run all tests
+pytest
+
+# With coverage
+pytest --cov=arachnite --cov-report=term-missing
+
+# Type check
+mypy arachnite
+
+# Lint
+ruff check arachnite tests benchmarks
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).