pythinker-ai 0.1.0__tar.gz

pythinker_ai-0.1.0/.gitignore

@@ -0,0 +1,98 @@
+# Project-specific
+.worktrees/
+.assets
+.docs
+.env
+.web
+.orion
+
+# webui (monorepo frontend)
+webui/node_modules/
+webui/dist/
+webui/coverage/
+webui/.vite/
+*.tsbuildinfo
+
+# bridge (monorepo node service)
+bridge/node_modules/
+bridge/dist/
+
+# Python bytecode & caches
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+__pycache__/
+*.egg-info/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.dmypy.json
+dmypy.json
+.tox/
+.nox/
+.hypothesis/
+
+# Build & packaging
+dist/
+build/
+*.manifest
+*.spec
+pip-wheel-metadata/
+share/python-wheels/
+
+# Test & coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Lock files (project policy)
+poetry.lock
+uv.lock
+
+# Jupyter
+.ipynb_checkpoints/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+.directory
+
+# Editors & IDEs (local workspace / user settings)
+.vscode/
+.cursor/
+.idea/
+.fleet/
+*.code-workspace
+*.sublime-project
+*.sublime-workspace
+*.swp
+*.swo
+*~
+nano.*.save
+
+# Environment & secrets (keep examples tracked if needed)
+.env.*
+!.env.example
+
+# Logs & temp
+*.log
+logs/
+tmp/
+temp/
+*.tmp

