techtide-botkit 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- botkit/__init__.py +24 -0
- botkit/agent.py +449 -0
- botkit/errors.py +6 -0
- botkit/llm.py +111 -0
- botkit/mcp.py +268 -0
- botkit/memory/__init__.py +9 -0
- botkit/memory/base.py +56 -0
- botkit/memory/memory.py +109 -0
- botkit/memory/sqlite.py +115 -0
- botkit/memory/supabase.py +188 -0
- botkit/sandbox.py +139 -0
- botkit/security.py +98 -0
- botkit/server.py +199 -0
- botkit/skill.py +137 -0
- botkit/skills/coding/SKILL.md +10 -0
- botkit/skills/data-analysis/SKILL.md +9 -0
- botkit/skills/debugging/SKILL.md +10 -0
- botkit/skills/planning/SKILL.md +10 -0
- botkit/skills/presentations/SKILL.md +10 -0
- botkit/skills/research/SKILL.md +10 -0
- botkit/skills/spreadsheets/SKILL.md +10 -0
- botkit/skills/summarizing/SKILL.md +10 -0
- botkit/skills/verify-work/SKILL.md +10 -0
- botkit/skills/writing-documents/SKILL.md +10 -0
- botkit/tool.py +198 -0
- botkit/tools/__init__.py +42 -0
- botkit/tools/docs.py +195 -0
- botkit/tools/files.py +125 -0
- botkit/tools/shell.py +23 -0
- botkit/tools/util.py +65 -0
- botkit/tools/web.py +121 -0
- techtide_botkit-0.3.0.dist-info/METADATA +196 -0
- techtide_botkit-0.3.0.dist-info/RECORD +36 -0
- techtide_botkit-0.3.0.dist-info/WHEEL +5 -0
- techtide_botkit-0.3.0.dist-info/licenses/LICENSE +21 -0
- techtide_botkit-0.3.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: techtide-botkit
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: A chatbot/agent loop in a few lines, with optional tools, skills, memory (SQLite/Supabase/your own) and MCP.
|
|
5
|
+
Author: Ahmed
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/YOUR-USERNAME/botkit
|
|
8
|
+
Project-URL: Issues, https://github.com/YOUR-USERNAME/botkit/issues
|
|
9
|
+
Keywords: ai,agent,chatbot,llm,mcp,tools,memory
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: openai>=1.40
|
|
19
|
+
Provides-Extra: docs
|
|
20
|
+
Requires-Dist: python-docx; extra == "docs"
|
|
21
|
+
Requires-Dist: python-pptx; extra == "docs"
|
|
22
|
+
Requires-Dist: openpyxl; extra == "docs"
|
|
23
|
+
Provides-Extra: mcp
|
|
24
|
+
Requires-Dist: mcp>=1.2; extra == "mcp"
|
|
25
|
+
Provides-Extra: all
|
|
26
|
+
Requires-Dist: python-docx; extra == "all"
|
|
27
|
+
Requires-Dist: python-pptx; extra == "all"
|
|
28
|
+
Requires-Dist: openpyxl; extra == "all"
|
|
29
|
+
Requires-Dist: mcp>=1.2; extra == "all"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest; extra == "dev"
|
|
32
|
+
Requires-Dist: python-docx; extra == "dev"
|
|
33
|
+
Requires-Dist: python-pptx; extra == "dev"
|
|
34
|
+
Requires-Dist: openpyxl; extra == "dev"
|
|
35
|
+
Requires-Dist: mcp>=1.2; extra == "dev"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# botkit
|
|
39
|
+
|
|
40
|
+
A chatbot/agent loop as a library. By default you get **only the loop** (model call, tool-call handling, retries,
|
|
41
|
+
error handling). Everything else is a flag you switch on and wire where you like.
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from botkit import Agent
|
|
45
|
+
|
|
46
|
+
bot = Agent("groq:openai/gpt-oss-120b") # key from GROQ_API_KEY
|
|
47
|
+
print(bot.chat("hello")) # or bot.run() for a terminal chat
|
|
48
|
+
|
|
49
|
+
bot = Agent("groq:openai/gpt-oss-120b", tools=True, skills=True, memory="bot.db") # now with everything
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install -e . # the loop only (needs just `openai`)
|
|
56
|
+
pip install -e ".[docs]" # + Word/Excel/PowerPoint tools
|
|
57
|
+
pip install -e ".[mcp]" # + MCP servers
|
|
58
|
+
pip install -e ".[all]" # everything
|
|
59
|
+
export GROQ_API_KEY=... # or OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY (Ollama needs none)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Models are `"provider:model"`: `groq:`, `openai:`, `openrouter:`, `gemini:`, `ollama:` (no prefix = OpenAI).
|
|
63
|
+
Other OpenAI-compatible servers: `base_url=` and `api_key=`.
|
|
64
|
+
|
|
65
|
+
## The flags
|
|
66
|
+
|
|
67
|
+
| Flag | Default | What it switches on |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| `tools=` | none | `True` = all bundled tools · `["files", "web"]` groups · `["read_file"]` single tools · your own functions · any mix |
|
|
70
|
+
| `skills=` | none | `True` = bundled skills · `"research"` one by name · `"my_skills/"` your folder · `Skill(...)` · any mix |
|
|
71
|
+
| `memory=` | none (history in RAM only) | `"bot.db"` SQLite · `SupabaseStorage()` · your own `Storage` · `Memory(...)` |
|
|
72
|
+
| `mcp=` | none | command string, URL, `MCP(...)`, list, or an `mcpServers` JSON file |
|
|
73
|
+
| `shell=` | none | `"local"` or `"docker"` (or a dict / `Sandbox`). Turns on `run_command`. |
|
|
74
|
+
| `rules=` | none | string, list, or a text file; added to the prompt |
|
|
75
|
+
|
|
76
|
+
## Bundled tools (12): `botkit/tools/`
|
|
77
|
+
|
|
78
|
+
| Group | Tools |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `files` | `list_files` `read_file` (also reads .docx/.xlsx/.pptx) `write_file` `edit_file` `search_files` |
|
|
81
|
+
| `docs` | `create_docx` `create_xlsx` `create_pptx` |
|
|
82
|
+
| `web` | `fetch_url` `web_search` (DuckDuckGo; scraping a free page, may be rate-limited) |
|
|
83
|
+
| `shell` | `run_command` (only with `shell=`) |
|
|
84
|
+
| `util` | `calculate` (safe arithmetic) |
|
|
85
|
+
|
|
86
|
+
Your own tool: `@tool` on a function. Type hints and the docstring become the schema.
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from botkit import Agent, tool
|
|
90
|
+
|
|
91
|
+
@tool
|
|
92
|
+
def order_status(order_id: str) -> str:
|
|
93
|
+
"""Look up an order.
|
|
94
|
+
|
|
95
|
+
Args:
|
|
96
|
+
order_id: The order number.
|
|
97
|
+
"""
|
|
98
|
+
return "shipped"
|
|
99
|
+
|
|
100
|
+
bot = Agent(tools=["files", "calculate", order_status])
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Bundled skills (10): `botkit/skills/`
|
|
104
|
+
|
|
105
|
+
`research` · `planning` · `verify-work` · `writing-documents` · `presentations` · `spreadsheets` ·
|
|
106
|
+
`data-analysis` · `coding` · `debugging` · `summarizing`
|
|
107
|
+
|
|
108
|
+
Only each skill's name and one-line description go into the prompt; the model loads the full text with
|
|
109
|
+
`load_skill` when a task matches. Your own skills are folders with a `SKILL.md`
|
|
110
|
+
(frontmatter `name` and `description`, then the instructions): `Agent(skills=[True, "my_skills/"])`.
|
|
111
|
+
|
|
112
|
+
## Memory: choose the database
|
|
113
|
+
|
|
114
|
+
Memory is history (survives restarts) plus long-term facts (`remember` / `recall` / `forget` tools).
|
|
115
|
+
It sits on a `Storage` backend, so the database is your choice:
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
Agent(memory="bot.db") # SQLite (zero setup)
|
|
119
|
+
Agent(memory=SupabaseStorage()) # Supabase
|
|
120
|
+
Agent(memory=MyStorage()) # anything you write (see below)
|
|
121
|
+
Agent(memory="bot.db", session="user42") # one session per user, same database
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Supabase.** Run once in the Supabase SQL editor (`python -m botkit.memory.supabase` prints it), then set
|
|
125
|
+
`SUPABASE_URL` and `SUPABASE_KEY` (the `service_role` key, server side only):
|
|
126
|
+
|
|
127
|
+
```sql
|
|
128
|
+
create table if not exists botkit_messages (
|
|
129
|
+
id bigint generated always as identity primary key,
|
|
130
|
+
session text not null, data jsonb not null, created_at timestamptz not null default now());
|
|
131
|
+
create index if not exists botkit_messages_session_idx on botkit_messages (session, id);
|
|
132
|
+
create table if not exists botkit_facts (
|
|
133
|
+
id bigint generated always as identity primary key,
|
|
134
|
+
session text not null, text text not null, created_at timestamptz not null default now());
|
|
135
|
+
create index if not exists botkit_facts_session_idx on botkit_facts (session, id);
|
|
136
|
+
alter table botkit_messages enable row level security;
|
|
137
|
+
alter table botkit_facts enable row level security;
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Your own tables** (same connection):
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
db = SQLiteStorage("bot.db", extra_schema="CREATE TABLE IF NOT EXISTS orders(id INTEGER PRIMARY KEY, item TEXT)")
|
|
144
|
+
db.execute("INSERT INTO orders(item) VALUES(?)", ("tea",)); db.query("SELECT * FROM orders")
|
|
145
|
+
|
|
146
|
+
store = SupabaseStorage()
|
|
147
|
+
store.table("orders").insert({"item": "tea"}); store.table("orders").select({"item": "tea"}, order="id.desc")
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Wrap those calls in `@tool` functions to let the bot use them (`examples/memory_backends.py`).
|
|
151
|
+
|
|
152
|
+
**Any other database:** subclass `Storage` and implement 6 methods (`add_messages`, `get_messages`,
|
|
153
|
+
`clear_messages`, `add_fact`, `list_facts`, `delete_fact`). `examples/custom_storage.py` is a complete template.
|
|
154
|
+
|
|
155
|
+
## Rules and security
|
|
156
|
+
|
|
157
|
+
`rules=["Reply in Urdu"]` adds your rules to the prompt; the security rules always come last and cannot be loosened.
|
|
158
|
+
Enforcement is in code, not in the prompt:
|
|
159
|
+
|
|
160
|
+
- File tools and the shell are confined to the workspace folder (`..`, absolute paths and symlinks are refused).
|
|
161
|
+
- The shell does not exist unless you choose an environment: `"local"` (workspace only, API keys hidden, dangerous
|
|
162
|
+
commands blocked; a speed bump, not a jail) or `"docker"` (throwaway container: no network, read-only root,
|
|
163
|
+
memory/CPU limits). `deny=[r"git push"]` blocks more commands, `approve=callback` asks you before each command.
|
|
164
|
+
- API keys and tokens are redacted from anything a tool returns to the model.
|
|
165
|
+
- `fetch_url` and `web_search` refuse private/internal addresses, also after redirects.
|
|
166
|
+
- Tool output and web pages are marked as untrusted data (prompt-injection defence).
|
|
167
|
+
|
|
168
|
+
## Layout
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
botkit/
|
|
172
|
+
pyproject.toml README.md
|
|
173
|
+
botkit/
|
|
174
|
+
agent.py the loop (Agent)
|
|
175
|
+
llm.py model client, retries
|
|
176
|
+
tool.py @tool, Tool
|
|
177
|
+
skill.py skill loader
|
|
178
|
+
mcp.py MCP bridge
|
|
179
|
+
security.py sandbox.py errors.py
|
|
180
|
+
server.py optional HTTP API: Agent(...).serve()
|
|
181
|
+
memory/ Storage base, SQLite, Supabase, Memory
|
|
182
|
+
tools/ files.py docs.py web.py shell.py util.py
|
|
183
|
+
skills/ 10 folders, each with a SKILL.md
|
|
184
|
+
examples/ tests/
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## Not included (yet)
|
|
188
|
+
|
|
189
|
+
Streaming replies, async API, token-based context trimming (history is trimmed by message count),
|
|
190
|
+
sub-agents, image input, scheduled tasks.
|
|
191
|
+
|
|
192
|
+
## Tests
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
pip install -e ".[dev]" && pytest
|
|
196
|
+
```
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
botkit/__init__.py,sha256=T3PqLwJWVZslnRVQJ8ufgdz_OrTIf4nc_ALDKONKu58,903
|
|
2
|
+
botkit/agent.py,sha256=4eOZPyS50h3lKG86B_Yqn4KcrH4qPkV35WiP8-WJNxY,19567
|
|
3
|
+
botkit/errors.py,sha256=4RQgdicbh-F4BG3sKWaYAeiOue7q0kjhJzXNUvG5qmM,157
|
|
4
|
+
botkit/llm.py,sha256=fD6A39lAs7MEjUgaNCb-Y-Ckas88v4ySm1ZHkOghFGY,4414
|
|
5
|
+
botkit/mcp.py,sha256=G8dd9zo9XpM29X32vZuWESzDQKwNqE69aoUZtY65AUk,10736
|
|
6
|
+
botkit/sandbox.py,sha256=0KzPRGPyvxf6duTv027yT6168u8Zu1foHmW_6V_N85c,5589
|
|
7
|
+
botkit/security.py,sha256=B9bKrR--ZfjuYgb5wm5mwaC6oOCLY_g0TA2BWv-HIZg,4478
|
|
8
|
+
botkit/server.py,sha256=Rh1OymnGliFIG7tZSL_5bbBcwNvA1PaVLZdixlgDqsU,8491
|
|
9
|
+
botkit/skill.py,sha256=9vco2-OmfyrjK-L4uRp8CwZektq1kejHgq1xYaFsfE8,4906
|
|
10
|
+
botkit/tool.py,sha256=c7uQgxh0o99PCy3GaUyxD-VrB-WXKF4d-UGvMc6w170,6788
|
|
11
|
+
botkit/memory/__init__.py,sha256=UReiaUK4fwA-4RORP48CCmsqyfIHn2BldBQ_NBHJmS4,398
|
|
12
|
+
botkit/memory/base.py,sha256=JzSIP3_SgqRM_jVMl6DuNrqaVFPZPb-VMElRBQ01rkw,1975
|
|
13
|
+
botkit/memory/memory.py,sha256=C9yIunVinoDBaNr-ia4OfsVOdGjAX9FkDJBnUTUIgM8,4174
|
|
14
|
+
botkit/memory/sqlite.py,sha256=s8QoNQ9pntv_RZzIgNAvmbUgfCKq76U_RgbIdPRbJAY,4859
|
|
15
|
+
botkit/memory/supabase.py,sha256=5E0Y6XDyVJJBxaD-B16_rzoVxyV8rSCqBDdy1RDexxY,8262
|
|
16
|
+
botkit/skills/coding/SKILL.md,sha256=eks6PGxyCfHcpiS_kDfFSCNHCgJnLUtKiSEXE-v1qVI,832
|
|
17
|
+
botkit/skills/data-analysis/SKILL.md,sha256=_HMH2S90wntoImceBw_yMC_Lz0P4qWMYLixk1v-8PvM,770
|
|
18
|
+
botkit/skills/debugging/SKILL.md,sha256=zWK1ZakjAfSXssOW_4Chv-DdxgINFBFahFp_PrkY6cw,728
|
|
19
|
+
botkit/skills/planning/SKILL.md,sha256=ktoTfX3nubn67f30YK5C8ySbtJw_eWfHUcQuxDVh5Dc,762
|
|
20
|
+
botkit/skills/presentations/SKILL.md,sha256=7uo5hqy3E_XxH7rsr53aKZxB5fdev31HnLKm2UL16IU,646
|
|
21
|
+
botkit/skills/research/SKILL.md,sha256=HjT9n4j_tavPaPEamugjo9SI5MmWwev_u0L4h8CvbpE,802
|
|
22
|
+
botkit/skills/spreadsheets/SKILL.md,sha256=AvZeJEUCITpojckIcSZWxpwyFmuvq7O8xovbCp6DX_A,731
|
|
23
|
+
botkit/skills/summarizing/SKILL.md,sha256=09nIX24AW9HJo_GnfYKRT96DWHHB3EDFbq7vkuAlyFI,651
|
|
24
|
+
botkit/skills/verify-work/SKILL.md,sha256=GV9xQ2wpynLChXmrIzmIMYoWd1_GXlkAu6GmygjnYQ4,739
|
|
25
|
+
botkit/skills/writing-documents/SKILL.md,sha256=8frwnd8iRPNzvBEOYOebIttij4B9l0lkdHUL_9K1o9E,869
|
|
26
|
+
botkit/tools/__init__.py,sha256=2RpsrHQmOLqWxWNrEkoozf9D6TeB5C0nYK3wKKIXZaQ,1819
|
|
27
|
+
botkit/tools/docs.py,sha256=076rdwJ0gAfcOvr3Iw4Yh5mu2OYb4OJdl-P-ZDvWwqo,7591
|
|
28
|
+
botkit/tools/files.py,sha256=xvWJpB7MQqkhnEPVfDQv0YPnZUDq0PtILH5MG6itd_Q,5115
|
|
29
|
+
botkit/tools/shell.py,sha256=3B7t9Ukvw2d0lq5LHRAY2oyfGmdKGzEcuuNK-kf7GDg,763
|
|
30
|
+
botkit/tools/util.py,sha256=M7LhqshD632ZZYAxLzNwJsS4QCci9rFjVHJoeakWv44,2784
|
|
31
|
+
botkit/tools/web.py,sha256=VhYc6dFv6BnArMofh5sSmvwIXCtLhxuLLXM2tLqyRpg,5108
|
|
32
|
+
techtide_botkit-0.3.0.dist-info/licenses/LICENSE,sha256=U0Dx8T3awFsVpsWYvFxh2gR2Ep6nq4WeBzD4mE-zlkg,1068
|
|
33
|
+
techtide_botkit-0.3.0.dist-info/METADATA,sha256=EKL_ruA1rINcMIgsLxKXS2xVss0YCzFI_KE4I7o4_N4,8157
|
|
34
|
+
techtide_botkit-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
35
|
+
techtide_botkit-0.3.0.dist-info/top_level.txt,sha256=_scHx9xwAt2zV_IXkCv7d7mBCY0XQqxpVitvAjB7Df0,7
|
|
36
|
+
techtide_botkit-0.3.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ahmed Umair
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
botkit
|