Metadata-Version: 2.4
Name: tiiny-sdk
Version: 0.2.0
Summary: A minimal agent CLI with provider abstraction, tool calling, and system prompt assembly.
License-Expression: MIT
Keywords: ai,agent,cli,llm,edge-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.51.0
Requires-Dist: prompt_toolkit>=3.0.47
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# tiiny-cli

`tiiny-cli` is a minimal agent runtime inspired by the architecture of `hermes-agent`, but intentionally scoped down to four core parts:

- agent loop
- provider abstraction
- tool calling
- system prompt construction

The goal of this first cut is to give you a small, readable foundation that you can extend without carrying the full complexity of Hermes.

## What is included

- A session-oriented `Agent` loop
- OpenAI-compatible provider adapter
- Tool registry with JSON-schema tool definitions
- Toolset-based filtering for session-scoped tool surfaces
- Minimal built-in tools for local development
- Minimal built-in tools for local development, including webpage fetch
- Skill discovery, loading, and management tools
- Hermes-style SOUL.md, AGENT.md, USER.md, and MEMORY.md support
- Layered system prompt builder
- JSON-backed session persistence with stable system prompt caching
- Streaming assistant output and live tool progress in the CLI
- CLI entrypoint for one-shot and interactive use

## Quick start

```bash
cd tiiny-cli
python -m venv .venv
source .venv/bin/activate
pip install -e .
export OPENAI_API_KEY=your_key
export OPENAI_API_URL=http://127.0.0.1:8000/v1
export TIINY_MODEL=gpt-4.1-mini

tiiny "List the files in the current directory"
```

Interactive mode:

```bash
tiiny
```

Configuration mode:

```bash
tiiny config
```

Running plain `tiiny` starts a fresh auto-generated session by default. Use `--session <name>` if you want to continue an existing session.

Inside interactive mode you can use:

- `/new` to start a fresh session with an auto-generated name
- `/new my-session` to switch to a specific new session name
- `/tasks` to list active background shell tasks
- `/stop` or `/stop all` to stop all active background shell tasks launched by this tiiny process
- `/stop <task_id>` to stop one active background shell task

Use a named session to preserve history across runs:

```bash
tiiny --session backend "inspect the current project"
tiiny --session backend "now summarize what you found"
```

Restrict the tool surface to specific toolsets:

```bash
tiiny --list-toolsets
tiiny --enable-toolset filesystem "read the README and summarize it"
tiiny --disable-toolset terminal "inspect the project structure safely"
```

Use `tiiny config` to manage persistent agent files and Tiiny home:

```bash
tiiny config
tiiny config home
tiiny config soul
tiiny config agent
tiiny config user
tiiny config memory
```

`tiiny config` lets you:

- change the base `tiiny-home` directory
- edit the contents of `SOUL.md`
- edit the contents of `AGENT.md`
- edit the contents of `USER.md`
- edit the contents of `MEMORY.md`

The CLI streams assistant text as it is generated and prints tool activity in between iterations, so interactive runs feel closer to Hermes instead of waiting for one final block response.

Interactive input uses `prompt_toolkit`, which gives much better editing behavior for Chinese and other wide-character input than plain `input()`.

Skills are stored under `~/.tiiny/skills` by default. Once the `skills` toolset is enabled, the agent can:

- list skills with `skills_list`
- load a skill with `skill_view`
- create or update skills with `skill_manage`

Tiiny also supports Hermes-style persona and memory files:

- `~/.tiiny/SOUL.md`: persistent agent identity and high-level behavior
- `~/.tiiny/AGENT.md`: stable operating instructions for future sessions
- `~/.tiiny/USER.md`: stable user preferences and workflow habits
- `~/.tiiny/MEMORY.md`: durable project/environment facts and conventions

On first startup, Tiiny bootstraps these files automatically if they do not exist yet.
The active `tiiny-home` directory is stored in `~/.tiiny/config.json` unless you override it with `TIINY_HOME`.

## Environment variables

- `OPENAI_API_KEY`: API key for the OpenAI-compatible provider
- `OPENAI_API_URL`: Preferred base URL variable for local or self-hosted OpenAI-compatible endpoints
- `OPENAI_BASE_URL`: Optional custom OpenAI-compatible base URL
- `TIINY_ENABLE_THINKING`: Whether to send `extra_body.chat_template_kwargs.enable_thinking` on model calls, default `true`
- `TIINY_MODEL`: Model name, default `gpt-4.1-mini`
- `TIINY_MAX_ITERATIONS`: Agent loop cap, default `12`
- `TIINY_SYSTEM_PROMPT`: Optional extra stable system prompt content
- `TIINY_EPHEMERAL_SYSTEM_PROMPT`: Optional per-run ephemeral prompt suffix
- `TIINY_ENABLED_TOOLSETS`: Comma-separated allowlist, for example `filesystem,terminal`
- `TIINY_DISABLED_TOOLSETS`: Comma-separated denylist
- `TIINY_SESSION_HOME`: Session storage directory, default `<tiiny_home>/sessions`
- `TIINY_SKILL_HOME`: Skill storage directory, default `<tiiny_home>/skills`
- `TIINY_HOME`: Base Tiiny home directory, default `~/.tiiny`
- `TIINY_SOUL_PATH`: Advanced override for `SOUL.md`, default `<tiiny_home>/SOUL.md`
- `TIINY_AGENT_PATH`: Advanced override for `AGENT.md`, default `<tiiny_home>/AGENT.md`
- `TIINY_USER_PATH`: Advanced override for `USER.md`, default `<tiiny_home>/USER.md`
- `TIINY_MEMORY_PATH`: Advanced override for `MEMORY.md`, default `<tiiny_home>/MEMORY.md`
- `TIINY_WEB_SEARCH_URL`: Override the default web search service endpoint