pythinker_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,219 @@
+# Contributing to Pythinker
+
+Thank you for being here.
+
+Pythinker is built with a simple belief: good tools should feel calm, clear, and humane.
+We care deeply about useful features, but we also believe in achieving more with less:
+solutions should be powerful without becoming heavy, and ambitious without becoming
+needlessly complicated.
+
+This guide is not only about how to open a PR. It is also about how we hope to build
+software together: with care, clarity, and respect for the next person reading the code.
+
+## Maintainers
+
+| Maintainer | Focus |
+|------------|-------|
+| [@mohamed-elkholy95](https://github.com/mohamed-elkholy95) | Project lead, `main` + `dev` branches |
+
+## Branching Strategy
+
+We use a two-branch model to balance stability and exploration:
+
+| Branch | Purpose | Stability |
+|--------|---------|-----------|
+| `main` | Stable releases | Production-ready |
+| `dev` | Experimental features | May have bugs or breaking changes |
+
+### Which Branch Should I Target?
+
+**Target `dev` if your PR includes:**
+
+- New features or functionality
+- Refactoring that may affect existing behavior
+- Changes to APIs or configuration
+
+**Target `main` if your PR includes:**
+
+- Bug fixes with no behavior changes
+- Documentation improvements
+- Minor tweaks that don't affect functionality
+
+**When in doubt, target `dev`.** It is easier to move a stable idea from `dev` to `main`
+than to undo a risky change after it lands in the stable branch.
+
+### How Does `dev` Get Merged to `main`?
+
+We don't merge the entire `dev` branch. Instead, stable features are **cherry-picked**
+from `dev` into individual PRs targeting `main`:
+
+```
+dev  ──┬── feature A (stable) ──► PR ──► main
+       ├── feature B (testing)
+       └── feature C (stable) ──► PR ──► main
+```
+
+This happens on an as-needed cadence — when a feature has settled and is ready for a
+stable release.
+
+### Quick Summary
+
+| Your Change | Target Branch |
+|-------------|---------------|
+| New feature | `dev` |
+| Bug fix | `main` |
+| Documentation | `main` |
+| Refactoring | `dev` |
+| Unsure | `dev` |
+
+## Development Setup
+
+Keep setup boring and reliable. The goal is to get you into the code quickly.
+
+Pythinker is a Python package (`pythinker/`) plus a Vite/React web UI (`webui/`) and a
+small Node bridge for WhatsApp (`bridge/`). You only need to set up the parts you plan to
+touch.
+
+### Python (core package)
+
+We use [`uv`](https://docs.astral.sh/uv/) in CI because it's fast and deterministic. Plain
+`pip` works too.
+
+```bash
+# Clone the repository
+git clone https://github.com/mohamed-elkholy95/Pythinker-ai.git
+cd Pythinker-ai
+
+# Recommended: uv
+uv sync --all-extras
+
+# Alternative: pip + venv
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Run tests
+uv run pytest tests/
+# or: pytest tests/
+
+# Lint
+uv run ruff check pythinker
+# or: ruff check pythinker
+
+# Format
+uv run ruff format pythinker
+# or: ruff format pythinker
+```
+
+`pyproject.toml` is the source of truth for dependencies, lint rules, and test
+configuration. If you're unsure which extras to install, `--all-extras` / `[dev]` covers
+the full development surface.
+
+### Web UI
+
+The WebUI lives in `webui/` and uses [Bun](https://bun.sh/) (lockfile: `bun.lock`). `npm`
+also works, but please do not commit npm or pnpm lockfiles alongside `bun.lock`.
+
+```bash
+cd webui
+bun install
+bun run dev     # local dev server
+bun run test    # vitest
+bun run build   # production bundle
+```
+
+### Node bridge (WhatsApp)
+
+The `bridge/` directory is only needed if you're working on the WhatsApp channel.
+
+```bash
+cd bridge
+npm install
+npm run build
+```
+
+## Code Style
+
+We care about more than passing lint. We want Pythinker to stay small, calm, and readable.
+
+When contributing, please aim for code that feels:
+
+- **Simple** — prefer the smallest change that solves the real problem.
+- **Clear** — optimize for the next reader, not for cleverness.
+- **Decoupled** — keep boundaries clean and avoid unnecessary new abstractions.
+- **Honest** — do not hide complexity, but do not create extra complexity either.
+- **Durable** — choose solutions that are easy to maintain, test, and extend.
+
+### Python
+
+- **Line length**: 100 characters (enforced by `ruff`; `E501` is ignored so long strings
+  and comments don't block you, but treat 100 as a target).
+- **Target**: Python 3.11+. CI tests 3.11, 3.12, 3.13, and 3.14 on Ubuntu and Windows.
+- **Linting**: `ruff` with rule groups `E, F, I, N, W` (see `[tool.ruff.lint]` in
+  `pyproject.toml`). CI is strictest about `F401` (unused imports) and `F841` (unused
+  variables) — please clean those before opening a PR.
+- **Typing**: Python is dynamically typed, but we prefer annotations on public functions,
+  dataclasses, and anything on the message bus / tool registry boundary.
+- **Async**: the codebase is `asyncio`-native. `pytest` is configured with
+  `asyncio_mode = "auto"`, so `async def test_…` functions run as coroutines automatically.
+- **Logging**: use `loguru` (`from loguru import logger`), not the stdlib `logging` module.
+- **Formatting**: `ruff format` is available but not enforced in CI. Match the surrounding
+  file when in doubt.
+
+### TypeScript / React (webui)
+
+- Uses Vite + TypeScript 5.7 + Tailwind + Radix UI. Keep components small, typed, and
+  colocated with the feature they serve.
+- Tests use Vitest + Testing Library. Put tests in `webui/src/tests/` or next to the unit.
+- Match the existing import style and file naming. Prefer functional components and hooks.
+
+### Node (bridge)
+
+- TypeScript, compiled via `tsc`. Keep the bridge as thin as possible — it's a relay, not
+  a second runtime.
+
+### In practice
+
+- Prefer readable code over magical code.
+- Prefer focused patches over broad rewrites.
+- If a new abstraction is introduced, it should clearly reduce complexity rather than
+  move it around.
+- Do not add drive-by reformatting to unrelated files; it makes review harder.
+
+## Tests
+
+- Python tests live under `tests/`, organized by subsystem (`tests/agent/`,
+  `tests/channels/`, `tests/providers/`, etc.). New behavior needs a test; bug fixes
+  should include a test that fails before the fix and passes after.
+- Web UI tests live under `webui/src/tests/` and run with `bun run test`.
+- CI runs `ruff check pythinker --select F401,F841` and `pytest tests/` across the Python
+  matrix. Please make sure both pass locally before opening a PR.
+
+## Commits and Pull Requests
+
+- **Commit messages**: imperative mood, short subject (≤72 characters). The body explains
+  *why*, not *what* — the diff shows *what*.
+- **One logical change per PR**. If your branch grew into several changes, split it.
+- **PR description**: explain the motivation, summarize the change, and note anything a
+  reviewer should double-check. Link related issues.
+- **Target the right branch** (see the table above).
+- **Keep history honest**. Rebase or squash if that produces a cleaner story, but never
+  force-push over someone else's work.
+
+## Security
+
+If you find a vulnerability, **please do not open a public issue**. Follow the process in
+[`SECURITY.md`](./SECURITY.md) — private disclosure first, so we can fix it before it's
+exploited.
+
+## Questions?
+
+If you have questions, ideas, or half-formed insights, you are warmly welcome here.
+
+- Open an [issue](https://github.com/mohamed-elkholy95/Pythinker-ai/issues) for bugs or
+  feature requests.
+- Start a [discussion](https://github.com/mohamed-elkholy95/Pythinker-ai/discussions) for
+  questions, design conversations, and show-and-tell.
+
+Thank you for spending your time and care on Pythinker. We would love for more people to
+participate in this community, and we genuinely welcome contributions of all sizes.

pythinker_ai-0.1.0/LICENSE

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

pythinker_ai-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: pythinker-ai
+Version: 0.1.0
+Summary: Pythinker — an ultra-lightweight personal AI agent framework with built-in chat channels, memory, MCP, and an OpenAI-compatible API.
+Project-URL: Homepage, https://github.com/mohamed-elkholy95/Pythinker-ai
+Project-URL: Repository, https://github.com/mohamed-elkholy95/Pythinker-ai
+Project-URL: Documentation, https://github.com/mohamed-elkholy95/Pythinker-ai/tree/main/docs
+Project-URL: Issues, https://github.com/mohamed-elkholy95/Pythinker-ai/issues
+Project-URL: Changelog, https://github.com/mohamed-elkholy95/Pythinker-ai/releases
+Author: Pythinker contributors
+Author-email: Mohamed Elkholy <moelkholy1995@gmail.com>
+Maintainer-email: Mohamed Elkholy <moelkholy1995@gmail.com>
+License: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: agent,ai,anthropic,assistant,chatbot,discord,llm,mcp,openai,slack,telegram,whatsapp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anthropic<1.0.0,>=0.45.0
+Requires-Dist: chardet<6.0.0,>=3.0.2
+Requires-Dist: croniter<7.0.0,>=6.0.0
+Requires-Dist: ddgs<10.0.0,>=9.5.5
+Requires-Dist: dulwich<1.0.0,>=0.22.0
+Requires-Dist: filelock>=3.25.2
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: jinja2<4.0.0,>=3.1.0
+Requires-Dist: json-repair<1.0.0,>=0.57.0
+Requires-Dist: loguru<1.0.0,>=0.7.3
+Requires-Dist: mcp<2.0.0,>=1.26.0
+Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.3
+Requires-Dist: openai>=2.8.0
+Requires-Dist: openpyxl<4.0.0,>=3.1.0
+Requires-Dist: prompt-toolkit<4.0.0,>=3.0.50
+Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
+Requires-Dist: pydantic<3.0.0,>=2.12.0
+Requires-Dist: pypdf<6.0.0,>=5.0.0
+Requires-Dist: python-docx<2.0.0,>=1.1.0
+Requires-Dist: python-pptx<2.0.0,>=1.0.0
+Requires-Dist: python-socks[asyncio]<3.0.0,>=2.8.0; sys_platform != 'win32'
+Requires-Dist: python-telegram-bot[socks]<23.0,>=22.6
+Requires-Dist: pyyaml<7.0.0,>=6.0
+Requires-Dist: questionary<3.0.0,>=2.0.0
+Requires-Dist: readability-lxml<1.0.0,>=0.8.4
+Requires-Dist: rich<15.0.0,>=14.0.0
+Requires-Dist: slack-sdk<4.0.0,>=3.39.0
+Requires-Dist: slackify-markdown<1.0.0,>=0.2.0
+Requires-Dist: socksio<2.0.0,>=1.0.0
+Requires-Dist: tiktoken<1.0.0,>=0.12.0
+Requires-Dist: typer<1.0.0,>=0.20.0
+Requires-Dist: websocket-client<2.0.0,>=1.9.0
+Requires-Dist: websockets<17.0,>=16.0
+Provides-Extra: api
+Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'dev'
+Requires-Dist: pymupdf>=1.25.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py<3.0.0,>=2.5.2; extra == 'discord'
+Provides-Extra: langsmith
+Requires-Dist: langsmith>=0.1.0; extra == 'langsmith'
+Provides-Extra: matrix
+Requires-Dist: matrix-nio[e2e]>=0.25.2; (sys_platform != 'win32') and extra == 'matrix'
+Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
+Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
+Provides-Extra: msteams
+Requires-Dist: cryptography>=41.0; extra == 'msteams'
+Requires-Dist: pyjwt<3.0,>=2.0; extra == 'msteams'
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.25.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+![cover](./images/GitHub_README.png)
+
+<div align="center">
+  <p>
+    <a href="https://pypi.org/project/pythinker-ai/"><img src="https://img.shields.io/pypi/v/pythinker-ai" alt="PyPI"></a>
+    <a href="https://pepy.tech/project/pythinker-ai"><img src="https://static.pepy.tech/badge/pythinker-ai" alt="Downloads"></a>
+    <img src="https://img.shields.io/badge/python-%E2%89%A53.11-blue" alt="Python">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <a href="https://github.com/mohamed-elkholy95/Pythinker-ai/graphs/commit-activity" target="_blank">
+      <img alt="Commit activity" src="https://img.shields.io/github/commit-activity/m/mohamed-elkholy95/Pythinker-ai?labelColor=%20%2332b583&color=%20%2312b76a"></a>
+    <a href="https://github.com/mohamed-elkholy95/Pythinker-ai/issues?q=is%3Aissue%20is%3Aclosed" target="_blank">
+      <img alt="Issues closed" src="https://img.shields.io/github/issues-search?query=repo%3Amohamed-elkholy95%2FPythinker-ai%20is%3Aissue%20is%3Aclosed&label=issues%20closed&labelColor=%20%237d89b0&color=%20%235d6b98"></a>
+    <a href="https://github.com/mohamed-elkholy95/Pythinker-ai/stargazers" target="_blank">
+      <img alt="Stars" src="https://img.shields.io/github/stars/mohamed-elkholy95/Pythinker-ai?style=flat&logo=github&color=ffd43b"></a>
+  </p>
+</div>
+
+🐍 **Pythinker** is an open-source, ultra-lightweight personal-AI-agent framework. It keeps the core agent loop small and readable while still supporting chat channels, long-term memory, MCP, and practical deployment paths — so you can go from local setup to a long-running personal agent with minimal overhead.
+
+> Powered by a small, multiplexing agent loop: one Python process listens to Slack, Telegram, Discord, WhatsApp, Matrix, MS Teams, email, a WebSocket WebUI, and an OpenAI-compatible HTTP API — all backed by a single session-scoped memory layer.
+
+## 💡 Key Features
+
+- **Ultra-lightweight** — a small readable core. Stable long-running behavior without orchestration sprawl.
+- **Channel-agnostic** — Slack, Telegram, Discord, WhatsApp, Matrix, MS Teams, email, WebSocket, plus an OpenAI-compatible HTTP API.
+- **Provider-rich** — 25+ LLM providers (Anthropic, OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, Qwen/DashScope, MiniMax, VolcEngine, Moonshot, DeepSeek, StepFun, and more) behind a single interface.
+- **Memory that learns** — a two-phase "Dream" process consolidates long-term memory into `MEMORY.md` / `SOUL.md` / `USER.md`, auto-versioned with pure-Python git.
+- **Skills & MCP** — bundled skills (GitHub, cron, weather, tmux, summarize, skill-creator, …) plus first-class [Model Context Protocol](https://modelcontextprotocol.io/) tool access.
+- **Sandboxed shell** — every command is wrapped in a bubblewrap sandbox on Linux; file tools enforce workspace boundaries.
+- **Hackable** — the Python package is ~55k LOC with zero monolithic orchestration layer. Read it, fork it, extend it.
+
+## 📦 Install
+
+> [!IMPORTANT]
+> If you want the newest features and experiments, install from source (the `dev` branch).
+> If you want the most stable day-to-day experience, install from PyPI or with `uv`.
+
+**Install from source**
+
+```bash
+git clone https://github.com/mohamed-elkholy95/Pythinker-ai.git
+cd Pythinker-ai
+pip install -e .
+```
+
+**Install with `uv`**
+
+```bash
+uv tool install pythinker-ai
+```
+
+**Install from PyPI**
+
+```bash
+pip install pythinker-ai
+```
+
+## 🚀 Quick Start
+
+**1. Initialize**
+
+```bash
+pythinker onboard
+```
+
+The interactive wizard drops a config at `~/.pythinker/config.json` and asks which provider / model you want.
+
+**2. Configure** (`~/.pythinker/config.json`)
+
+Configure these **two parts** (other options have defaults). Add or merge the blocks below into your existing config rather than replacing the whole file.
+
+*Set your API key* (e.g. [OpenRouter](https://openrouter.ai/keys), a good default for global users):
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "apiKey": "sk-or-v1-xxx"
+    }
+  }
+}
+```
+
+*Set your model* (optionally pin a provider — defaults to auto-detection):
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "provider": "openrouter",
+      "model": "anthropic/claude-opus-4-6"
+    }
+  }
+}
+```
+
+**3. Chat**
+
+```bash
+pythinker agent
+```
+
+- Want different LLM providers, web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md).
+- Want to run Pythinker in chat apps like Telegram, Discord, Slack, WhatsApp, or Matrix? See [Chat Apps](./docs/chat-apps.md).
+- Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md).
+
+## 🧪 WebUI (Development)
+
+> [!NOTE]
+> The WebUI development workflow currently requires a source checkout and is not yet shipped together with the official packaged release. See the [WebUI README](./webui/README.md) for full WebUI development docs and build steps.
+
+<p align="center">
+  <img src="images/pythinker_webui.png" alt="pythinker webui preview" width="900">
+</p>
+
+**1. Enable the WebSocket channel in `~/.pythinker/config.json`**
+
+```json
+{ "channels": { "websocket": { "enabled": true } } }
+```
+
+**2. Start the gateway**
+
+```bash
+pythinker gateway
+```
+
+**3. Start the WebUI dev server**
+
+```bash
+cd webui
+bun install
+bun run dev
+```
+
+## 🏗️ Architecture
+
+<p align="center">
+  <img src="images/pythinker_arch.png" alt="pythinker architecture" width="800">
+</p>
+
+🐍 Pythinker stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.
+
+See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for a forensic walkthrough of the runtime.
+
+## ✨ Features
+
+<table align="center">
+  <tr align="center">
+    <th><p align="center">📈 24/7 Real-Time Market Analysis</p></th>
+    <th><p align="center">🚀 Full-Stack Software Engineer</p></th>
+    <th><p align="center">📅 Smart Daily Routine Manager</p></th>
+    <th><p align="center">📚 Personal Knowledge Assistant</p></th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img src="case/search.gif" width="180" height="400"></p></td>
+    <td align="center"><p align="center"><img src="case/code.gif" width="180" height="400"></p></td>
+    <td align="center"><p align="center"><img src="case/schedule.gif" width="180" height="400"></p></td>
+    <td align="center"><p align="center"><img src="case/memory.gif" width="180" height="400"></p></td>
+  </tr>
+  <tr>
+    <td align="center">Discovery • Insights • Trends</td>
+    <td align="center">Develop • Deploy • Scale</td>
+    <td align="center">Schedule • Automate • Organize</td>
+    <td align="center">Learn • Memory • Reasoning</td>
+  </tr>
+</table>
+
+## 📚 Docs
+
+Browse the [repo docs](./docs/README.md) for the current GitHub development version.
+
+- Talk to Pythinker from familiar chat apps: [Chat Apps](./docs/chat-apps.md)
+- Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md)
+- Integrate Pythinker with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
+- Run Pythinker with Docker or as a Linux service: [Deployment](./docs/deployment.md)
+- Deeper dives: [Architecture](./docs/ARCHITECTURE.md) · [Memory](./docs/memory.md) · [Multiple Instances](./docs/multiple-instances.md) · [Channel Plugin Guide](./docs/channel-plugin-guide.md)
+
+## 🤝 Contribute & Roadmap
+
+PRs welcome! The codebase is intentionally small and readable. 🤗
+
+### Branching Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable releases — bug fixes and minor improvements |
+| `dev` | Experimental features — new features and breaking changes |
+
+**Unsure which branch to target?** See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+**Roadmap** — Pick an item and [open a PR](https://github.com/mohamed-elkholy95/Pythinker-ai/pulls)!
+
+- **Multi-modal** — See and hear (images, voice, video)
+- **Long-term memory** — Never forget important context
+- **Better reasoning** — Multi-step planning and reflection
+- **More integrations** — Calendar and more
+- **Self-improvement** — Learn from feedback and mistakes
+
+### Contributors
+
+<a href="https://github.com/mohamed-elkholy95/Pythinker-ai/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=mohamed-elkholy95/Pythinker-ai&max=100&columns=12" alt="Contributors" />
+</a>
+
+## 🔐 Security
+
+Found a vulnerability? Please **do not open a public issue**. Follow the private disclosure process in [`SECURITY.md`](./SECURITY.md).
+
+## 📄 License
+
+Pythinker is released under the [MIT License](./LICENSE). Third-party components redistributed with the project are listed in [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).
+
+## ⭐ Star History
+
+<div align="center">
+  <a href="https://star-history.com/#mohamed-elkholy95/Pythinker-ai&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=mohamed-elkholy95/Pythinker-ai&type=Date&theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=mohamed-elkholy95/Pythinker-ai&type=Date" />
+      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=mohamed-elkholy95/Pythinker-ai&type=Date" style="border-radius: 15px;" />
+    </picture>
+  </a>
+</div>
+
+<p align="center">
+  <em>Thanks for visiting ✨ Pythinker!</em>
+</p>