agentino-framework 1.1.0__tar.gz

agentino_framework-1.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,40 @@
+name: Bug report
+description: Something behaves differently from what the docs say
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what you got instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: >
+        The smallest script or config that shows the problem. This is the
+        single most useful thing you can include.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Release number or commit SHA.
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.3"
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or logs
+      render: text

agentino_framework-1.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/islavutin-oss/agentino/security/advisories/new
+    about: Report privately, not as a public issue.

agentino_framework-1.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose a change to what Agentino does
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >
+        What are you trying to do that is awkward or impossible today?
+        Describe the situation, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: If you have an API or config shape in mind, sketch it.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you tried instead
+      description: Workarounds you have used, and why they fall short.

agentino_framework-1.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What this changes
+
+<!-- One paragraph. What is different after this lands? -->
+
+## Why
+
+<!-- The reasoning a reviewer cannot get from the diff. Link the issue if
+     there is one. -->
+
+## Checklist
+
+- [ ] Tests cover the change, and a bug fix has a test that failed before it
+- [ ] `pytest` passes locally
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] Docs updated if behaviour or configuration changed

agentino_framework-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format --check
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: pytest
+        run: pytest tests/ -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - name: Build the distribution
+        run: python -m build
+      - name: Check the distribution metadata
+        run: twine check dist/*

agentino_framework-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write   # to attach build artifacts to the release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Attach the artifacts to the release
+        if: github.event_name == 'release'
+        run: gh release upload "$GITHUB_REF_NAME" dist/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Publishing is a separate job so a build failure never leaves a partial
+  # upload, and so the PyPI credential is scoped to this job alone. It uses
+  # Trusted Publishing (OIDC) — there is no API token stored in the repo.
+  #
+  # Before the first run, configure a pending publisher on PyPI:
+  #   https://pypi.org/manage/account/publishing/
+  #   owner: <the GitHub owner>   repository: agentino
+  #   workflow: release.yml       environment: pypi
+  publish:
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentino_framework-1.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+sessions/
+usage.jsonl
+*.jsonl
+.env
+node_modules/
+package-lock.json
+
+# Tooling caches
+.hypothesis/
+.mypy_cache/

agentino_framework-1.1.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
+to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0
+onward.
+
+## [1.1.0] — 2026-08-29
+
+### Added
+
+- Apache-2.0 licence, `NOTICE`, contribution guide, security policy, code of
+  conduct, and issue and pull-request templates.
+- `agentino.tools.std._llm_env`, one vendor-neutral resolver for the LLM
+  endpoint used by the standard tools. Configure with `AGENTINO_BASE_URL` /
+  `AGENTINO_API_KEY` or the conventional `OPENAI_*` pair.
+- `__all__` on the public packages, so the supported surface is explicit.
+- `gpt-5.4-codex` in the model registry; it is now the default Codex model.
+- `agentino.tools.std.set_pdf_renderer`, plus a plain reportlab renderer, so
+  `create_pdf` works in a standalone install. A host with its own house style
+  registers a renderer instead; async renderers are awaited.
+- Storage-contract tests for the file-producing standard tools.
+- `agentino.tools.std.set_file_storage_provider`, so a host application can
+  supply its own file storage, plus a local-filesystem default
+  (`AGENTINO_FILES_DIR`, falling back to `./.agentino/files`) so the
+  file-producing tools work with no configuration.
+
+- `py.typed`, so a type checker no longer ignores every annotation in the
+  package.
+- Tests that check the documentation against the package: every documented
+  import resolves, every file path named in prose exists, and a list of names
+  that were promised but never existed cannot reappear.
+
+### Changed
+
+- Published on PyPI as `agentino-framework`: `pip install agentino-framework`.
+  The `agentino` name there belongs to an unrelated project, so the
+  distribution carries a second name; the import name is unaffected and
+  remains `agentino`. Releases also attach wheels and sdists to the GitHub
+  release, and are uploaded by Trusted Publishing rather than a stored token.
+- Licence changed from MIT to Apache-2.0. The repository previously declared
+  MIT in metadata with no licence file present.
+- `print_summary` now reports how many stages passed and prints `FAILED`
+  rather than `COMPLETE` when any stage failed.
+- CI runs `ruff check` and `ruff format --check`, covers Python 3.10 through
+  3.13, and builds the distribution with a `twine` metadata check.
+
+### Fixed
+
+- `builtin_tools` raised `NameError` instead of a readable message when
+  `httpx` was missing: the `ImportError` handler called `error_unavailable`
+  without importing it.
+- Task notifications dropped the notification body, showing only the
+  description.
+- `fetch_web_data` and `translate_text` read different environment variables
+  for the same endpoint and defaulted to a hardcoded private host.
+- Four standard tools imported modules belonging to the workspace runtime
+  built *on top of* this framework — `protocols` in three, and
+  `helpers.documents.branded_pdf` in `create_pdf`. A standalone install
+  had no such module, so `read_file`, `list_files` and file creation raised
+  ImportError. The dependency is now inverted: the host registers storage.
+- A tenant id of `..` traversed out of the storage root. Path segments that
+  are only dots are replaced, not just character-substituted.
+
+- `examples/hello.py` and `examples/booking_bot.py` called `agent.run(...)`
+  without awaiting it, so both printed a coroutine object and never reached a
+  model. The smallest example in the repository did not work.
+- `discover_tools_from_dir` is exported publicly but was annotated `Path` and
+  called `.is_dir()` directly, so the natural call with a string raised
+  `AttributeError`. Every caller inside the package passed a `Path`, which is
+  why it went unnoticed.
+- The transport package documented `pip install agentino[telegram]`, `[slack]`
+  and `[serve]`. None of those extras existed, so each of those commands
+  failed.
+- The README declared MIT while `LICENSE`, `NOTICE` and `pyproject` all
+  declare Apache-2.0 — the one statement that would have mattered to someone
+  deciding whether they could use this.
+- The README promised `Runner.run_sync`. There is no synchronous wrapper
+  anywhere; the core is async throughout.
+- `LLMClient`'s docstring listed `OPENAI_BASE_URL` as a fallback for the
+  endpoint. It is not read at all, so setting it silently did nothing.
+- `SECURITY.md` described the project as pre-1.0 at version 1.1.0, in the
+  section a reader consults to learn which releases are patched.
+- The README's layout omitted `tools/`, the built-in tools package.
+
+### Removed
+
+- `browse_web` and `crawl_page`. Both imported `helpers.crawler`, a module
+  belonging to a host application that has never existed in this package, so
+  they returned an error string on every call and no test covered them. The
+  `browser` extra goes with them.
+- An internal cross-repository planning document.
+- CI exclusions for two test files whose 30 tests pass.
+
+## [1.1.0] and earlier
+
+Released before this changelog was kept. See the git history.

agentino_framework-1.1.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md — Agentino
+
+Notes for coding agents (and humans) working in this repository.
+
+## What this is
+
+A lightweight Python agent framework — 88 modules, about 12,000 lines of
+code. An agent is a loop:
+send messages and tool schemas to an LLM; if it calls a tool, run the tool and
+loop; if it returns text, stop. Everything else here is in service of that.
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Commands
+
+```bash
+pytest tests/ -q                  # the suite CI runs
+ruff check src/ tests/            # lint — must be clean
+ruff format --check src/ tests/   # formatting — must be clean
+python -m build                   # build the wheel
+
+agentino chat                     # REPL
+agentino run agents.yml           # run agents from config
+agentino run agents.yml -m "hi"   # one-shot message
+agentino run agents.yml --gateway # multi-channel gateway
+```
+
+## Layout
+
+```
+src/agentino/
+├── core/         Agent, Runner, LLMClient, Tool, Message, Context, State, Session
+├── config/       YAML loaders for agents, pipelines, tools
+├── pipeline/     Pipeline and StagedPipeline (multi-stage flows with verdicts)
+├── safety/       GateManager, HookManager, sanitizers
+├── reliability/  retry and backoff, history compaction, the error taxonomy
+├── extras/       knowledge base, memory, audio, skills, usage tracking
+├── providers/    pluggable LLM backends
+├── scheduler/    CronScheduler and the JobStore protocol
+├── transport/    outbound channels — Telegram, Slack, WhatsApp, WebSocket
+├── workers/      fork_agent and make_spawn_tool for multi-agent work
+├── tools/std/    the standard tool catalogue
+└── cli/          REPL renderer and the JSON event emitter
+```
+
+`from agentino import ...` is the public API and is what `__all__` in
+`src/agentino/__init__.py` declares. Deeper paths such as
+`from agentino.safety.gates import GateManager` are how internal packages talk
+to each other; treat them as unstable.
+
+## Conventions that matter here
+
+- **The framework provides mechanisms, not policies.** Anything that encodes
+  one application's behaviour — prompt wording, thresholds, a specific tool's
+  name, a natural language — belongs to that application, not here. If you
+  find yourself adding a rule that only makes sense for one deployment, add a
+  seam instead and let config supply the rule.
+- **No hardcoded endpoints or credentials.** Configuration comes from the
+  environment; `agentino.tools.std._llm_env` resolves the LLM endpoint and is
+  the only place that should know a default host.
+- **Tests come with the change.** A bug fix without a test that fails before
+  it is not finished.
+- **Lint is enforced.** CI runs `ruff check` and `ruff format --check`, so a
+  formatting argument is never worth having.
+
+## Releasing
+
+Version lives in `pyproject.toml`. The distribution is published as
+`agentino-framework` because the `agentino` name on PyPI belongs to an
+unrelated project; the import name is unaffected.

agentino_framework-1.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+## Our pledge
+
+We want participation in this project to be a harassment-free experience for
+everyone, whatever their age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Things that help:
+
+- being welcoming and respectful of differing viewpoints
+- accepting constructive criticism gracefully
+- focusing on what is best for the project
+- showing empathy toward other people
+
+Things that are not acceptable:
+
+- sexualised language or imagery, and unwelcome sexual attention
+- trolling, insults, derogatory comments, and personal or political attacks
+- public or private harassment
+- publishing someone's private information without explicit permission
+
+## Enforcement
+
+Report unacceptable behaviour by contacting the maintainer,
+[@islavutin-oss](https://github.com/islavutin-oss), through a GitHub private message
+or a private security advisory on this repository. All reports are reviewed
+and investigated, and will be kept confidential.
+
+Maintainers may remove comments, commits, code, issues and other
+contributions that violate this Code of Conduct, and may ban contributors
+temporarily or permanently for behaviour they judge inappropriate,
+threatening, offensive or harmful.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 1.4.

agentino_framework-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Agentino
+
+Thanks for taking the time. This is a small project, so the process is short.
+
+## Before you start
+
+For anything beyond a bug fix or a typo, **open an issue first**. It is much
+less painful to disagree about an approach in an issue than in a finished
+pull request.
+
+## Getting set up
+
+```bash
+git clone https://github.com/islavutin-oss/agentino.git
+cd agentino
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Run the tests and the linter:
+
+```bash
+pytest tests/ -q
+ruff check .
+ruff format --check .
+```
+
+CI runs exactly these, on Python 3.10 through 3.13.
+
+## What a good pull request looks like
+
+- **One change per pull request.** Unrelated fixes bundled together are hard
+  to review and harder to revert.
+- **Tests come with the change.** A bug fix should include a test that fails
+  before it and passes after.
+- **The suite is green.** Not "green except for a flaky one" — if something
+  is flaky, that is worth an issue of its own.
+- **Commit messages say what changed and why.** The subject line is
+  imperative and under about 72 characters; the body explains the reasoning
+  a reviewer cannot get from the diff.
+
+We use [Conventional Commits](https://www.conventionalcommits.org) prefixes:
+`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`.
+
+## Style
+
+The linter settles formatting arguments, so there is nothing to debate:
+`ruff format` owns line width, `ruff check` owns the rest. Type hints on
+public functions. Comments should explain why something is the way it is —
+the code already says what it does.
+
+## Licensing
+
+Contributions are accepted under the [Apache License 2.0](LICENSE), the same
+licence the project ships under. There is no CLA.

agentino_framework-1.1.0/DESIGN.md

@@ -0,0 +1,209 @@
+# Design Document
+
+## Vision
+
+Lightweight Python agent framework. YAML config → agents → run.
+
+Apache-2.0 licensed. Provider-agnostic. Core deps: httpx + pyyaml.
+
+## Core Principle
+
+**An agent is a loop.** Send messages + tools to an LLM. If the LLM calls a tool, execute it and loop. If the LLM returns text, you're done.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Layer 4: Transport                         │
+│  Telegram, Slack, WhatsApp, WebSocket       │
+├─────────────────────────────────────────────┤
+│  Layer 3: Orchestration                     │
+│  StagedPipeline, RouterPipeline, Parallel   │
+├─────────────────────────────────────────────┤
+│  Layer 2: Persistence                       │
+│  Session (JSONL), KnowledgeBase (TF-IDF +   │
+│  dense embeddings, SQLite cache)            │
+├─────────────────────────────────────────────┤
+│  Layer 1: Core                              │
+│  Agent, @tool, LLMClient, Config, Events    │
+└─────────────────────────────────────────────┘
+```
+
+Each layer independently usable. All layers optional except Core.
+
+## Config-Driven Agents
+
+```yaml
+# agents.yml
+providers:
+  router:
+    base_url: https://router.example.com/v1
+    api_key: ${AGENTINO_API_KEY}
+    provider: openai-codex
+
+agents:
+  coder:
+    model: router/gpt-5.4-codex
+    soul: ./SOUL.md
+    tools_dir: ./tools
+    tools: [read_file, write_file, shell, grep, stage_verdict]
+    temperature: 0.3
+    max_turns: 50
+
+gateway:
+  slack:
+    bot_token: ${SLACK_BOT_TOKEN}
+    app_token: ${SLACK_APP_TOKEN}
+    agent: coder
+```
+
+`load_config("agents.yml")` auto-detects `stages.yml` → creates StagedPipeline.
+
+## Agent Pattern
+
+```
+my-agent/
+├── SOUL.md          # identity + rules
+├── agents.yml       # model, tools, provider config
+├── stages.yml       # pipeline stages (optional)
+└── tools/           # custom tools (optional)
+```
+
+## Staged Pipeline
+
+Multi-stage execution with deterministic control flow:
+
+```yaml
+# stages.yml
+global_max_cycles: 20
+
+stages:
+  - name: IMPLEMENT
+    prompt: "Implement the plan..."
+    verdict_tool: stage_verdict
+    repeatable: true
+    on_fail: retry
+
+  - name: TEST
+    prompt: "Run tests..."
+    verdict_tool: stage_verdict
+    repeatable: true
+    on_fail: IMPLEMENT    # jump back on failure
+```
+
+- `verdict_tool` — structured ACCEPT/REJECT/FAIL signals
+- `repeatable` + `max_cycles` — retry stages
+- `on_fail: "STAGE_NAME"` — jump to named stage (loops)
+- `global_max_cycles` — hard budget
+- Fresh Agent context per stage
+- `on_event` callback for all pipeline events
+
+## Router Pipeline
+
+LLM-based intent classification → route to specialist agents:
+
+```yaml
+pipeline:
+  type: router
+  router: classifier
+  routes:
+    support: support_agent
+    billing: billing_agent
+  default: support
+```
+
+## Message Hook
+
+App-level intent routing:
+
+```yaml
+message_hook: my_module    # loads my_module.classify_and_route
+```
+
+`async (runner, agent, message, session) -> str | None`
+Return str = reply (skip pipeline). Return None = run pipeline.
+
+## Built-in Tools
+
+`shell`, `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, `search_files`, `stage_verdict`
+
+Shell timeout: `AGENTINO_SHELL_TIMEOUT` env var (default: no limit).
+
+## Knowledge Base
+
+Hybrid TF-IDF + dense embeddings. Auto-indexed from `.agentino/`.
+Tools: `search_knowledge`, `save_knowledge`, `delete_knowledge`.
+
+## Gateway
+
+Single process, multiple channels: Telegram, Slack, WhatsApp, WebSocket.
+
+```
+agentino run agents.yml --gateway
+```
+
+## File Layout
+
+```
+src/agentino/           ~12,000 LOC
+├── agent.py            Core loop + resilience
+├── tool.py             @tool decorator, schema gen
+├── llm.py              OpenAI-compatible client
+├── config.py           YAML loader, auto-detect stages.yml
+├── staged.py           StagedPipeline
+├── pipeline.py         RouterPipeline, sequence, parallel
+├── runner.py           Runner, message_hook, HTTP, REPL
+├── cli_renderer.py     Terminal rendering
+├── builtin_tools.py    shell, read_file, grep, etc.
+├── knowledge.py        Hybrid search KB
+├── session.py          JSONL persistence
+├── resilience.py       Retry, compaction, truncation
+├── message.py          Message, ToolCall, Event
+├── auth.py             Multi-provider auth
+├── context.py          Thread-local context
+├── spawn.py            Subagent spawning
+├── audio.py            STT transcription
+├── usage.py            Token tracking
+└── transport/          Channel adapters
+    ├── gateway.py
+    ├── telegram.py
+    ├── slack.py
+    ├── websocket.py
+    ├── webhook.py
+    └── whatsapp.py
+```
+
+27 test files. Python >=3.10.
+
+## Dependencies
+
+| Install | Adds |
+|---------|------|
+| `pip install agentino` | httpx, pyyaml |
+| `agentino[memory]` | + numpy |
+| `agentino[telegram]` | + aiogram |
+| `agentino[slack]` | + slack-bolt, aiohttp |
+| `agentino[serve]` | + uvicorn, starlette |
+| `agentino[all]` | everything |
+
+## Design Decisions
+
+- YAML-only config (see ADR-003)
+- OpenAI-compatible API (Codex, OpenAI, Anthropic, any endpoint)
+- Async-first architecture (see ADR-001)
+- Tool execution chain: validate → permission → execute (see ADR-002)
+- FinalResult for deterministic structured outputs
+- JSONL sessions (see ADR-004)
+- Framework provides mechanisms, not policies — no app logic in core
+- stages.yml = pure pipeline config, app routing via message_hook
+
+## Architecture Decision Records
+
+See `docs/architecture/` for detailed ADRs on major design choices:
+
+| ADR | Title | Summary |
+|-----|-------|---------|
+| ADR-001 | Async-First | All core APIs are async for concurrent I/O efficiency |
+| ADR-002 | Tool Execution Chain | 3-stage validation → permission → execution pattern |
+| ADR-003 | YAML-Only | Single configuration format for simplicity |
+| ADR-004 | JSONL Sessions | Line-based conversation persistence for git-friendliness |