## Architecture

```text
CLI
  -> Agent
    -> SessionStore
    -> SkillStore
    -> MemoryStore
    -> PromptBuilder
    -> Provider
    -> ToolRegistry
      -> Built-in tool handlers
```

Key files:

- `src/tiiny_cli/agent.py`: main loop
- `src/tiiny_cli/session.py`: JSON-backed session persistence
- `src/tiiny_cli/memory.py`: SOUL.md, AGENT.md, USER.md, MEMORY.md storage and frozen prompt snapshots
- `src/tiiny_cli/skills.py`: local skill storage, metadata parsing, and prompt integration
- `src/tiiny_cli/prompt_builder.py`: system prompt assembly
- `src/tiiny_cli/providers/openai_compatible.py`: provider adapter
- `src/tiiny_cli/tools/registry.py`: schema registry and dispatch
- `src/tiiny_cli/tools/builtin.py`: starter tools
- `src/tiiny_cli/tools/memory.py`: persistent memory tool
- `src/tiiny_cli/tools/skills.py`: skill tools

## Built-in toolsets

- `filesystem`: `list_directory`, `read_file`, `write_file`
- `terminal`: `run_command`, `bash`, `process`, `detect_browser`
- `web`: `web_search`, `fetch_webpage`
- `memory`: `memory`
- `skills`: `skills_list`, `skill_view`, `skill_manage`

## Web Search And Fetch

Tiiny includes Hermes-inspired web search and fetch tools:

- `web_search`: query the configured search service and return candidate URLs
- `fetch_webpage`: fetch one or more public HTTP(S) pages, extract readable text, and optionally focus the result with a `query`

Recommended flow:

- call `web_search` first to discover relevant URLs
- call `fetch_webpage` on the most relevant results to inspect page content

Example:

```text
Use web_search with:
{
  "query": "OpenAI latest research",
  "topk": 5
}

Then use fetch_webpage with:
{
  "urls": ["https://example.com"],
  "query": "domain reserved example"
}
```

The tool blocks `localhost` and private-network addresses to avoid unsafe internal fetches.
The search endpoint defaults to `http://34.212.123.29:8002/api/retrieve` and can be overridden with `TIINY_WEB_SEARCH_URL`.

## Browser Detection

Tiiny includes a Hermes-inspired browser detection helper:

- `detect_browser`: detect Chrome-family browsers across macOS, Windows, and Linux

Use it when a workflow depends on a local browser being installed. This avoids false negatives from Linux-only checks like `which google-chrome` on macOS.

## SOUL And Memory Files

On first startup, Tiiny bootstraps the following files under `~/.tiiny` by default:

- `SOUL.md`: top-level identity
- `AGENT.md`: durable operating instructions
- `USER.md`: user preferences and working style
- `MEMORY.md`: durable facts about the environment or project

If you already have older files under `~/.tiiny/memories/`, Tiiny migrates them to the tiiny-home root automatically on startup.

If `SOUL.md` exists, Tiiny uses it as the top-level identity layer instead of the built-in default identity string.

`AGENT.md`, `USER.md`, and `MEMORY.md` are loaded as a frozen snapshot at session start and injected into the system prompt. Mid-session writes through the `memory` tool update the files on disk immediately, but they do not rewrite the current session prompt; the new snapshot is picked up the next time a fresh session starts.

Example layout:

```text
~/.tiiny/
  SOUL.md
  AGENT.md
  USER.md
  MEMORY.md
```

## Skill layout

Each skill lives in its own directory and contains a required `SKILL.md`.

```text
~/.tiiny/skills/
  my-skill/
    SKILL.md
    references/
    templates/
    scripts/
    assets/
```

Minimal `SKILL.md` format:

```md
---
name: my-skill
description: Short explanation of when to use this skill.
---

# My Skill

Step-by-step instructions go here.
```

## Notes

This is a starter architecture, not a production-hardening pass. The current built-in tools include file reads, file writes, directory listing, and shell command execution, so you should review and tighten permissions before wider use.

## Live CLI behavior

- Assistant text is streamed token-by-token when the provider supports OpenAI-compatible streaming.
- Tool calls are shown in a structured live activity feed with clearer visual separation.
- A lightweight spinner keeps the CLI feeling active between model/tool events.
- The `bash` tool is the direct shell-facing alias for terminal work; `run_command` remains available as a more generic name.
- `bash` and `run_command` can take `background=true`.
- The `process` tool can `list`, `status`, `wait`, `stop`, and `stop_all` background tasks.
- `/tasks`, `/stop all`, and `/stop <task_id>` control those background tasks from the interactive CLI.
