sparrow-agent 0.1.0__tar.gz

sparrow_agent-0.1.0/LICENSE

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

sparrow_agent-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: sparrow-agent
+Version: 0.1.0
+Summary: A small-but-complete agent harness: ReAct loop, tool injection, three-tier memory, restricted-expression panels. Zero heavy deps.
+Author: nikefd
+License: MIT
+Project-URL: Homepage, https://github.com/nikefd/sparrow
+Project-URL: Repository, https://github.com/nikefd/sparrow
+Keywords: agent,llm,react,tool-calling,deepseek,harness
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# 🐦 sparrow
+
+**A small-but-complete agent harness.** 麻雀虽小，五脏俱全。
+
+Bring your own tools and a system prompt; sparrow wires them into a ReAct loop
+with citations, three-tier memory, and a restricted-expression engine for safe
+computed panels. Stdlib-only core, zero heavy dependencies — no LangChain, no
+LangGraph.
+
+> [English](#english) · [中文](#中文)
+
+---
+
+## English
+
+### Why sparrow
+
+Most agent frameworks are big. sparrow is the opposite: a single readable
+package you can fully understand in an afternoon, yet it has all the organs of a
+real agent:
+
+- **ReAct tool loop** — the model decides *what* it needs; deterministic code
+  decides *how* to get it.
+- **Tool injection** — the engine assumes nothing about your domain. You inject
+  plain functions as tools; finance, news, weather — all the same engine.
+- **Three-tier memory** — conversations, materialized panels, and an append-only
+  journal, all in one SQLite file, physically isolated from your business data.
+- **LLM emits declarations, not code** — even custom panel columns are a
+  *restricted expression* (AST allowlist: field names + numbers + arithmetic),
+  so the model can compose derived metrics but never run arbitrary code.
+- **Citations by construction** — every tool result carries a `source`; final
+  answers collect them automatically.
+
+### Install
+
+```bash
+pip install sparrow-agent          # import name is `sparrow`
+```
+
+The core engine is stdlib-only. Point it at any OpenAI-compatible endpoint
+(DeepSeek by default) via env or `configure()`:
+
+```bash
+export SPARROW_LLM_API_KEY=sk-...
+export SPARROW_LLM_BASE_URL=https://api.deepseek.com   # optional
+export SPARROW_LLM_MODEL=deepseek-chat                 # optional
+```
+
+### Quickstart
+
+```python
+from sparrow import tool, AgentConfig, Harness
+
+@tool(description="Get current weather", source="demo-weather")
+def get_weather(city: str) -> dict:
+    return {"city": city, "weather": "sunny, 24°C"}
+
+config = AgentConfig(
+    system_prompt="You are a weather assistant. Always call a tool; never invent weather.",
+    tools=[get_weather],
+)
+
+for event in Harness(config).run([{"role": "user", "content": "Weather in Beijing?"}]):
+    print(event)   # tool_call / tool_result / final / error
+```
+
+See [`examples/weather_agent.py`](examples/weather_agent.py) for a full run.
+
+### Memory & panels (optional)
+
+For dashboard-style apps, sparrow ships "panel as memory": the agent can persist
+a conversation insight as a live, declarative panel.
+
+```python
+from sparrow import Memory, AgentConfig, panel_tools
+
+mem = Memory("ui.db", transforms={"count": lambda d: {"value": len(next(iter(d.values()), []))}})
+
+config = AgentConfig(
+    system_prompt="...",
+    tools=[*my_query_tools, *panel_tools(mem)],   # adds create/archive/list_panels
+    recall_provider=mem.journal_summary_for_prompt,  # inject episodic recall
+)
+```
+
+Panels store *recipes* (a tool + transform/columns), not snapshots, so they
+recompute from live data every time. Custom table columns use the restricted
+expression engine:
+
+```python
+{"title": "Market Value", "expr": "current_price * shares"}   # safe
+{"title": "x", "expr": "__import__('os')"}                    # rejected
+```
+
+### Design principles
+
+1. **LLM decides *what*, deterministic code decides *how*.** The model only ever
+   emits declarations (which tool, which transform, which column expression);
+   real execution is plain Python. This prevents hallucinated data and confines
+   the model to a read-only, validated surface.
+2. **Read/write separation.** Query tools read your business data; write tools
+   only touch the agent's own memory db. The LLM can shape presentation, never
+   the underlying truth.
+3. **Memory covers every actor.** The journal records what the user did, what
+   the agent did, and what the system did — so the agent's worldview is complete.
+
+### Status
+
+`v0.1` — extracted from two production agents (a quant-trading assistant and an
+AI-frontier tracker) and generalized. API may still move before `1.0`.
+
+MIT licensed.
+
+---
+
+## 中文
+
+### 为什么是 sparrow
+
+大多数 agent 框架都很重。sparrow 反其道而行：一个一下午就能读透的单包，却五脏俱全：
+
+- **ReAct 工具循环** —— LLM 决定「要什么」，确定性代码决定「怎么做」。
+- **工具注入** —— 引擎对业务零假设。你把普通函数注入成工具；金融、新闻、天气，同一套引擎。
+- **三层记忆** —— 对话、物化面板、append-only 流水，同一个 SQLite 文件，与业务数据物理隔离。
+- **LLM 只产声明，不产代码** —— 连自定义面板列都是「受限表达式」（AST 白名单：字段名+数字+四则运算），模型能组合衍生指标，却碰不到任意代码。
+- **天生带溯源** —— 每个工具结果带 `source`，最终答案自动收集成 citations。
+
+### 安装
+
+```bash
+pip install sparrow-agent          # import 名是 sparrow
+```
+
+核心引擎零三方依赖（仅 stdlib）。指向任意 OpenAI 兼容端点（默认 DeepSeek）：
+
+```bash
+export SPARROW_LLM_API_KEY=sk-...
+```
+
+### 快速开始
+
+```python
+from sparrow import tool, AgentConfig, Harness
+
+@tool(description="查天气", source="demo")
+def get_weather(city: str) -> dict:
+    return {"city": city, "weather": "晴, 24°C"}
+
+config = AgentConfig(
+    system_prompt="你是天气助手，必须调工具拿真实数据，绝不编造。",
+    tools=[get_weather],
+)
+
+for event in Harness(config).run([{"role": "user", "content": "北京天气？"}]):
+    print(event)
+```
+
+### 设计理念
+
+1. **LLM 决定「要什么」，确定性代码决定「怎么做」。** 模型永远只产声明（用哪个工具、哪种 transform、哪个列表达式），真正执行都是普通代码。防幻觉，且把模型限制在只读、已校验的边界内。
+2. **读写分级。** 查询工具读业务数据，写工具只动 agent 自己的记忆库。LLM 能塑造呈现，永远碰不到底层真相。
+3. **记忆覆盖所有 actor。** 流水记录人做的、AI 做的、系统做的——agent 的世界观才完整。
+
+### 状态
+
+`v0.1` —— 从两个生产 agent（A股量化助手 + AI 前沿追踪）抽取并通用化而来。`1.0` 前 API 可能调整。
+
+MIT 协议。

sparrow_agent-0.1.0/README.md

@@ -0,0 +1,168 @@
+# 🐦 sparrow
+
+**A small-but-complete agent harness.** 麻雀虽小，五脏俱全。
+
+Bring your own tools and a system prompt; sparrow wires them into a ReAct loop
+with citations, three-tier memory, and a restricted-expression engine for safe
+computed panels. Stdlib-only core, zero heavy dependencies — no LangChain, no
+LangGraph.
+
+> [English](#english) · [中文](#中文)
+
+---
+
+## English
+
+### Why sparrow
+
+Most agent frameworks are big. sparrow is the opposite: a single readable
+package you can fully understand in an afternoon, yet it has all the organs of a
+real agent:
+
+- **ReAct tool loop** — the model decides *what* it needs; deterministic code
+  decides *how* to get it.
+- **Tool injection** — the engine assumes nothing about your domain. You inject
+  plain functions as tools; finance, news, weather — all the same engine.
+- **Three-tier memory** — conversations, materialized panels, and an append-only
+  journal, all in one SQLite file, physically isolated from your business data.
+- **LLM emits declarations, not code** — even custom panel columns are a
+  *restricted expression* (AST allowlist: field names + numbers + arithmetic),
+  so the model can compose derived metrics but never run arbitrary code.
+- **Citations by construction** — every tool result carries a `source`; final
+  answers collect them automatically.
+
+### Install
+
+```bash
+pip install sparrow-agent          # import name is `sparrow`
+```
+
+The core engine is stdlib-only. Point it at any OpenAI-compatible endpoint
+(DeepSeek by default) via env or `configure()`:
+
+```bash
+export SPARROW_LLM_API_KEY=sk-...
+export SPARROW_LLM_BASE_URL=https://api.deepseek.com   # optional
+export SPARROW_LLM_MODEL=deepseek-chat                 # optional
+```
+
+### Quickstart
+
+```python
+from sparrow import tool, AgentConfig, Harness
+
+@tool(description="Get current weather", source="demo-weather")
+def get_weather(city: str) -> dict:
+    return {"city": city, "weather": "sunny, 24°C"}
+
+config = AgentConfig(
+    system_prompt="You are a weather assistant. Always call a tool; never invent weather.",
+    tools=[get_weather],
+)
+
+for event in Harness(config).run([{"role": "user", "content": "Weather in Beijing?"}]):
+    print(event)   # tool_call / tool_result / final / error
+```
+
+See [`examples/weather_agent.py`](examples/weather_agent.py) for a full run.
+
+### Memory & panels (optional)
+
+For dashboard-style apps, sparrow ships "panel as memory": the agent can persist
+a conversation insight as a live, declarative panel.
+
+```python
+from sparrow import Memory, AgentConfig, panel_tools
+
+mem = Memory("ui.db", transforms={"count": lambda d: {"value": len(next(iter(d.values()), []))}})
+
+config = AgentConfig(
+    system_prompt="...",
+    tools=[*my_query_tools, *panel_tools(mem)],   # adds create/archive/list_panels
+    recall_provider=mem.journal_summary_for_prompt,  # inject episodic recall
+)
+```
+
+Panels store *recipes* (a tool + transform/columns), not snapshots, so they
+recompute from live data every time. Custom table columns use the restricted
+expression engine:
+
+```python
+{"title": "Market Value", "expr": "current_price * shares"}   # safe
+{"title": "x", "expr": "__import__('os')"}                    # rejected
+```
+
+### Design principles
+
+1. **LLM decides *what*, deterministic code decides *how*.** The model only ever
+   emits declarations (which tool, which transform, which column expression);
+   real execution is plain Python. This prevents hallucinated data and confines
+   the model to a read-only, validated surface.
+2. **Read/write separation.** Query tools read your business data; write tools
+   only touch the agent's own memory db. The LLM can shape presentation, never
+   the underlying truth.
+3. **Memory covers every actor.** The journal records what the user did, what
+   the agent did, and what the system did — so the agent's worldview is complete.
+
+### Status
+
+`v0.1` — extracted from two production agents (a quant-trading assistant and an
+AI-frontier tracker) and generalized. API may still move before `1.0`.
+
+MIT licensed.
+
+---
+
+## 中文
+
+### 为什么是 sparrow
+
+大多数 agent 框架都很重。sparrow 反其道而行：一个一下午就能读透的单包，却五脏俱全：
+
+- **ReAct 工具循环** —— LLM 决定「要什么」，确定性代码决定「怎么做」。
+- **工具注入** —— 引擎对业务零假设。你把普通函数注入成工具；金融、新闻、天气，同一套引擎。
+- **三层记忆** —— 对话、物化面板、append-only 流水，同一个 SQLite 文件，与业务数据物理隔离。
+- **LLM 只产声明，不产代码** —— 连自定义面板列都是「受限表达式」（AST 白名单：字段名+数字+四则运算），模型能组合衍生指标，却碰不到任意代码。
+- **天生带溯源** —— 每个工具结果带 `source`，最终答案自动收集成 citations。
+
+### 安装
+
+```bash
+pip install sparrow-agent          # import 名是 sparrow
+```
+
+核心引擎零三方依赖（仅 stdlib）。指向任意 OpenAI 兼容端点（默认 DeepSeek）：
+
+```bash
+export SPARROW_LLM_API_KEY=sk-...
+```
+
+### 快速开始
+
+```python
+from sparrow import tool, AgentConfig, Harness
+
+@tool(description="查天气", source="demo")
+def get_weather(city: str) -> dict:
+    return {"city": city, "weather": "晴, 24°C"}
+
+config = AgentConfig(
+    system_prompt="你是天气助手，必须调工具拿真实数据，绝不编造。",
+    tools=[get_weather],
+)
+
+for event in Harness(config).run([{"role": "user", "content": "北京天气？"}]):
+    print(event)
+```
+
+### 设计理念
+
+1. **LLM 决定「要什么」，确定性代码决定「怎么做」。** 模型永远只产声明（用哪个工具、哪种 transform、哪个列表达式），真正执行都是普通代码。防幻觉，且把模型限制在只读、已校验的边界内。
+2. **读写分级。** 查询工具读业务数据，写工具只动 agent 自己的记忆库。LLM 能塑造呈现，永远碰不到底层真相。
+3. **记忆覆盖所有 actor。** 流水记录人做的、AI 做的、系统做的——agent 的世界观才完整。
+
+### 状态
+
+`v0.1` —— 从两个生产 agent（A股量化助手 + AI 前沿追踪）抽取并通用化而来。`1.0` 前 API 可能调整。
+
+MIT 协议。

sparrow_agent-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "sparrow-agent"
+version = "0.1.0"
+description = "A small-but-complete agent harness: ReAct loop, tool injection, three-tier memory, restricted-expression panels. Zero heavy deps."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "nikefd" }]
+keywords = ["agent", "llm", "react", "tool-calling", "deepseek", "harness"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Core engine is stdlib-only (urllib/sqlite/ast). No runtime dependencies.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/nikefd/sparrow"
+Repository = "https://github.com/nikefd/sparrow"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sparrow*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

sparrow_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sparrow_agent-0.1.0/sparrow/__init__.py

@@ -0,0 +1,74 @@
+"""sparrow — a small-but-complete agent harness.
+
+麻雀虽小，五脏俱全 / Small bird, all the organs.
+
+Bring your own tools and a system prompt; sparrow wires them into a ReAct loop
+with citations, three-tier memory (conversations / panels / journal), and a
+restricted-expression engine for safe computed columns.
+
+    from sparrow import tool, AgentConfig, Harness
+
+    @tool(description="Echo back", source="demo")
+    def echo(text: str) -> dict:
+        return {"text": text}
+
+    cfg = AgentConfig(system_prompt="You are a helpful assistant.", tools=[echo])
+    for event in Harness(cfg).run([{"role": "user", "content": "hi"}]):
+        print(event)
+"""
+from .registry import AgentConfig, Tool, ToolRegistry, tool
+from .harness import Harness
+from .memory import Memory
+from .llm import chat, configure, LLMError
+from . import panel_data
+from .expr import safe_eval, is_safe_expr
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentConfig", "Tool", "ToolRegistry", "tool",
+    "Harness", "Memory",
+    "chat", "configure", "LLMError",
+    "panel_data", "safe_eval", "is_safe_expr",
+    "panel_tools",
+]
+
+
+def panel_tools(memory):
+    """Return the standard panel-management tools (create / archive / list) bound
+    to a :class:`~sparrow.memory.Memory`. Add them to your AgentConfig.tools to
+    give the agent "panel as memory" capabilities.
+    """
+    from .registry import tool as _tool
+
+    @_tool(name="create_panel", writes=True, source="ui.db: panels",
+           description="Persist a conversation insight as a dashboard panel. "
+                       "Only call after the user explicitly agrees.")
+    def create_panel(spec: dict = None, conversation_id: str = "") -> dict:
+        import json as _json
+        if isinstance(spec, str):
+            try:
+                spec = _json.loads(spec)
+            except (ValueError, TypeError):
+                return {"error": "spec must be an object"}
+        return memory.create_panel(spec, conversation_id=conversation_id)
+
+    @_tool(name="archive_panel", writes=True, source="ui.db: panels",
+           description="Archive a panel (reversible). Requires user confirmation.")
+    def archive_panel(id: str = "", conversation_id: str = "") -> dict:
+        return memory.archive_panel(id)
+
+    @_tool(name="list_panels", source="ui.db: panels",
+           description="List current dashboard panels.")
+    def list_panels(include_archived: bool = False) -> dict:
+        allp = memory.list_panels(include_archived=include_archived)
+        custom = [p for p in allp if p.get("kind") != "builtin"]
+        builtin = [p for p in allp if p.get("kind") == "builtin"]
+        return {
+            "custom_panels": [{"id": p["id"], "title": p["title"], "viz": p["viz"],
+                               "status": p["status"], "note": p.get("note", "")} for p in custom],
+            "builtin_panels": [{"title": p["title"], "tab": p.get("tab", "")} for p in builtin],
+            "summary": f"{len(custom)} custom + {len(builtin)} builtin panels",
+        }
+
+    return [create_panel, archive_panel, list_panels]

