fj-ai 0.1.0__tar.gz

fj_ai-0.1.0/.gitignore

@@ -0,0 +1,215 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+# fj-ai commits uv.lock for reproducible CLI installs.
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

fj_ai-0.1.0/LICENSE

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

fj_ai-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: fj-ai
+Version: 0.1.0
+Summary: fj — one-shot CLI coding agent powered by soothe-nano
+Project-URL: Homepage, https://github.com/caesar0301/fj-ai
+Project-URL: Repository, https://github.com/caesar0301/fj-ai
+Project-URL: Issues, https://github.com/caesar0301/fj-ai/issues
+Author: Xiaming Chen
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,coding-agent,fj,nano,soothe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.11
+Requires-Dist: soothe-nano<1.0.0,>=0.9.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fj
+
+**fj** is a one-shot coding-agent CLI. Everything after the command is the query:
+
+```bash
+fj who is your name
+fj 修改这个文件。
+fj explain the auth flow in this repo
+```
+
+It embeds [soothe-nano](https://github.com/mirasoth/soothe-nano) — a full coding CoreAgent (tools, skills, MCP, subagents, progressive loading) — with **default SQLite** persistence and config at **`~/.soothe/config/nano.yml`**.
+
+> **fj-ai** is the Python package name; the agent runtime is **soothe-nano**. This README documents both the CLI and the agent capabilities you get underneath.
+
+## Quick start
+
+### 1. Install
+
+```bash
+pip install fj-ai
+# or
+uv tool install fj-ai
+```
+
+Requires Python 3.11+.
+
+### 2. Minimal config (no external SaaS)
+
+Copy the example and point it at a **local** OpenAI-compatible server (Ollama, LM Studio, vLLM, …). No Tavily, Langfuse, Postgres, or browser stack required.
+
+```bash
+mkdir -p ~/.soothe/config
+cp nano.yml ~/.soothe/config/nano.yml
+# or run without installing into ~/.soothe:
+#   fj -c ./nano.yml who are you
+```
+
+The repo-root [`nano.yml`](nano.yml) is a validated minimal profile: local OpenAI-compatible provider (Ollama), SQLite, search/research/browser subagents off.
+
+Start Ollama (or your local server), pull a model, then:
+
+```bash
+fj who are you
+fj list Python files in this directory
+```
+
+**Zero-config alternative** (cloud API, still no extra services):
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional: export OPENAI_BASE_URL=https://api.openai.com/v1
+fj summarize README.md
+```
+
+If `~/.soothe/config/nano.yml` is missing, soothe-nano bootstraps from `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
+
+### 3. What fj sets up for you
+
+| Concern | Default |
+|--------|---------|
+| Config | `~/.soothe/config/nano.yml` (`SOOTHE_HOME` overrides home) |
+| Checkpoints | SQLite at `~/.soothe/data/soothe_checkpoints.db` |
+| Workspace | Current working directory (`SOOTHE_WORKSPACE`) |
+| Output | Ephemeral progress on stdout line 1; final answer only when done |
+
+## Usage
+
+```text
+fj [options] [--] <query...>
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-c PATH` / `--config` | Alternate `nano.yml` |
+| `-t ID` / `--thread` | Reuse a LangGraph thread id (multi-turn via sqlite) |
+| `-w DIR` / `--workspace` | Workspace root for file/shell tools |
+| `--no-stream` | Same final-only answer (progress still shown on a TTY) |
+| `-v` / `--verbose` | Also mirror tool/custom events on stderr |
+| `-V` / `--version` | Version |
+| `--` | Force remaining argv into the query (including leading `-`) |
+
+Examples:
+
+```bash
+fj who is your name
+fj 修改这个文件。
+fj -v refactor the CLI parser to support Unicode
+fj --thread demo-1 continue from last turn: what files did you touch?
+fj -w ~/code/myapp find TODO comments
+```
+
+## Add skills
+
+Skills are folders with a `SKILL.md` (frontmatter + instructions). Point nano at them in `nano.yml`:
+
+```yaml
+skills:
+  - ~/.soothe/skills/my-reviewer
+  - ./skills/deploy
+```
+
+Example skill layout:
+
+```text
+~/.soothe/skills/my-reviewer/
+  SKILL.md
+```
+
+```markdown
+---
+name: my-reviewer
+description: Review Python PRs for style and security
+---
+
+# Reviewer
+
+When asked to review code, check for ...
+```
+
+**Progressive skills** (on by default): the agent keeps a compact catalog in context and loads full skill bodies on demand via `search_skills` / `invoke_skill`, with optional intent prefetch on cold threads. Tune under `progressive_skills:` in `nano.yml` (budget %, core skills, semantic search).
+
+## Add MCP servers
+
+MCP is opt-in. Either enable builtins or declare servers:
+
+```yaml
+# Builtin names (playwright, github, slack, postgres, gdrive, …)
+mcp_builtins:
+  - playwright
+
+# Or explicit servers (stdio / SSE / HTTP / websocket)
+mcp_servers:
+  - name: filesystem
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    defer: true          # progressive: tools listed, activated when needed
+    enabled: true
+```
+
+**Progressive MCP**: with `defer: true` (default), MCP tools are not dumped into the full tool array; the agent discovers and activates them as needed within a listing budget (`progressive_mcp:`).
+
+## Agent features (soothe-nano / fj-ai)
+
+fj is a thin CLI; the agent is **soothe-nano**, built on **soothe-deepagents** + **soothe-sdk**.
+
+### Progressive loading
+
+| Layer | Behavior |
+|-------|----------|
+| **Tools** | Core tools bound at startup; deferred tools discovered via `search_tools` (`progressive_tools`) |
+| **Skills** | Compact listings + `search_skills` / `invoke_skill`; intent prefetch on turn 0 |
+| **MCP** | Servers deferred by default; tools activated on demand |
+
+This keeps the context window small on every turn while still exposing a large capability surface.
+
+### Coding product defaults (beyond raw deepagents)
+
+- Builtin tool groups: shell/execution, file ops, HTTP, data, datetime, optional search
+- Ready subagents: planner, explorer, deep/academic research, browser-use (disable what you do not need)
+- Workspace scoping + path security policies
+- YAML / env config factory (`SootheConfig`)
+- SQLite-first persistence (Postgres optional in nano for larger deployments)
+- Middleware: context limits, tool timeouts, rate-limit retries, edit coalescing, role routing
+
+### Optimizations inspired by / layered on deepagents
+
+deepagents provides the harness (filesystem, shell, todos, subagents, context management). soothe-nano adds production-shaped defaults and progressive discovery so a coding agent can run in a repo without hand-wiring every tool and prompt. fj then packages that as a single argv → agent CLI with sqlite threads and cwd as workspace.
+
+## Compared to other agents
+
+| | **fj / soothe-nano** | **deepagents** | **OpenCode** | **Pi / pi-agent style** |
+|--|----------------------|----------------|--------------|-------------------------|
+| Shape | Library + thin CLI | Python harness library | Full TUI product (JS/TS) | Minimal / research-oriented agent loops |
+| Install surface | `pip install fj-ai` | `pip install deepagents` | Native/npm installer | Varies by project |
+| Config | `~/.soothe/config/nano.yml` | Code-first | App/project config | Usually code or light config |
+| Tools in context | Progressive (core + search) | Bring-your-own / harness set | Product tool surface | Often smaller fixed sets |
+| Skills | Progressive SKILL.md catalog | Base / custom | Product skills/plugins | Optional / custom |
+| MCP | First-class, deferred by default | Via adapters if you wire them | Product MCP support | Depends on fork |
+| Persistence | SQLite default under `~/.soothe/data` | Pluggable checkpointer | Product session store | Often ephemeral |
+| Subagents | Planner / research / browser ready | You define `task` agents | Product multi-agent UX | Usually single loop |
+| Best when | Scriptable coding agent in a repo | Custom harness control | Interactive daily coding IDE-in-terminal | Experiments, minimal loops |
+
+**vs deepagents:** use deepagents when you want the harness and full control; use fj/nano when you want coding defaults, progressive skills/tools/MCP, and a one-line CLI.
+
+**vs OpenCode:** OpenCode is a rich interactive TUI product. fj is intentionally small — argv in, streamed answer out — while sharing the same class of capabilities (tools, MCP, skills) through soothe-nano.
+
+**vs Pi-agent-style agents:** Pi-oriented agents emphasize lean loops and simplicity. fj trades a bit of that minimalism for progressive loading, workspace security, and sqlite threads so longer coding sessions stay practical.
+
+## Development
+
+```bash
+git clone https://github.com/caesar0301/fj-ai.git
+cd fj-ai
+make sync-dev
+make test
+make lint
+
+# Run against a local soothe-nano checkout (optional):
+#   uv add --editable ../soothe/packages/soothe-nano
+uv run fj who is your name
+```
+
+### Project layout
+
+```text
+src/fj_ai/
+  cli.py       # argv → query, asyncio entry
+  config.py    # ~/.soothe/config/nano.yml loader
+  agent.py     # create_nano_agent + sqlite checkpointer
+  stream.py    # stdout streaming
+nano.yml                 # minimal local config
+.github/workflows/
+  ci.yml
+  release.yml
+```
+
+### CI / release
+
+- **CI** — format, lint, unit tests on Python 3.11–3.13; build + `twine check`
+- **Release** — on GitHub Release publish (or workflow_dispatch), build and publish to PyPI (`UV_PUBLISH_TOKEN` or OIDC trusted publishing)
+
+## License
+
+MIT