shonku 0.1.0

Build, publish, and run AI agents as PyPI packages — wraps agno

shonku

Build, publish, and run AI agents as PyPI packages.

shonku is a declarative agent framework that wraps agno. Define agents with built-in tools, accept external tools at runtime, and publish them as installable packages.

Install

pip install shonku

Scaffold a new agent project

shonku init my-agent
cd my-agent
pip install -e '.[dev]'
pytest

This creates a ready-to-go project:

my-agent/
  src/my_agent/agent.py    <- your agent (ShonkuAgent subclass)
  tests/test_agent.py      <- tests (passing out of the box)
  pyproject.toml            <- package config (pip installable)
  README.md

Edit agent.py, add tools, publish to PyPI. Anyone can then pip install my-agent and run your agent with their own LLM creds.

Quick start

from shonku import ShonkuAgent, tool, LLMConfig

class MyAgent(ShonkuAgent):
    name = "my-agent"
    instructions = "You are a helpful assistant."
    required_tools = ["search"]  # caller must provide this

    @tool(description="Calculate a math expression")
    def calculate(self, expression: str) -> str:
        return str(eval(expression))

# Run with external tools + LLM creds passed at runtime
agent = MyAgent()
result = await agent.run(
    input="What is 42 * 17?",
    llm_config=LLMConfig(provider="groq", model="llama-3.3-70b-versatile", api_key="..."),
    tools=[search_tool],  # external tool passed by caller
)
print(result.content)

Key concepts

• ShonkuAgent -- subclass to define agents with @tool-decorated methods
• Tool merging -- agent's own tools + caller-provided tools merge at runtime
• Required tools -- declare what tools callers must provide
• LLMConfig -- LLM credentials passed at runtime, never stored in the agent
• Only bridge.py imports agno -- swap the runtime without touching agent code

Publish agents as PyPI packages

# myagent/agent.py
from shonku import ShonkuAgent, tool

class WeatherAgent(ShonkuAgent):
    name = "weather-agent"
    instructions = "Look up weather using the tools provided."
    required_tools = ["get_weather"]

    @tool(description="Format temperature")
    def format_temp(self, celsius: str) -> str:
        return f"{celsius}C / {float(celsius) * 9/5 + 32:.0f}F"

pip install myagent  # anyone can install it

# consumer code
from myagent import WeatherAgent

result = await WeatherAgent().run(
    input="Weather in Tokyo?",
    llm_config=my_config,
    tools=[my_weather_api_tool],
)

Supported LLM providers

All providers supported by agno work out of the box:

Provider	Config
Anthropic (Claude)	provider="anthropic"
OpenAI	provider="openai"
Groq	provider="groq"
Google Gemini	provider="gemini"
OpenRouter	provider="openrouter"

Built on agno

shonku is a thin, opinionated layer on top of agno (the open-source agent framework by Agno). agno provides the production-grade agent runtime, LLM provider integrations, and AgentOS for deploying agents at scale. shonku adds:

• Declarative agent definitions with @tool decorators
• Runtime tool injection (caller passes tools, agent doesn't hardcode them)
• Required tool validation
• shonku init scaffolding for publishable PyPI packages
• A single-file bridge (bridge.py) so agent code never imports agno directly

If you need the full agent runtime directly, use agno: pip install agno

Part of autoresearch-prompt-manager

shonku is the agent framework layer in the autoresearch-prompt-manager stack:

autoresearch-prompt-manager  (prompt CRUD, experiments, metrics)
  -> autoresearcher-shonku   (optimization agents)
  -> shonku                  (this package -- agent framework)
  -> agno                    (runtime -- https://agno.com)

Install via the parent package: pip install autoresearch-prompt-manager[shonku]

Contributing

For humans

1. Fork and clone autoresearch-prompt-manager
2. cd packages/shonku && pip install -e '.[dev]'
3. Make changes, run pytest, run ruff check src/
4. Submit a PR

For agents

Build agents with shonku and publish them as PyPI packages:

1. shonku init my-agent — scaffold a project
2. Edit src/my_agent/agent.py — add @tool methods, set required_tools
3. pip install -e '.[dev]' && pytest — verify
4. Publish to PyPI — anyone can pip install and run your agent

Key rules for agent authors:

• Never hardcode LLM creds — always passed via LLMConfig at runtime
• Never hardcode data access — receive tools from the caller
• Declare required_tools so callers know what to provide
• Keep agent code agno-free — only bridge.py imports agno

License

MIT