sparrow_agent-0.1.0/sparrow/expr.py

@@ -0,0 +1,101 @@
+"""Restricted expression evaluation — for computed columns in table panels.
+
+Security boundary: only "field names + numbers + arithmetic + parentheses" are
+allowed; function calls, attribute access, subscripts, comprehensions, etc. are
+all forbidden. The LLM may *declare* a column's formula (e.g.
+``current_price * shares``) but can never execute arbitrary code — consistent
+with sparrow's guiding principle: the LLM emits declarations, not code.
+
+Usage:
+    safe_eval('current_price * shares', {'current_price': 10, 'shares': 100})  # -> 1000
+    safe_eval('(current_price - avg_cost) / avg_cost * 100', row)             # P&L %
+"""
+import ast
+import operator
+
+_BINOPS = {
+    ast.Add: operator.add, ast.Sub: operator.sub,
+    ast.Mult: operator.mul, ast.Div: operator.truediv,
+    ast.Mod: operator.mod, ast.Pow: operator.pow,
+    ast.FloorDiv: operator.floordiv,
+}
+_UNARYOPS = {ast.UAdd: operator.pos, ast.USub: operator.neg}
+
+
+class ExprError(Exception):
+    pass
+
+
+def _to_num(v):
+    """Coerce a field value to a number; non-numeric values (e.g. string names)
+    are returned as-is so text columns keep working."""
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, (int, float)):
+        return v
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return v
+
+
+def _eval_node(node, row):
+    if isinstance(node, ast.Expression):
+        return _eval_node(node.body, row)
+    # Field name
+    if isinstance(node, ast.Name):
+        if node.id not in row:
+            return 0  # missing field -> 0, so the whole column doesn't crash
+        return _to_num(row[node.id])
+    # Numeric / string constant
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, (int, float, str)):
+            return node.value
+        raise ExprError(f'unsupported constant: {node.value!r}')
+    # Binary operation
+    if isinstance(node, ast.BinOp):
+        op = _BINOPS.get(type(node.op))
+        if not op:
+            raise ExprError(f'unsupported operator: {type(node.op).__name__}')
+        left, right = _eval_node(node.left, row), _eval_node(node.right, row)
+        if not isinstance(left, (int, float)) or not isinstance(right, (int, float)):
+            return 0  # text in arithmetic -> safe fallback
+        try:
+            return op(left, right)
+        except ZeroDivisionError:
+            return 0
+    # Unary operation
+    if isinstance(node, ast.UnaryOp):
+        op = _UNARYOPS.get(type(node.op))
+        if not op:
+            raise ExprError(f'unsupported unary op: {type(node.op).__name__}')
+        return op(_eval_node(node.operand, row))
+    raise ExprError(f'disallowed expression node: {type(node).__name__}')
+
+
+def safe_eval(expr, row):
+    """Evaluate an expression against a single row. Returns None on failure
+    (the render layer shows a placeholder)."""
+    try:
+        tree = ast.parse(str(expr), mode='eval')
+        val = _eval_node(tree, row)
+        if isinstance(val, float):
+            return round(val, 2)
+        return val
+    except (ExprError, SyntaxError, ValueError):
+        return None
+
+
+def is_safe_expr(expr):
+    """Static check: does the expression contain only whitelisted nodes?
+    (used when validating a panel spec at creation time)."""
+    try:
+        tree = ast.parse(str(expr), mode='eval')
+    except SyntaxError:
+        return False
+    allowed = (ast.Expression, ast.BinOp, ast.UnaryOp, ast.Name, ast.Constant,
+               ast.Load) + tuple(_BINOPS) + tuple(_UNARYOPS)
+    for n in ast.walk(tree):
+        if not isinstance(n, allowed):
+            return False
+    return True