zeline 0.3.1__tar.gz

zeline-0.3.1/LICENSE

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

zeline-0.3.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include zeline/SOUL.md
+recursive-include zeline/skills *
+recursive-include zeline/zenith_tools *
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude __pycache__/*

zeline-0.3.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: zeline
+Version: 0.3.1
+Summary: Zeline — an open-source agentic AI framework by Zerolinear.
+Author: Mahesa F. Ferdinand
+License: MIT License
+        
+        Copyright (c) 2026 Mahesa F. Ferdinand
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Mftrferdinand/Zeline
+Project-URL: Documentation, https://github.com/Mftrferdinand/Zeline/blob/main/docs/installation.md
+Project-URL: Repository, https://github.com/Mftrferdinand/Zeline
+Project-URL: Issues, https://github.com/Mftrferdinand/Zeline/issues
+Project-URL: Changelog, https://github.com/Mftrferdinand/Zeline/blob/main/CHANGELOG.md
+Keywords: ai,agent,llm,telegram,whatsapp,openai-compatible
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests[socks]>=2.28
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pypdf>=4.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/zerolinear-logo.png" alt="Zerolinear" width="760">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Mftrferdinand/Zeline/tree/main/docs"><img src="https://img.shields.io/badge/Docs-zeline.zerolinear.com-1D4ED8?style=flat&labelColor=334155"></a>
+  <a href="https://t.me/zerolinear"><img src="https://img.shields.io/badge/Community-0A84FF?style=flat&labelColor=334155&logo=telegram&logoColor=white"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-1D4ED8?style=flat&labelColor=334155"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Lang-EN-0A84FF?style=flat&labelColor=334155"></a>
+  <a href="docs/README.id.md"><img src="https://img.shields.io/badge/Lang-ID-1D4ED8?style=flat&labelColor=334155"></a>
+  <a href="docs/README.zh.md"><img src="https://img.shields.io/badge/Lang-中文-0A84FF?style=flat&labelColor=334155"></a>
+  <br>
+  <strong>— by Zerolinear, an AI research lab.</strong>
+</p>
+
+---
+
+# Zeline
+
+Zeline is an open-source agentic AI framework developed by **Zerolinear**. It's a flexible foundation for building AI agents that can reason, use tools, interact with external systems, and carry out complex, multi-step workflows.
+
+Rather than being tied to a single model, provider, or infrastructure, Zeline is built around flexibility. Connect your preferred AI models and OpenAI-compatible endpoints, configure providers, integrate tools, and extend the framework to fit how you want your agents to work — models and providers can be swapped without rebuilding the system, keeping the agent architecture portable and adaptable.
+
+Run it locally for development or deploy it to your own server or cloud, and connect it to the interfaces you use. The goal is to keep control in the developer's hands: your models, your tools, your infrastructure, your data. Open-source, model-agnostic, extensible, and developer-first.
+
+## Features
+
+- **Agent core** — an OpenAI-compatible agent loop with tool calling, plus an interactive CLI and one-shot queries
+- **Model-agnostic** — works with OpenAI, OpenRouter, vLLM, Ollama, and any OpenAI- or Anthropic-compatible API; swap model or provider without rebuilding
+- **Persistent memory** — long-term memory isolated per platform identity
+- **Session persistence** — conversation history stored in SQLite (`~/.zeline/sessions.db`), so it survives gateway restarts
+- **Skills** — reusable Markdown procedures loaded on demand; see the [Zenith skill index](zeline/skills/ZENITH_INDEX.md) for the full bundled catalog
+- **Messaging gateways** — Telegram (long polling, commands, attachments), WhatsApp (Baileys QR pairing), and an authenticated local HTTP webhook
+- **Built-in tools** — web search, web fetch, deep research, HTTP requests, file read/write/edit/search, image analysis, text-to-image generation, code execution, shell, and sub-agent delegation
+- **Lazy tool schemas** — the model is sent a small core of schemas plus a one-line summary of every other tool, and fetches full parameters on demand with `tool_search`. On the `full` profile that is 6,793 characters per request instead of 17,089 (60% less), without hiding any capability: names stay visible and a listed tool can be called directly. It engages only where the saving outweighs the extra round trip, so the public `safe` profile keeps sending everything; run `zeline toolsearch` for the numbers on your own tool set
+- **Real browser control** — the `browser` tool drives an installed Chromium/Chrome over the Chrome DevTools Protocol (open, click, type, read, screenshot), so JavaScript-rendered and logged-in pages are reachable where raw HTML fetching is not. No Playwright or Puppeteer dependency
+- **Scheduled jobs inside the gateway** — `zeline cron` runs interval or cron-expression jobs in the running gateway process, reusing its config, provider key, and workspace, and delivers results to the chat that owns the job
+- **Language-server intelligence** — `code_intel` asks a real LSP server for diagnostics, definitions, references, hover, and symbols; servers are discovered on PATH and never downloaded, falling back to the project linter when none is installed
+- **Operator extension points** — Python plugin hooks can audit, rewrite, or block any tool call before it runs, plain Python files can be loaded as `custom_*` tools, and local OpenAPI 3 documents become namespaced `api_*` tools without handwritten wrappers
+- **Nothing is silently lost** — oversized tool output is written to disk and replaced by a pointer with a head/tail preview, and conversation turns evicted to keep the context window bounded are appended to an on-disk transcript plus a deterministic digest (what you asked, which files were touched, where the archive lives) injected at the front of history. Both are recoverable with `read_file`, and neither costs a model call
+- **Undo** — writes and edits are snapshotted first; `zeline undo` lists and restores them
+- **Human-in-the-loop** — `ask_user` pauses the run to ask you one question, with tappable options on messaging gateways and a keyboard prompt in the CLI
+- **Format on write** — after the agent writes or edits a file, the project's installed formatter (ruff, gofmt, biome, prettier, rustfmt, shfmt, …) runs on it, so generated code matches your repo style; configurable per extension and never overwrites a failed write
+- **Sub-agents** — delegate a focused subtask to an isolated child agent that returns only its final summary, keeping the main context clean (depth-limited; owner profiles only)
+- **MCP client** — connect external MCP servers (stdio or HTTP) and expose their tools automatically
+- **Scoped tool profiles** — gate access per surface:
+  - `safe` — memory and public skills only; default for messaging gateways
+  - `workspace` — `safe` plus files inside the owner workspace
+  - `full` — `workspace` plus shell access; intended for the local owner CLI
+
+## Install
+
+**Requirements:** Python 3.10+. WhatsApp also needs Node.js 18+ and npm. POSIX
+platforms use a private Python environment; Windows uses a per-user package
+install. Neither requires root/Administrator access.
+
+### PyPI (recommended)
+
+```sh
+pip install zeline
+# or, in an isolated tool environment:
+uv tool install zeline
+```
+
+Then `zeline setup`. Zeline is on PyPI via Trusted Publishing (OIDC) — no API
+token stored in the repository, same verified artifacts as the release.
+
+### Termux, Linux, macOS, and iSH
+
+One line, and it needs no existing Python tooling — it provisions a private
+environment for you:
+
+```bash
+curl -fsSLO --proto '=https' --tlsv1.2 https://github.com/Mftrferdinand/Zeline/releases/download/v0.3.1/install.sh && bash install.sh
+```
+
+Then `zeline setup`. The installer downloads the versioned wheel and verifies it
+against `SHA256SUMS` itself before installing, so there is nothing to check by
+hand. On iSH, run `apk add bash curl python3` first.
+
+### Windows PowerShell
+
+```powershell
+iwr -UseBasicParsing https://github.com/Mftrferdinand/Zeline/releases/download/v0.3.1/install.ps1 -OutFile install.ps1; .\install.ps1
+```
+
+Then `zeline setup`.
+
+### npm (any platform with Node.js ≥ 18)
+
+If you already use npm, the wrapper does the same verified wheel install on
+first run — no `curl` or `iwr` needed:
+
+```sh
+npm install -g zeline
+zeline setup
+```
+
+The wrapper detects Python 3.10+ on your `PATH`, downloads the same versioned
+wheel and `SHA256SUMS` from the GitHub release, verifies the checksum, and
+installs into the same private runtime (`~/.local/share/zeline`). See
+[`README.npm.md`](README.npm.md) for details.
+
+### Verify the download independently (optional)
+
+The installer's own wheel check comes from the same release as the installer, so
+it proves integrity, not origin. For that, verify the release's build-provenance
+attestation with GitHub CLI — an independent signature chain:
+
+```bash
+gh attestation verify install.sh --repo Mftrferdinand/Zeline
+```
+
+See the complete [installation guide](docs/installation.md) for package
+prerequisites, platform limitations, checkout installs, updates, PATH fixes, and
+uninstall instructions.
+
+### Update
+
+One command on every platform — Termux, Linux, macOS, iSH, and Windows
+PowerShell:
+
+```bash
+zeline update
+```
+
+It fetches the latest release installer, verifies its SHA-256 before running it,
+and updates in place. Your config, sessions, memory, and private skills under
+`~/.zeline` are untouched. From a git checkout it rebuilds your local source
+instead.
+
+Check what you are on, and whether a release is waiting:
+
+```bash
+zeline version
+```
+
+Both are also available from Telegram, so a phone-only install never needs a
+shell: **`/version`** reports the installed build against the latest release, and
+**`/update`** performs the update. `/update` is owner-only and runs in a detached
+process — the gateway finishes in-flight work, stops, installs, and relaunches
+itself, with progress posted back to the chat. It refuses to run from a source
+checkout, where installing an uncommitted working tree would be a surprise.
+
+Then inspect the available integrations and health:
+
+```bash
+zeline tools list
+zeline mcp list
+zeline doctor
+zeline gateway list
+```
+
+## Use the CLI
+
+```bash
+zeline
+# or
+zeline chat -q "What can you do?"
+```
+
+## Connect a platform
+
+### Telegram
+
+Create a bot with [@BotFather](https://t.me/BotFather), then run:
+
+```bash
+zeline gateway setup telegram
+zeline gateway start
+```
+
+An empty allowlist makes the bot public. Public gateways always use the `safe` tool profile by default, so users cannot access host files or a shell.
+
+Telegram commands:
+
+```text
+/start, /help             Show command help
+/status                   Show provider and session status
+/models                   Show the active model
+/model <provider/model>   Persistently switch this installation's model
+/new                      Clear the current chat history
+/restart                  Restart the current Telegram chat session
+/stop                     Stop this Zeline gateway process
+/logs                     Show how to inspect gateway logs from the installation terminal
+```
+
+Attachments up to 256 KB are accepted for text, JSON, CSV, common code/config files, and ZIP archives containing safe text files. Text-based PDFs are extracted with `pypdf`. Images are accepted as attachment metadata; pixel analysis needs a vision-capable provider.
+
+### WhatsApp
+
+```bash
+zeline gateway setup whatsapp
+zeline gateway start
+```
+
+On first start, Zeline installs its Baileys bridge under `~/.zeline/wa-bridge/` and prints a QR code. In WhatsApp, open **Linked devices**, choose **Link a device**, then scan it.
+
+> This gateway uses WhatsApp multi-device through Baileys, not the Meta Business API. Make sure your use complies with WhatsApp policies.
+
+### HTTP webhook
+
+```bash
+zeline gateway enable webhook
+zeline gateway start
+```
+
+The default listener is `127.0.0.1:8765`. It does not listen on the public internet.
+
+```bash
+curl http://127.0.0.1:8765/health
+
+curl -X POST http://127.0.0.1:8765/message \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_WEBHOOK_TOKEN' \
+  -d '{"chat_id":"demo-user","text":"Hello Zeline"}'
+```
+
+Show masked configuration with:
+
+```bash
+zeline config show
+```
+
+If you expose the webhook through a tunnel or reverse proxy, use HTTPS and keep token authentication enabled.
+
+## Command reference
+
+```text
+zeline                         First run: gateway onboarding; later: local chat
+zeline chat -q "..."           Send one query after gateway + model setup
+zeline setup                   First run: gateway picker; later: setup center
+zeline setup <section>         Configure gateway|model|tools|integrations|agent
+zeline model                   Detect protocol, fetch models, and choose one
+zeline tools list              List native tools, profiles, and enabled state
+zeline tools profile <name>    Set safe|workspace|full for the local CLI
+zeline tools enable|disable T  Toggle one native tool for new sessions
+zeline tools workspace <path>  Set the owner workspace root
+zeline tools openapi-add FILE  Install a local OpenAPI 3 YAML/JSON document
+zeline tools openapi           List parsed API operations and credential variable names
+zeline doctor                  Check dependencies and configuration
+zeline config path             Print the configuration location
+zeline config show             Print configuration with masked secrets
+zeline gateway setup [name]    Configure telegram, whatsapp, or webhook
+zeline gateway enable <name>   Enable a gateway
+zeline gateway disable <name>  Disable a gateway
+zeline gateway list            Show configured gateways
+zeline gateway token webhook   Explicitly reveal a webhook token
+zeline gateway start           Run enabled gateways in the background
+zeline gateway stop            Stop the background gateway process
+zeline gateway status          Show background gateway status
+zeline gateway log             Print gateway logs
+zeline gateway run             Run enabled gateways in the foreground
+zeline skills                  List installed skills (catalog: zeline/skills/ZENITH_INDEX.md)
+zeline memory                  Print local CLI memory
+```
+
+On first launch, Zeline requires one gateway selected from an arrow-key picker:
+Telegram, WhatsApp, Webhook, or Cancel. It configures only the selected gateway,
+returns to the terminal, and directs the user to `zeline model`; local chat stays
+locked until both gateway and model setup are complete.
+
+During model setup, Zeline detects OpenAI-compatible or Anthropic APIs,
+queries the provider model endpoint, and shows a numbered picker. Secret input
+renders one `*` per character while the real API key stays hidden. If a provider
+cannot list models, Zeline requires an explicit model ID instead of accepting a
+placeholder.
+
+Zeline can safely describe its active model, provider URL, protocol, tool profile,
+and available tools through `runtime_info` and the bundled `self-analysis` skill.
+API keys and gateway tokens are never included.
+
+## Security
+
+- Keep `~/.zeline/`, `.env`, provider keys, and bot tokens out of Git.
+- OpenAPI credentials are read only from `~/.zeline/.env` (`ZELINE_OPENAPI_<FILE>_<SCHEME>`), never exposed in model schemas, and loaded only for `workspace`/`full` profiles.
+- Gateway users receive the `safe` profile by default.
+- Webhooks require a secret token and bind to loopback by default.
+- Memory is namespaced by platform identity, for example `telegram:123` or `webhook:alice`.
+- The WhatsApp bridge uses a random runtime token between Python and Node.
+- The repository enables secret scanning, push protection, Dependabot, CodeQL, and dependency review.
+
+See [SECURITY.md](SECURITY.md) for reporting guidance.
+
+## Extend it
+
+Custom Python tools, plugin hooks that can audit or block any tool call, local
+OpenAPI documents as tools, and MCP servers all work without changing the
+package. See [docs/extending.md](docs/extending.md).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+ruff check zeline tests
+python3 -m pip wheel --no-deps --wheel-dir dist .
+```
+
+CI runs `unittest`, not `pytest`.
+
+**Contributions are welcome, and you do not need write access here.** Fork,
+branch, and open a pull request against `main`; it runs the same CI matrix the
+maintainer's does — Linux, Windows, macOS, and both installers:
+
+```bash
+gh repo fork Mftrferdinand/Zeline --clone --remote
+cd Zeline && git checkout -b fix/short-description
+git push -u origin fix/short-description
+gh pr create --repo Mftrferdinand/Zeline --base main
+```
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the full flow, what each CI job proves,
+and where things live. Issues labelled
+[good first issue](https://github.com/Mftrferdinand/Zeline/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+are scoped small on purpose. [CHANGELOG.md](CHANGELOG.md) records every release
+with links to its pull requests.
+
+## Roadmap
+
+- Service integration for systemd and Termux:Boot
+- More messaging adapters
+- Richer interfaces on top of the app gateway
+- Promoting more ruff rules into the blocking lint gate
+
+## License
+
+MIT © 2026 Mftrferdinand