Upload 32 files

.gitignore

@@ -0,0 +1,220 @@
+# Universal-MCP-server-sandox
+
+README.MD
+.gitignore
+app/*
+
+
+
+
+
+
+.env
+# 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
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# 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
+
+# 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

Dockerfile

@@ -0,0 +1,27 @@
+# Use an official Python runtime as a parent image.
+# We choose a slim version to keep the image size small.
+FROM python:3.10-slim
+
+# Set the working directory in the container.
+# All subsequent commands will be executed in this directory.
+WORKDIR /app
+
+# Copy the requirements file into the container.
+# We do this first to leverage Docker's layer caching.
+# If requirements.txt doesn't change, this step is skipped.
+COPY requirements.txt ./
+
+# Install any needed packages specified in requirements.txt.
+# The --no-cache-dir flag helps to keep the image smaller.
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application code into the working directory.
+COPY . .
+
+# Expose the hub port (matches HUB_PORT in app/.pyfun)
+EXPOSE 7860
+
+# Define the command to run your application.
+# This command will be executed when the container starts.
+# We use main.py as the entry point, as per our architecture.
+CMD ["python", "main.py"]

ESOL

@@ -0,0 +1,91 @@
+## Ethical Security Operations License (ESOL v1.1)
+since 2021
+updated on 05.02.2026
+
+### Section 1: Preamble and Scope
+The **Ethical Security Operations License (ESOL v1.1)** is an **additional, non-severable condition** supplementing the **MIT License** under which the covered software (hereinafter "the Work") is distributed.
+
+By downloading, copying, modifying, or executing the Work, the Licensee **irrevocably agrees** to adhere to both the terms of the MIT License and the specific, mandatory ethical constraints defined herein. **Lack of awareness of these terms does not constitute a defense.**
+
+### Section 2: Mandatory Ethical Use and Purpose
+The grant of rights under this License is **expressly and exclusively conditioned** upon the Licensee's continuous adherence to the following use limitations:
+
+1. **Authorized Use Only:** The Work shall be used **exclusively** for:
+   - Defensive security operations (Blue Teaming)
+   - Authorized penetration testing (Red Teaming) with documented consent
+   - Vulnerability research on systems owned or explicitly authorized by the researcher
+   - Security compliance auditing with contractual authorization
+
+2. **Explicit Written Authorization Required:** Any security testing, scanning, exploitation, or enumeration against **any system not wholly owned by the Licensee** requires **explicit, documented, written authorization** from the rightful owner **prior to execution**. Verbal permission, implicit consent, or "bug bounty program existence" does **not** constitute authorization without explicit scope documentation.
+
+3. **Educational Use Constraints:** Educational or research use must:
+   - Occur only in isolated, controlled environments (virtual machines, dedicated test networks)
+   - Not target production systems, public infrastructure, or third-party services
+   - Comply with institutional ethics board requirements where applicable
+
+### Section 3: Prohibited Use (Malicious Activities)
+The Licensee is **strictly and unconditionally prohibited** from using the Work for:
+
+* **Unauthorized Access or Reconnaissance:** Scanning, probing, accessing, or attempting to access any computer system, network, database, or data without **explicit prior written authorization** from the lawful owner.
+
+* **Malicious Code Operations:** Creating, distributing, executing, or facilitating:
+  - Malware, viruses, worms, trojans, ransomware, or rootkits
+  - Cryptominers operating without system owner consent
+  - Phishing infrastructure, scam campaigns, or social engineering attacks
+  - Exploits targeting zero-day vulnerabilities outside authorized disclosure processes
+
+* **Service Disruption:** Denial-of-service (DoS/DDoS) attacks, resource exhaustion, or any unauthorized degradation of system availability or performance.
+
+* **Data Exfiltration or Manipulation:** Unauthorized copying, modification, deletion, or encryption of data not owned by the Licensee.
+
+* **Legal Violations:** Any activity violating the Computer Fraud and Abuse Act (CFAA), GDPR, national cybercrime laws, or international treaties concerning unauthorized computer access.
+
+* **Circumvention of Security Controls:** Bypassing authentication, encryption, access controls, or security monitoring systems without documented authorization.
+
+### Section 4: Compliance Verification and Audit Rights
+The Licensor reserves the right to:
+- Request documentation of authorization for any deployment of the Work
+- Audit compliance upon reasonable notice if misuse is suspected
+- Publicly disclose violations (including Licensee identity) to warn the security community
+
+**Licensees conducting authorized security research are encouraged to maintain contemporaneous records of authorization as evidence of compliance.**
+
+### Section 5: No Warranty Regarding Legal Compliance
+**THE WORK IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE LICENSOR MAKES NO REPRESENTATION THAT USE OF THE WORK, EVEN IN COMPLIANCE WITH THIS LICENSE, WILL BE LEGAL IN ALL JURISDICTIONS. THE LICENSEE BEARS SOLE RESPONSIBILITY FOR ENSURING COMPLIANCE WITH ALL APPLICABLE LAWS.**
+
+### Section 6: Violation and Termination
+Violation of **any** provision of this ESOL v1.1 constitutes a **material breach** resulting in:
+
+1. **Immediate Automatic Termination** of all rights under both the MIT License and this ESOL
+2. **Obligation to Cease Use** and destroy all copies of the Work
+3. **Liability for Damages:** The Licensee shall be liable for all damages, including but not limited to:
+   - Direct and consequential damages to affected third parties
+   - Licensor's legal costs in enforcement actions
+   - Reputational harm to the Licensor or the security research community
+
+4. **Reporting to Authorities:** The Licensor reserves the right to report violations to appropriate law enforcement and cybersecurity authorities.
+
+### Section 7: Severability and Precedence
+If any provision of this License is held unenforceable, the remaining provisions remain in full effect. **In any conflict between the MIT License and ESOL v1.1, the ESOL v1.1 takes precedence regarding ethical use constraints.**
+
+### Section 8: Jurisdiction and Dispute Resolution
+This License shall be governed by the laws of **[Germany(Berlin)]**. Disputes shall be resolved through binding arbitration under **[Arbitration Rules]**, with the prevailing party entitled to attorney's fees.
+
+### Section 9: License Acceptance Evidence
+By downloading this software from any source (GitHub, mirrors, forks), you acknowledge that:
+- This license was prominently displayed in the repository
+- You had reasonable opportunity to review these terms
+- Your use constitutes legally binding acceptance
+---
+
+## Final Licensing Statement
+**This Work is dual-licensed under:**
+1. **The MIT License** (for general software rights)
+2. **The Ethical Security Operations License v1.1 (ESOL v1.1)** (for use constraints)
+
+**The ESOL v1.1 is a mandatory, non-severable condition of use. Acceptance is automatic upon use of the Work.**
+
+**By using this software, you acknowledge that misuse may result in criminal prosecution, civil liability, and permanent termination of license rights.**
+
+> Checked & Updated, on 08.02.2026 @01700MEZ
+## Ethical Security Operations License (ESOL v1.1) since 2021 against fraud and scam

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

PyFundaments – Function Overview.md

@@ -0,0 +1,145 @@
+# PyFundaments – Function Overview
+
+## `main.py`
+
+| Function                  | Description                                                                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize_fundaments()` | Asynchronously initializes services based on available environment variables. Returns a dictionary of services (`None` if not initialized). |
+| `main()`                  | Application entry point. Calls `initialize_fundaments()`, loads `app/app.py`, closes DB pool on shutdown.                                   |
+
+---
+
+## `fundaments/config_handler.py` – `ConfigHandler`
+
+| Function                 | Description                                                        |
+| ------------------------ | ------------------------------------------------------------------ |
+| `__init__()`             | Loads `.env` via `python-dotenv` and system environment variables. |
+| `load_all_config()`      | Stores all non-empty environment variables in `self.config`.       |
+| `get(key)`               | Returns value as string or `None`.                                 |
+| `get_bool(key, default)` | Parses boolean values (`true/1/yes/on`).                           |
+| `get_int(key, default)`  | Returns integer value or `default` on failure.                     |
+| `has(key)`               | Returns `True` if key exists and is not empty.                     |
+| `get_all()`              | Returns copy of full configuration dictionary.                     |
+| `config_service`         | Global singleton instance.                                         |
+
+---
+
+## `fundaments/postgresql.py`
+
+| Function                                              | Description                                                                         |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `enforce_cloud_security(dsn_url)`                     | Enforces `sslmode=require`, applies timeouts, removes incompatible DSN options.     |
+| `mask_dsn(dsn_url)`                                   | Removes credentials from DSN for logging.                                           |
+| `ssl_runtime_check(conn)`                             | Verifies active SSL connection.                                                     |
+| `init_db_pool(dsn_url)`                               | Creates asyncpg pool (min=1, max=10) and runs SSL check.                            |
+| `close_db_pool()`                                     | Gracefully closes connection pool.                                                  |
+| `execute_secured_query(query, *params, fetch_method)` | Executes parameterized query (`fetch`, `fetchrow`, `execute`) with reconnect logic. |
+
+---
+
+## `fundaments/encryption.py` – `Encryption`
+
+| Function                               | Description                                                      |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `generate_salt()`                      | Generates secure 16-byte hex salt.                               |
+| `__init__(master_key, salt)`           | Derives AES-256 key via PBKDF2-SHA256 (480k iterations).         |
+| `encrypt(data)`                        | Encrypts string using AES-256-GCM. Returns `{data, nonce, tag}`. |
+| `decrypt(encrypted_data, nonce, tag)`  | Decrypts data. Raises `InvalidTag` if tampered.                  |
+| `encrypt_file(source_path, dest_path)` | Encrypts file in 8192-byte chunks.                               |
+| `decrypt_file(source_path, dest_path)` | Decrypts file using stored nonce and tag.                        |
+
+---
+
+## `fundaments/access_control.py` – `AccessControl`
+
+| Function                                           | Description                          |
+| -------------------------------------------------- | ------------------------------------ |
+| `__init__(user_id)`                                | Initializes with optional user ID.   |
+| `has_permission(permission_name)`                  | Checks if user has permission.       |
+| `get_user_permissions()`                           | Returns all user permissions.        |
+| `get_user_roles()`                                 | Returns assigned roles.              |
+| `assign_role(role_id)`                             | Assigns role to user.                |
+| `remove_role(role_id)`                             | Removes role from user.              |
+| `get_all_roles()`                                  | Returns all roles.                   |
+| `get_all_permissions()`                            | Returns all permissions.             |
+| `create_role(name, description)`                   | Creates new role and returns ID.     |
+| `update_role_permissions(role_id, permission_ids)` | Replaces all permissions for a role. |
+| `get_role_permissions(role_id)`                    | Returns role permissions.            |
+
+---
+
+## `fundaments/user_handler.py`
+
+### `Database` (SQLite Wrapper)
+
+| Function                  | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `execute(query, params)`  | Executes query and commits.                       |
+| `fetchone(query, params)` | Returns single row.                               |
+| `fetchall(query, params)` | Returns all rows.                                 |
+| `close()`                 | Closes connection.                                |
+| `setup_tables()`          | Creates `users` and `sessions` tables if missing. |
+
+---
+
+### `Security` (Password Utilities)
+
+| Function                            | Description                                  |
+| ----------------------------------- | -------------------------------------------- |
+| `hash_password(password)`           | Hashes password (PBKDF2-SHA256 via passlib). |
+| `verify_password(password, hashed)` | Verifies password against hash.              |
+| `regenerate_session(session_id)`    | Generates new UUID session ID.               |
+
+---
+
+### `UserHandler`
+
+| Function                                  | Description                                            |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `login(username, password, request_data)` | Authenticates user, validates state, creates session.  |
+| `logout()`                                | Removes session from DB and memory.                    |
+| `is_logged_in()`                          | Checks if active session exists.                       |
+| `is_admin()`                              | Checks session `is_admin` flag.                        |
+| `validate_session(request_data)`          | Validates session against IP and User-Agent.           |
+| `lock_account(username)`                  | Locks user account.                                    |
+| `reset_failed_attempts(username)`         | Resets failed login counter.                           |
+| `increment_failed_attempts(username)`     | Increments failed attempts and locks after 5 failures. |
+
+---
+
+## `fundaments/security.py` – `Security` (Orchestrator)
+
+| Function                                       | Description                                                           |
+| ---------------------------------------------- | --------------------------------------------------------------------- |
+| `__init__(services)`                           | Initializes with required services. Raises `RuntimeError` if missing. |
+| `user_login(username, password, request_data)` | Performs login and session validation.                                |
+| `check_permission(user_id, permission_name)`   | Delegates permission check.                                           |
+| `encrypt_data(data)`                           | Encrypts data if encryption service is available.                     |
+| `decrypt_data(encrypted_data, nonce, tag)`     | Decrypts data or returns `None` on failure.                           |
+
+---
+
+## `fundaments/debug.py` – `PyFundamentsDebug`
+
+| Function          | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| `__init__()`      | Reads debug-related environment variables.              |
+| `_setup_logger()` | Configures logging handlers.                            |
+| `run()`           | Outputs runtime diagnostics when debug mode is enabled. |
+
+---
+
+## `app/app.py`
+
+| Function                        | Description                                                           |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `start_application(fundaments)` | Receives initialized service dictionary and starts application logic. |
+
+---
+
+## Architecture Notes
+
+* `UserHandler` uses internal SQLite.
+* `AccessControl` uses PostgreSQL via `execute_secured_query`.
+* `security.py` `Security` is the orchestrator layer.
+* All services are optional.

PyFundaments.md

@@ -0,0 +1,232 @@
+# PyFundaments: A Secure Python Architecture
+##### v. 1.0.1 dev
+
+## Description
+
+This project, named **PyFundaments**, provides a robust and secure Python architecture. Its core mission is not to be a monolithic framework, but to establish a layered, modular foundation—or "fundament"—of essential services. This structure ensures that every application starts on a verified and secure base, with a focus on stability, code clarity, and a security-first mindset from the ground up.
+
+> [!NOTE]  
+> you must create your app/bot in app/* or you get an error! Than uncoment
+> ```
+>from app.app import start_application
+>await start_application(fundaments)
+>```
+> in main.py
+
+
+
+-----
+
+## Table of Contents
+
+  - [Project Structure](#project-structure)
+  - [The Role of `main.py`](#the-role-of-mainpy)
+  - [Configuration (`.env`)](#configuration-env)
+  - [Installation](#installation)
+  - [Getting Started](#getting-started)
+  - [Module Documentation](#module-documentation)
+  - [Notes](#notes)
+
+-----
+
+## Project Structure
+
+```
+
+├── main.py # run main!
+├── README.md
+├── requirements.txt
+├── .gitignore
+├── .env.example
+├── app/
+│   └── ...
+│   └── app.py # sandboxed app run!
+│   └── tools.py
+│   └── provider.py
+│   └── models.py
+│   └── db_sync.py
+
+├── fundaments/ # do not touch! 
+│   ├── access_control.py
+│   ├── config_handler.py
+│   ├── encryption.py
+│   ├── postgresql.py
+│   ├── security.py
+│   └── user_handler.py
+└── docs/
+    ├── access_control.py.md
+    ├── encryption.py.md
+    ├── postgresql.py.md
+    ├── security.py.md
+    └── user_handler.py.md
+
+```
+-----
+
+## The Role of `main.py`
+
+`main.py` is the **only entry point** and acts as the first line of defense for the application.
+
+### Responsibilities
+
+  - [x] **Validate Dependencies**: It checks for all necessary core modules in `fundaments/` and exits immediately if any are missing.
+  - [x] **Conditional Environment Loading**: It uses the `config_handler` to load available configuration variables and initializes only the services for which configuration is present.
+  - [x] **Initialize Services**: It creates instances of available services (PostgreSQL, encryption, access control, user handling) based on environment configuration, collecting them into a single service dictionary.
+  - [x] **Graceful Degradation**: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality.
+  - [x] **Decouple App Logic**: It hands off the prepared and verified services to `app/app.py`, allowing the main application to focus purely on its business logic without worrying about low-level setup.
+
+-----
+
+## Configuration (`.env`)
+
+Application settings are managed using a `.env` file. **Never commit this file to version control.**
+
+The framework uses **conditional loading** - only services with available configuration are initialized. This allows different application types to use only what they need.
+
+A `.env.example` file is provided to show available variables. Create a copy named `.env` and configure only what your application requires.
+
+### Core Configuration (Optional based on app type)
+
+```text
+# Database connection (required only for database-using apps)
+DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"
+
+# Encryption keys (required only for apps using encryption)
+MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
+PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
+
+# Logging configuration (optional)
+LOG_LEVEL="INFO"
+LOG_TO_TMP="false"
+ENABLE_PUBLIC_LOGS="true"
+```
+
+### Application Examples
+
+**Discord Bot:** Only needs `BOT_TOKEN`, no database or encryption required.
+**ML Pipeline:** Only needs `DATABASE_URL` for data access.
+**Web Application:** May need all services for full functionality.
+
+-----
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+-----
+
+## Getting Started
+
+1.  **Configure**: Create your `.env` file from the `.env.example` and set only the variables your application type requires.
+2.  **Run**: Execute the `main.py` script to start the application.
+
+```bash
+python main.py
+```
+
+The framework will automatically detect available configuration and load only the necessary services.
+
+-----
+
+## Module Documentation
+
+Each security-relevant core module is documented in the `docs/` directory:
+
+| Module              | Description                              | Documentation                                     |
+| ------------------- | ---------------------------------------- | -------------------------------------------------|
+| `access_control.py` | Role-based access management             | [access\_control.py.md](docs/access_control.py.md)|
+| `config_handler.py` | Universal configuration loader           | [config\_handler.py.md](docs/config_handler.py.md)|
+| `encryption.py`     | Cryptographic routines                   | [encryption.py.md](docs/encryption.py.md)         |
+| `postgresql.py`     | Secure, asynchronous database access     | [postgresql.py.md](docs/postgresql.py.md)         |
+| `user_handler.py`   | Authentication and identity management   | [user\_handler.py.md](docs/user_handler.py.md)     |
+| `security.py`       | Central security orchestration layer     | [security.py.md](docs/security.py.md)             |
+
+-----
+
+## License
+
+This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+### Section 4: Additional Restrictions and Ethical Use Policy
+
+This project is released under the permissive Apache 2.0 License, which is intended to provide broad freedom for use and modification.  
+However, in the interest of fostering a safe and responsible community, we include the following **mandatory ethical use restrictions**:
+
+Use of this project (or derivatives) is **strictly prohibited** for purposes that:
+
+  - **Promote Hatred or Discrimination**  
+      Includes hate speech, incitement to violence, or discrimination based on race, religion, gender, orientation, etc.
+
+  - **Facilitate Illegal Activities**  
+      Use to conduct or support criminal activity is forbidden.
+
+  - **Spread Malicious Content**  
+      This includes pornography, malware, spyware, or other harmful payloads.
+
+We believe that freedom in development must be coupled with responsibility.  
+**Violation of these terms constitutes a breach of license and will trigger takedown actions** including legal and technical responses.
+
+*Volkan Kücükbudak*
+
+-----
+
+## Credits
+
+- Developed and maintained by the PyFundaments project.  
+-  Core components inspired by best practices in modular app architecture and OWASP security principles.
+- Third-party libraries are credited in their respective module docs and comply with open-source terms.
+
+-----
+
+## Notes
+
+    Security-first by design.  
+    If one piece is missing or unsafe — the app does not run.  
+    Zero tolerance for guesswork.
+
+> Give a ⭐ if you find the structure helpful.
+
+
+## Changelog 
+###### Version 1.0.0 -> 1.0.1
+### PyFundaments Refactoring
+
+#### Modified Files
+
+**1. main.py - Conditional Service Loading**
+- **Added:** Environment-based conditional service initialization
+- **Added:** Graceful fallback when services can't be initialized (warning instead of crash)
+- **Added:** Conditional logging configuration (LOG_LEVEL, LOG_TO_TMP, ENABLE_PUBLIC_LOGS)
+- **Added:** Smart dependency management (access_control & user_handler only load if database available)
+- **Added:** Safe shutdown (only close DB pool if it was initialized)
+- **Result:** Framework now supports partial service loading for different app types
+
+**2. app/app.py - Proper Service Injection**
+- **Removed:** Direct service imports and instantiation
+- **Added:** Services received as parameter from main.py
+- **Modified:** start_application() now takes fundaments dictionary as parameter
+- **Added:** Conditional service usage based on what main.py provides
+- **Added:** Examples for different app types (database-only, database-free modes)
+- **Result:** Clean separation - main.py handles initialization, app.py uses services
+
+**3. fundaments/config_handler.py - Universal Configuration Loader**
+- **Removed:** REQUIRED_KEYS validation (moved to main.py)
+- **Modified:** Now loads ALL environment variables without validation
+- **Added:** Helper methods: get_bool(), get_int(), has(), get_all()
+- **Added:** Safe defaults and type conversion
+- **Result:** Config handler never needs updates, works with any ENV variables
+
+**4. .env.example - Conditional Configuration Template**
+- **Added:** Clear separation between core and optional dependencies
+- **Added:** Logging configuration options
+- **Added:** App-specific configuration examples (Discord, ML, Web)
+- **Added:** Comments explaining when to use each option
+- **Result:** Users only configure what they need, no unused variables
+
+#### Architecture Improvements
+- **Conditional Loading:** Framework only loads needed services based on available ENV vars
+- **Merge-Safe Structure:** User code (app/, config_handler.py) protected from framework updates
+- **Zero Breaking Changes:** Updates only affect fundaments/ directory
+- **Enterprise-Level Merging:** Community can safely pull framework updates</document_content></document>

README.md

@@ -1,15 +1,516 @@
 ---
-title: MyAiHub
-emoji: 🔥
-colorFrom: purple
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.31.0
-python_version: '3.12'
-app_file: app.py
-pinned: false
-license: bigscience-bloom-rail-1.0
-short_description: My Universal AI HUB (Privat)
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+title: Multi-LLM API Gateway
+emoji: 🛡️
+colorFrom: indigo
+colorTo: red
+sdk: docker
+pinned: true
+license: apache-2.0
+short_description: Secure Multi-LLM Gateway — (Streamable HTTP / SSE)
+---
+
+# Multi-LLM API Gateway
+
+— or Universal MCP Hub (Sandboxed)  
+— or secure AI wrapper with dual interface: REST + MCP
+
+aka: a clean, secure starting point for your own projects.  
+Pick the description that fits your use case. They're all correct.
+
+> A production-grade **the-thing** that actually thinks about security.  
+> Built on [PyFundaments](PyFundaments.md) — running on **simpleCity**.
+
+```
+No key → no tool → no crash → no exposed secrets
+```
+
+> [!WARNING]
+> Most MCP servers are prompts dressed up as servers. This one has a real architecture.
+
+---
+
+> [!IMPORTANT]
+> This project is under active development — always use the latest release from [Codey Lab](https://github.com/Codey-LAB/Multi-LLM-API-Gateway) *(more stable builds land here first)*.  
+> This repo ([DEV](https://github.com/VolkanSah/Multi-LLM-API-Gateway)) is where the chaos happens. 🔬 A ⭐ on the repos will be cool 😙
+
+---
+
+## What's new in v1.1.0 (Rebuild)
+
+> Full changelog in [`REVIEW.md`](REVIEW.md). Highlights:
+
+- **Fixed:** `/mcp` 404 (mount middleware stripped the prefix FastMCP expects) and the missing session-manager lifespan — MCP is fully functional again.
+- **New:** **Auto model pricing** — costs are fetched from the public OpenRouter models API + the LiteLLM community price list, cached in `db_sync` (24h TTL). Your `.pyfun [MODELS]` values always win as override. Manual cost maintenance is over.
+- **New:** Brave + Tavily search providers implemented with fallback chain — `web_search` registers as soon as `BRAVE_API_KEY` or `TAVILY_API_KEY` is set.
+- **New:** `db_query` as MCP tool (SELECT-only, app/* tables).
+- **Cleanup:** dead code removed, `requirements.txt` now pins `mcp>=1.10,<2` (not `fastmcp`), LF line endings.
+
+## Why this exists
+
+The AI ecosystem is full of servers with hardcoded keys, `os.environ` scattered everywhere, zero sandboxing. One misconfigured fork and your API keys are gone.
+
+This is exactly the kind of negligence (and worse — outright fraud) that [Wall of Shames](https://github.com/Wall-of-Shames) documents: fake "AI tools" exploiting non-technical users — API wrappers dressed up as custom models, Telegram payment funnels, bought stars. If you build on open source, you should know this exists.
+
+This hub is the antidote:
+
+- **Structural sandboxing** — `app/*` can never touch `fundaments/` or `.env`. Not by convention. By design.
+- **Guardian pattern** — `main.py` is the only process that reads secrets. It injects validated services as a dict. `app/*` never sees the raw environment.
+- **Graceful degradation** — No key? Tool doesn't register. Server still starts. No crash, no error, no empty `None` floating around.
+- **Single source of truth** — All tool/provider/model config lives in `app/.pyfun`. Adding a provider = edit one file. No code changes.
+
+---
+
+## Two Interfaces — One Server
+
+This hub exposes **two completely independent interfaces** on the same hypercorn instance:
+
+```
+POST /api          → REST interface — for custom clients, desktop apps, CMS plugins
+GET+POST /mcp      → MCP interface — for Claude Desktop, Cursor, Windsurf, any MCP client
+GET /              → Health check — uptime, status
+```
+
+They share the same tool registry, provider config, and fallback chain. Adding a tool once makes it available on both interfaces automatically.
+
+### REST API (`/api`)
+
+Simple JSON POST — no protocol overhead, works with any HTTP client:
+
+```json
+POST /api
+{"tool": "llm_complete", "params": {"prompt": "Hello", "provider": "anthropic"}}
+```
+
+Used by: Desktop Client (`DESKTOP_CLIENT/hub.py`), WordPress plugin, any custom integration.
+
+### MCP Interface (`/mcp`)
+
+Full MCP protocol — tool discovery, structured calls, streaming responses.
+
+**Primary transport: Streamable HTTP** (MCP spec 2025-11-25)  
+**Fallback transport: SSE** (legacy, configurable via `.pyfun`)
+
+Configured via `HUB_TRANSPORT` in `app/.pyfun [HUB]`:
+
+```ini
+HUB_TRANSPORT = "streamable-http"   # default — MCP spec 2025-11-25
+# HUB_TRANSPORT = "sse"             # legacy fallback for older clients
+```
+
+Used by: Claude Desktop, Cursor, Windsurf, any MCP-compatible client.
+
+---
+
+## Architecture
+
+```
+main.py (Guardian)
+│
+│  reads .env / HF Secrets
+│  initializes fundaments/* conditionally
+│  injects validated services as dict
+│
+└──► app/app.py (Orchestrator, sandboxed)
+     │
+     │  unpacks fundaments ONCE, at startup, never stores globally
+     │  starts hypercorn (async ASGI)
+     │  routes: GET / | POST /api | /mcp (transport-dependent)
+     │
+     ├── app/mcp.py         ← FastMCP + transport handler (Streamable HTTP / SSE)
+     ├── app/tools.py       ← Tool registry (key-gated)
+     ├── app/providers.py   ← LLM + Search execution + fallback chain
+     ├── app/models.py      ← Model limits, costs, capabilities
+     ├── app/config.py      ← .pyfun parser (single source of truth)
+     └── app/db_sync.py     ← Internal SQLite IPC (app/* state only)
+                              ≠ fundaments/postgresql.py (Guardian-only)
+```
+
+**The sandbox is structural:**
+
+```python
+# app/app.py — fundaments unpacked ONCE, NEVER stored globally
+async def start_application(fundaments: Dict[str, Any]) -> None:
+    config_service         = fundaments["config"]
+    db_service             = fundaments["db"]          # None if not configured
+    encryption_service     = fundaments["encryption"]  # None if keys missing
+    access_control_service = fundaments["access_control"]
+    ...
+    # From here: app/* reads its own config from app/.pyfun only.
+    # fundaments are never passed into other app/* modules.
+```
+
+`app/app.py` never calls `os.environ`. Never imports from `fundaments/`. Never reads `.env`.  
+This isn't documentation. It's enforced by the import structure.
+
+### Why Quart + hypercorn?
+
+**Quart** is async Flask — fully `async/await` native. FastMCP's handlers are async; mixing sync Flask would require thread hacks. With Quart, `/mcp` hands off directly to FastMCP — no bridging, no blocking.
+
+**hypercorn** is an ASGI server (vs. waitress/gunicorn which are WSGI). WSGI servers handle one request per thread — wrong for long-lived MCP connections. hypercorn handles both Streamable HTTP and SSE natively, and runs without extra config on HuggingFace Spaces. HTTP/2 support (`config.h2 = True`) is built-in — relevant for Streamable HTTP performance at scale.
+
+The `/mcp` route in `app.py` remains the natural interception point regardless of transport — auth checks, rate limiting, and logging can all be added there before the request reaches FastMCP.
+
+---
+
+## Two Databases — One Architecture
+
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Guardian Layer (fundaments/*)                              │
+│                                                             │
+│  postgresql.py   → Cloud DB (e.g. Neon, Supabase)          │
+│                    asyncpg pool, SSL enforced               │
+│                                                             │
+│  user_handler.py → SQLite (users + sessions tables)        │
+│                    PBKDF2-SHA256 password hashing           │
+│                    Session validation incl. IP + UserAgent  │
+│                    Account lockout after 5 failed attempts  │
+│                                                             │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ inject as fundaments dict
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│  App Layer (app/*)                                          │
+│                                                             │
+│  db_sync.py  → SQLite (hub_state + tool_cache tables)      │
+│                aiosqlite (async, non-blocking)              │
+│                NEVER touches users/sessions tables          │
+│                Relocated to /tmp/ on HF Spaces auto        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Table ownership — hard rule:**
+
+| Table | Owner | Access |
+| :--- | :--- | :--- |
+| `users` | `fundaments/user_handler.py` | Guardian only |
+| `sessions` | `fundaments/user_handler.py` | Guardian only |
+| `hub_state` | `app/db_sync.py` | app/* only |
+| `tool_cache` | `app/db_sync.py` | app/* only |
+| `hub_results` | PostgreSQL / Guardian | via `persist_result` tool |
+
+---
+
+## Tools
+
+Tools register at startup — only if the required API key exists. No key, no tool. Server always starts.
+
+| ENV Secret | Tool | Notes |
+| :--- | :--- | :--- |
+| `ANTHROPIC_API_KEY` | `llm_complete` | Claude Haiku / Sonnet / Opus |
+| `GEMINI_API_KEY` | `llm_complete` | Gemini 2.0 / 2.5 / 3.x Flash & Pro |
+| `OPENROUTER_API_KEY` | `llm_complete` | 100+ models via OpenRouter |
+| `HF_TOKEN` | `llm_complete` | HuggingFace Inference API |
+| `BRAVE_API_KEY` | `web_search` | Independent web index |
+| `TAVILY_API_KEY` | `web_search` | AI-optimized search with synthesized answers |
+| `DATABASE_URL` | `cloud DB` | e.g. Neon, Supabase |
+| `DATABASE_URL` | `db_query`, `persist_result` | SQLite read + PostgreSQL write |
+| *(always)* | `list_active_tools` | Shows key names only — never values |
+| *(always)* | `health_check` | Status + uptime + active transport |
+| *(always)* | `get_model_info` | Limits, costs, capabilities per model (auto-merged) |
+| *(always)* | `get_model_pricing` | Auto-fetched costs — `.pyfun` values win as override |
+| *(always)* | `refresh_pricing` | Force refresh from OpenRouter + LiteLLM |
+| *(always)* | `db_query` | Read-only SELECT on internal hub state |
+
+For all key names see [`app/.pyfun`](app/.pyfun).
+
+**Tools are configured in `.pyfun` — including system prompts:**
+
+```ini
+[TOOL.code_review]
+active           = "true"
+description      = "Review code for bugs, security issues and improvements"
+provider_type    = "llm"
+default_provider = "anthropic"
+timeout_sec      = "60"
+system_prompt    = "You are an expert code reviewer. Analyze the given code for bugs, security issues, and improvements. Be specific and concise."
+[TOOL.code_review_END]
+```
+
+Current built-in tools: `llm_complete`, `code_review`, `summarize`, `translate`, `web_search`, `db_query`  
+Future hooks (commented, ready): `image_gen`, `code_exec`, `shellmaster_2.0`, Discord, GitHub webhooks
+
+---
+
+## LLM Fallback Chain
+
+All LLM providers share one `llm_complete` tool. If a provider fails, the hub walks the fallback chain from `.pyfun`:
+
+```
+e.g. anthropic → gemini → openrouter → huggingface
+```
+
+```ini
+[LLM_PROVIDER.anthropic]
+fallback_to = "gemini"
+[LLM_PROVIDER.anthropic_END]
+
+[LLM_PROVIDER.gemini]
+fallback_to = "openrouter"
+[LLM_PROVIDER.gemini_END]
+```
+
+Same pattern applies to search providers (`brave → tavily`).
+
+---
+
+## Quick Start
+
+### HuggingFace Spaces (recommended)
+
+1. Fork / duplicate this Space
+2. Go to **Settings → Variables and secrets**
+3. Add the API keys you have (any subset works)
+4. Space starts automatically — only tools with valid keys register
+
+[→ Live Demo Space](https://huggingface.co/spaces/codey-lab/Multi-LLM-API-Gateway) (no LLM keys set)
+
+### Local / Docker
+
+```bash
+git clone https://github.com/VolkanSah/Multi-LLM-API-Gateway
+cd Multi-LLM-API-Gateway
+cp example-mcp___.env .env
+# fill in your keys
+pip install -r requirements.txt
+python main.py
+```
+
+Minimum required ENV vars (everything else is optional):
+
+```env
+PYFUNDAMENTS_DEBUG=""
+LOG_LEVEL="INFO"
+LOG_TO_TMP=""
+ENABLE_PUBLIC_LOGS="true"
+HF_TOKEN=""
+HUB_SPACE_URL=""
+```
+
+Transport is configured in `app/.pyfun [HUB]` — not via ENV.
+
+---
+
+## Connect an MCP Client
+
+### Streamable HTTP (default — MCP spec 2025-11-25)
+
+```json
+{
+  "mcpServers": {
+    "universal-mcp-hub": {
+      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/mcp"
+    }
+  }
+}
+```
+
+### Streamable HTTP — Private Space (with HF token)
+
+```json
+{
+  "mcpServers": {
+    "universal-mcp-hub": {
+      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/mcp",
+      "headers": {
+        "Authorization": "Bearer hf_..."
+      }
+    }
+  }
+}
+```
+
+### SSE legacy fallback (set `HUB_TRANSPORT = "sse"` in `.pyfun`)
+
+```json
+{
+  "mcpServers": {
+    "universal-mcp-hub": {
+      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/mcp"
+    }
+  }
+}
+```
+
+> Same URL (`/mcp`) for both transports — the protocol is negotiated automatically.  
+> SSE fallback is for older clients that don't support Streamable HTTP yet.
+
+---
+
+## Desktop Client
+###### (experimental — ~80% AI generated)
+
+A full PySide6 desktop client is included in `DESKTOP_CLIENT/hub.py`.  
+Communicates via the REST `/api` endpoint — no MCP protocol overhead.  
+Ideal for private or non-public Spaces.
+
+```bash
+pip install PySide6 httpx
+# optional file handling:
+pip install Pillow PyPDF2 pandas openpyxl
+python DESKTOP_CLIENT/hub.py
+```
+
+**Features:**
+- Multi-chat with persistent history
+- Tool / Provider / Model selector loaded live from your Hub
+- File attachments: images, PDF, CSV, Excel, ZIP, source code
+- Connect tab with health check + auto-load
+- Settings: HF Token + Hub URL saved locally, never sent anywhere except your own Hub
+- Full request/response log with timestamps
+- Runs on Windows, Linux, macOS
+
+[→ Desktop Client docs](DESKTOP_CLIENT/README.md)
+
+---
+
+## CMS & Custom Clients
+
+| Client | Interface used | Notes |
+| :--- | :--- | :--- |
+| [Desktop Client](DESKTOP_CLIENT/hub.py) | REST `/api` | PySide6, local |
+| [WP AI Hub](https://github.com/VolkanSah/WP-AI-HUB/) | REST `/api` | WordPress plugin |
+| TYPO3 (soon) | REST `/api` | — |
+| Claude Desktop | MCP `/mcp` | Streamable HTTP |
+| Cursor / Windsurf | MCP `/mcp` | Streamable HTTP |
+
+---
+
+## Configuration (.pyfun)
+
+`app/.pyfun` is the single source of truth for all app behavior. Three tiers:
+
+```
+LAZY:       [HUB] + one [LLM_PROVIDER.*]                    → works
+NORMAL:     + [SEARCH_PROVIDER.*] + [MODELS.*]              → works better
+PRODUCTIVE: + [TOOLS] + [HUB_LIMITS] + [DB_SYNC]           → full power
+```
+
+Key settings in `[HUB]`:
+
+```ini
+[HUB]
+HUB_TRANSPORT   = "streamable-http"   # streamable-http | sse
+HUB_STATELESS   = "true"              # true = HF Spaces safe, no session state
+HUB_PORT        = "7860"
+[HUB_END]
+```
+
+Adding a new LLM provider — two steps:
+
+```ini
+# 1. app/.pyfun
+[LLM_PROVIDER.mistral]
+active        = "true"
+base_url      = "https://api.mistral.ai/v1"
+env_key       = "MISTRAL_API_KEY"
+default_model = "mistral-large-latest"
+models        = "mistral-large-latest, mistral-small-latest"
+fallback_to   = ""
+[LLM_PROVIDER.mistral_END]
+```
+
+```python
+# 2. app/providers.py — uncomment the dummy
+_PROVIDER_CLASSES = {
+    ...
+    "mistral": MistralProvider,   # ← uncomment to activate
+}
+```
+
+---
+
+## Dependencies
+
+```
+# PyFundaments Core (always required)
+asyncpg          — async PostgreSQL pool (Guardian/cloud DB)
+python-dotenv    — .env loading
+passlib          — PBKDF2 password hashing in user_handler.py
+cryptography     — encryption layer in fundaments/
+
+# MCP Hub
+mcp              — MCP protocol + FastMCP (Streamable HTTP + SSE)
+httpx            — async HTTP for all provider API calls
+quart            — async Flask (ASGI) — needed for MCP + hypercorn
+hypercorn        — ASGI server — Streamable HTTP + SSE, HF Spaces native
+requests         — sync HTTP for tool workers
+
+# Optional (uncomment in requirements.txt as needed)
+# aiofiles         — async file ops (ML pipelines, file uploads)
+# discord.py       — Discord bot integration (planned)
+# PyNaCl           — Discord signature verification
+# psycopg2-binary  — alternative PostgreSQL driver
+```
+
+> **Note:** The package is `mcp` (not `fastmcp`) — `FastMCP` is imported from `mcp.server.fastmcp`.  
+> Streamable HTTP support requires `mcp >= 1.6.0`.
+
+---
+
+## Security Design
+
+- API keys live in HF Secrets / `.env` — never in `.pyfun`, never in code
+- `list_active_tools` returns key **names** only — never values
+- `db_query` is SELECT-only, enforced at application level (not just docs)
+- `app/*` has zero import access to `fundaments/` internals
+- Direct execution of `app/app.py` blocked by design — warning + null-fundaments fallback
+- `fundaments/` initialized conditionally — missing services degrade gracefully, never crash
+- Streamable HTTP uses standard Bearer headers — no token-in-URL (unlike SSE)
+
+> PyFundaments is not perfect. But it's more secure than most of what runs in production today.
+
+[→ Full Security Policy](SECURITY.md)
+
+---
+
+## Foundation
+
+Built on [PyFundaments](PyFundaments.md) — a security-first Python boilerplate:
+
+- `config_handler.py` — env loading with validation
+- `postgresql.py` — async DB pool (Guardian-only)
+- `encryption.py` — key-based encryption layer
+- `access_control.py` — role/permission management
+- `user_handler.py` — user lifecycle management
+- `security.py` — unified security manager composing the above
+
+None accessible from `app/*`. Injected as a validated dict by `main.py`.
+
+[→ PyFundaments Function Overview](PyFundaments%20–%20Function%20Overview.md)  
+[→ Module Docs](docs/app/)  
+[→ Source Repo](https://github.com/VolkanSah/Multi-LLM-API-Gateway)
+
+---
+
+## Related Projects
+
+- [Customs LLMs for free — Build Your Own LLM Service](https://github.com/VolkanSah/SmolLM2-customs/)
+- [WP AI Hub (WordPress Client)](https://github.com/VolkanSah/WP-AI-HUB/)
+- [ShellMaster (2023 precursor)](https://github.com/VolkanSah/ChatGPT-ShellMaster)
+
+---
+
+## History
+
+[ShellMaster](https://github.com/VolkanSah/ChatGPT-ShellMaster) (2023, MIT) was the precursor — browser-accessible shell for ChatGPT with session memory, built before MCP was a concept. Universal MCP Hub is its natural evolution: same idea, proper architecture, dual interface.
+
+---
+
+## License
+
+Dual-licensed:
+
+- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+- [Ethical Security Operations License v1.1 (ESOL)](ESOL) — mandatory, non-severable
+
+By using this software you agree to all ethical constraints defined in ESOL v1.1.
+
+---
+
+*Architecture, security decisions, and PyFundaments by Volkan Kücükbudak.*  
+*Built with Claude (Anthropic) as a typing assistant for docs (and the occasional bug).*
+
+> crafted with passion — just wanted to understand how it works, don't actually need it, have a CLI 😄

REVIEW.md

@@ -0,0 +1,250 @@
+# Code-Review & Rebuild — Multi-LLM-API-Gateway v1.1.0
+
+**Datum:** 10.11.2026 · **Basis:** `Multi-LLM-API-Gateway_brocken.7z` + `PyFundaments-Quart-Boilerplate.zip`
+**Getestet:** Live-Boot, MCP-Session-Flow, /api-Endpunkte, echtes Pricing-Fetch (OpenRouter + LiteLLM), Fehlerpfade
+
+---
+
+## 1. Kurzfassung
+
+Der Gateway **startete**, aber **MCP war komplett tot** (`POST /mcp` → 404). Zwei verlorene Boilerplate-Konzepte waren die Ursache. Nach dem Fix wurde der Hub um Auto-Model-Pricing erweitert (dein Schmerzpunkt: Kosten nie wieder von Hand pflegen) und um echte Search-Provider.
+
+**Finale Tool-Liste (live getestet):**
+`llm_complete` · `web_search` · `list_active_tools` · `health_check` · `get_model_info` · `get_model_pricing` · `refresh_pricing` · `db_query`
+
+---
+
+## 2. Was kaputt war (mit Beweis)
+
+| # | Befund | Beweis / Test |
+|---|--------|---------------|
+| **A1** | `/mcp` → **404**. Die Mount-Middleware stripte den `/mcp`-Prefix, aber FastMCP registriert seine Route **intern selbst** unter `/mcp` (`settings.streamable_http_path`). Der gestripte Pfad `/` existiert in der inneren Starlette-App nicht. | Minimal-Repro: gestript → 404; Pfad unangetastet → erreichbar. Das Boilerplate hat genau das mit `strip_prefix=False` (Default) abgefangen. |
+| **A2** | **Session-Manager lief nie.** `mcp.lifespan()` fehlte komplett, `serve()` lag nicht im `async with`. | Ohne lifespan: `RuntimeError: Task group is not initialized` bei jedem Request (nachgewiesen). |
+| **A3** | **SSE-Fallback tot.** `mcp.handle_request()` rief `_mcp.handle_sse(request)` — diese Methode existiert im MCP-SDK 1.27 nicht. | SDK-Inspektion. |
+| **A4** | `tools.run()` verlangte `prompt` positional → `/api` ohne `prompt` = roher 500er. | Live-Test. |
+| **A5** | `providers.search()` war ein Stub („not yet implemented") — Brave/Tavily standen in der `.pyfun`, `web_search` registrierte sich nie. | Boot-Log: „No active search providers". |
+| **A6** | `requirements.txt` pinnte `fastmcp` — dein Code importiert aber `mcp.server.fastmcp` (das **mcp**-SDK). Funktionierte nur zufällig, weil fastmcp mcp als Dep nachzieht. | `pip show fastmcp` → `mcp<2.0,>=1.24.0`. |
+| **A7** | Leichen: `mcp_old.py` (379 Zeilen), leere `example.py`, `app/web/`, `app/tmp/`, und `app/web/tmp/__init__py` **ohne Punkt** im Dateinamen. | Datei-Inspektion. |
+| **A8** | `.pyfun`: `[MODEL.gemini-2.5-flash-lite]` wurde mit `[MODEL.gemini-2.0-flash-lite_END]` geschlossen (Parser toleriertes es, war aber falsch); doppelter Header-Kommentar. | Parser-Review. |
+| **A9** | `shellmaster.py` war nie verdrahtet — `initialize()` wurde von niemandem gerufen. | Import-Graph. |
+| **A10** | CRLF-Zeilenenden überall (Windows-Checkout). | `file`-Check: „with CRLF line terminators". |
+
+## 3. Fundament-Befunde (pyfun) — nur relevant mit `DATABASE_URL`
+
+| # | Befund | Status |
+|---|--------|--------|
+| **D1** | `UserHandler` erwartet ein SQLite-`Database`-Objekt (`fetchone`/`execute`, synchron) — `main.py` übergab aber den **asyncpg-Pool** → `AttributeError` beim ersten Login. | **Gefixt:** `main.py` baut jetzt `UserHandler(Database())` mit `setup_tables()` — exakt wie im `__main__`-Demo deines eigenen `user_handler.py`. |
+| **D2** | `Security.user_login()` awaited eine **synchrone** Methode → `TypeError: bool can't be awaited`. | **Gefixt:** `await` entfernt (UserHandler bleibt synchron/SQLite). |
+| **D3** | `Security.check_permission(user_id, name)` rief `has_permission(name)` mit 2 Argumenten auf, obwohl die Signatur nur 1 nimmt → `TypeError`. | **Gefixt:** `has_permission(permission_name, user_id=None)` — optionaler Override, rückwärtskompatibel. |
+| **D4** | `AccessControl()` wurde ohne `user_id` gebaut → Permission-Check wäre immer `False` gewesen. | **Mit D3 gelöst** (user_id kann pro Call übergeben werden). |
+| **D5** | Gemischte Stores: users/sessions in **SQLite**, Rollen/Permissions in **PostgreSQL**. | **Dokumentiert, nicht geändert** — das ist ein Design-Decision, die dir gehört. |
+| **D6** | `main.py` loggte „Database service initialized." obwohl `init_db_pool()` `None` zurückgab. | **Gefixt:** Rückgabewert wird geprüft, Warnung stattdessen. |
+
+> **Hinweis fürs PyFundaments-Repo:** D1–D4 sind im Boilerplate genauso drin. Die Fixes (`main.py`-Wiring, `security.py`-Signaturen, `access_control.py`-Override) kannst du 1:1 übernehmen.
+
+---
+
+## 4. Was im Rebuild passiert ist (Datei für Datei)
+
+### `app/app.py`
+- Mount-Middleware zurück auf Boilerplate-Logik: `prefixes`-Tuple, **kein Strip**, `strip_prefix` nur noch bewusster Opt-in.
+- `serve()` läuft jetzt in `async with mcp.lifespan():` — der FastMCP-Session-Manager lebt.
+- `mcp.mount_prefixes()` bestimmt die Prefixe (streamable-http → `/mcp`; sse → `/sse` + `/messages`).
+- `HUB_HOST` wird aus `.pyfun` gelesen (stand vorher auf `0.0.0.0` hardcoded).
+- `/api`: saubere Fehlercodes — `ValueError` → 400 (fehlender Prompt, unbekanntes Tool), `KeyError` → 404, `RuntimeError` → 502 (Provider-Kette erschöpft, Message upstream sanitisiert), kaputtes JSON crasht nicht.
+- `get_model_pricing` als REST-Tool direkt daneben.
+- `shellmaster.initialize()` + `pricing.initialize()` in die Startup-Sequenz.
+- Tote SSE-Quart-Route entfernt, ungenutzte Imports (`threading`, `requests`, `time`) raus, `datetime.utcnow()` (deprecated) → `datetime.now(timezone.utc)`.
+
+### `app/mcp.py`
+- `lifespan()` + `mount_prefixes()` zurück (mit dem WARUM-Kommentar aus dem Boilerplate).
+- Tote `handle_request()`/`handle_sse()` entfernt.
+- **Neu:** `_register_pricing_tools()` → `get_model_pricing` + `refresh_pricing`.
+- `get_model_info` ist jetzt async und liefert **gemergte** Kosten (.pyfun gewinnt, Auto-Werte füllen).
+- `_register_db_tools()` aktiviert — alle drei im Kommentar genannten Bedingungen sind erfüllt.
+- `list_active_tools` zeigt jetzt `pricing_stats`.
+
+### `app/pricing.py` — **NEU** (dein Schmerzpunkt)
+- **Das Problem:** Nicht jeder Anbieter hat eine Pricing-API (Anthropic & Google: keine). Kosten von Hand in `[MODELS]` pflegen nervt.
+- **Die Lösung:** Zwei freie, öffentliche Quellen + deine `.pyfun` als Override:
+
+| Priorität | Quelle | Deckt | Getestet |
+|-----------|--------|-------|----------|
+| 1 | `.pyfun [MODELS]` | Deine manuellen Werte — **gewinnen immer** | ✅ `claude-opus-4-6` → 0.015/0.075 $/1k aus deiner Config |
+| 2 | OpenRouter `/api/v1/models` (öffentlich, kein Key) | Alle OR-Modelle, per-Token-Preise, Context-Längen | ✅ 465 Modelle live geholt |
+| 3 | LiteLLM `model_prices_and_context_window.json` (Community-Standard) | Anthropic, Gemini, OpenAI, Mistral, … | ✅ 4615 Modelle live geholt |
+
+- **Merge-Logik:** `.pyfun` > OpenRouter > LiteLLM. Fehlt beides → `source: "unknown"`, kein Crash.
+- **Matching:** exakt normalisiert (lowercase, Vendor-Prefixe wie `anthropic/`, `gemini/` gestrippt) + Loose-Match gegen Punkt/Strich-Differenzen (OR schreibt `claude-opus-4.6`, du `claude-opus-4-6` — beides findet sich).
+- **Caching:** landet in `db_sync` (`hub_state["pricing.cache"]`), TTL aus `.pyfun` (Default 24 h). **Restart innerhalb der TTL = null externe Calls** (live getestet).
+- **Nicht-blockierend:** Fetch läuft als Background-Task — der Server startet sofort, auch wenn beide Quellen down sind.
+- **MCP/REST:** `get_model_pricing(model_name)` liefert alles gemergt; `refresh_pricing()` erzwingt den Refresh.
+
+### `app/providers.py`
+- **Neu:** `BaseSearchProvider` + `BraveSearchProvider` (Auth via `X-Subscription-Token`, **nicht** Bearer) + `TavilySearchProvider` (Key im Payload, `include_answer`-Support).
+- `_initialize_search()` mit demselben Key-Gating wie die LLMs: kein Key = Provider übersprungen = kein Crash.
+- `search()` mit Fallback-Kette via `fallback_to` (brave → tavily), mit Visited-Set gegen Endlosschleifen.
+- Fehler sanitisiert wie bei LLMs: nur HTTP-Status + safe_url, niemals Keys/Bodies.
+
+### `app/tools.py`
+- `prompt` jetzt optional + `**params`-Fänger → unbekannte Parameter crashen nicht mehr.
+- Fehlender Prompt → sauberer `ValueError` → 400.
+
+### `app/config.py`, `app/models.py`
+- `get_pricing()` für die neue `[PRICING]`-Sektion.
+- `models.get()` fällt auf die rohe `.pyfun` zurück, falls das Registry noch nicht initialisiert ist.
+
+### `app/.pyfun`
+- **Neu:** `[PRICING]`-Sektion (Enabled, TTL, beide Quell-URLs).
+- END-Marker-Fix + Doppel-Header entfernt.
+- `HUB_VERSION` → `1.1.0`.
+
+### `app/db_sync.py`, `app/shellmaster.py`
+- Unverändert bzw. nur verdrahtet — beide waren solide gebaut.
+- ShellMaster bleibt **inactive** in `.pyfun` bis Token + `shellmaster_commands.jsonl` + Agent-URL da sind.
+
+### `fundaments/` (minimal)
+- `security.py`: D2 + D3 (siehe oben).
+- `access_control.py`: D3-Override.
+- `main.py` (Guardian): D1-Wiring + D6-Log.
+- Sonst **keine** Änderungen — dein Fundament bleibt deins.
+
+### Projekt
+- Entfernt: `mcp_old.py`, `example.py`, `app/web/`, `app/tmp/`.
+- `requirements.txt`: `fastmcp` → `mcp>=1.10,<2`.
+- `Dockerfile`: `EXPOSE 7860`.
+- `example-mcp___.env`: aufgeräumt (stale `APP_MODE`/`MCP_TRANSPORT` raus, alle Provider-Keys dokumentiert).
+- Alle Dateien auf LF normalisiert (40 Dateien, CRLF kam aus dem Windows-Checkout).
+
+---
+
+## 5. Live-Test-Ergebnisse (alle bestanden)
+
+```
+✅ Boot ohne ENV-Keys          → Server startet, 3 System-Tools, kein Crash
+✅ Boot mit Dummy-Keys         → anthropic + brave registrieren sich, 8 Tools
+✅ MCP initialize              → JSON-RPC Response mit serverInfo
+✅ MCP tools/list              → 8 Tools
+✅ MCP tools/call (pricing)    → gemini-2.5-flash: .pyfun-Werte gewinnen
+✅ MCP tools/call (db_query)   → SELECT auf hub_state funktioniert
+✅ Pricing-Quellen             → OpenRouter 465 + LiteLLM 4615 Modelle live
+✅ Pricing-Lookup              → .pyfun-Override ✅ / Auto-Fill ✅ / Unknown ✅
+✅ Cache-TTL                   → Restart: „cache fresh — no external fetch needed"
+✅ Fallback-Kette              → anthropic 403 → Kette durch → RuntimeError, KEIN Key im Log
+✅ /api Fehlerpffade           → fehlender Prompt 400, unbekanntes Tool 400,
+                                 Schreib-SQL blockiert, kaputtes JSON 400
+```
+
+---
+
+## 6. Wie du weitermachst
+
+```bash
+# 1. .env anlegen
+cp example-mcp___.env .env   # dann Keys eintragen
+
+# 2. Starten
+python main.py
+
+# 3. Kosten abfragen (macht jetzt der Hub selbst)
+curl -X POST localhost:7860/api -H "Content-Type: application/json" \
+  -d '{"tool":"get_model_pricing","params":{"model_name":"gemini-2.5-flash"}}'
+
+# 4. Preise erzwingen zu aktualisieren
+curl -X POST localhost:7860/api -H "Content-Type: application/json" \
+  -d '{"tool":"refresh_pricing"}'
+```
+
+**Du kannst in `.pyfun [MODELS]` jetzt alle `cost_*`-Zeilen löschen** — sie werden automatisch gefüllt. Einträge, die du setzt, gewinnen weiterhin als Override (z. B. wenn du Sonderkonditionen hast).
+
+**Nächste sinnvolle Schritte:** echte Keys testen · `persist_result` mit echter PostgreSQL-Tabelle · ShellMaster aktivieren (Token + Registry-Datei + Agent) · Auth-Layer vor `/api` und `/mcp` legen.
+
+---
+
+## 7. Debug- & Secrets-Audit (nachgetragen am 10.11.2026)
+
+**Anlass:** Nutzer-Hinweis auf die Debug-Einstellungen in `.pyfun` und `.env` — die fehlte im ersten Review. Nachgetragen, mit Beweis.
+
+### Secrets — wo auch immer gesucht, nichts gefunden
+
+| Prüfung | Ergebnis | Beweis |
+|---------|----------|--------|
+| Echte API-Keys im Work-Tree | ✅ keine | `.pyfun` enthält nur ENV-**Namen** (`env_key = "ANTHROPIC_API_KEY"`), `shellmaster_token = ""` |
+| Echte API-Keys in **gesamter Git-History** (~30 Commits) | ✅ keine | Alle Muster-Treffer sind `...`-Platzhalter in Doku-Kommentaren (`sk-ant-...`, `hf_...`, `BSA...`, `tvly-...`) |
+| `.env` je committed | ✅ nein | `git log --all --diff-filter=A` — nur `example-mcp___.env` (Platzhalter) |
+| Logs über HTTP ausgeliefert | ✅ nein | `app.py` hat nur `/`, `/api`, `/crypto` — keine Log-Route |
+| Prompts/Responses/Bodies in Logs | ✅ nein | `grep` über alle `logger.*`-Aufrufe in `app/` — nur Status, Registrierungen, sanitized URLs |
+
+### Debug-Schalter — wer liest sie WIRKLICH?
+
+| Schalter | Wo gelesen | Default | Tatsächliche Wirkung |
+|----------|-----------|---------|---------------------|
+| `PYFUNDAMENTS_DEBUG` | `.env` → `main.py` + `fundaments/debug.py` | `false` | Startup-Diagnose (Python-Version, `sys.path`, Datei-Checks) |
+| `LOG_LEVEL` | `.env` | `INFO` | Log-Tiefe |
+| `LOG_TO_TMP` | `.env` | `false` | Logs nach `/tmp` (nur Host-lokal, nicht öffentlich) |
+| `ENABLE_PUBLIC_LOGS` | `.env` | **`true`** | `false` = nur CRITICAL. **Achtung HF Spaces:** stdout-Logs sind dort im Log-Tab **öffentlich einsehbar** — für öffentliche Spaces `false` setzen |
+| `.pyfun [DEBUG]`-Sektion | **niemand** | — | **TOTE CONFIG** — kein `app/*`-Code liest sie (Stand v1.1.0, per `grep` über `app/` bewiesen) |
+
+### Was daraus bereinigt wurde
+
+- **`.pyfun [DEBUG]`**: Stand auf `DEBUG="ON"`, `DEBUG_LEVEL="FULL"`, `LOG_RESPONSES="true"` — wirkungslos heute, aber eine **Landmine**: wäre die Sektion später verdrahtet worden, hätte sie sofort sensitiv geloggt. Jetzt: `OFF`/`false`-Defaults + „not wired yet"-Hinweis im Header.
+- **`example-mcp___.env`**: shippte Dev-Defaults (`PYFUNDAMENTS_DEBUG="true"`, `LOG_LEVEL="DEBUG"`, `ENABLE_PUBLIC_LOGS="true"`). Template jetzt produktions-sicher (`false`/`INFO`/`false`) + Warnhinweis zum öffentlichen HF-Spaces-Log-Tab. Für die Testphase einfach in deiner lokalen `.env` umschalten.
+- **Nicht geändert (Empfehlung):** Der Code-Default `ENABLE_PUBLIC_LOGS=true` in `main.py`/`fundaments/debug.py`. Für öffentliche HF Spaces wäre `false` der sicherere Default — aber das ist dein Fundament, deine Entscheidung. Eindeutig dokumentiert in der `.env`-Vorlage.
+
+> **Wichtig fürs Verständnis:** Runtime-Verhalten hat sich durch die Bereinigung **nicht** geändert — die `[DEBUG]`-Sektion war tot, und die `.env`-Vorlage wirkt erst, wenn du sie kopierst. Geändert haben sich nur die Defaults, mit denen das Projekt ausgeliefert wird.
+
+---
+
+## 8. Update 2 (v1.2.0): Auto-Pricing konsequent, Gedächtnis-Orchestrierung, ShellMaster ROT
+
+### 8.1 Die Pricing-Frage: Brauchen wir `[MODELS]`-Kosten noch?
+
+**Antwort auf die OpenRouter-Frage (belegt, OpenRouter-FAQ live):**
+> *„We charge a small fee when purchasing credits. We never mark-up the pricing of the underlying providers, and you'll always pay the same as the provider's listed price."*
+
+- **Per-Token = Original-Listenpreis.** Kein Markup. Du irrst dich NICHT.
+- **ABER:** ~5,5 % Gebühr beim **Kredit-Kauf** (Stripe, $0,80 Min; Coinbase 5 %) — effektiv also Listenpreis + Kaufgebühr, nicht pro Token.
+- Wer mit eigenem `ANTHROPIC_API_KEY` direkt callt, zahlt ohnehin Vendor-Listenpreis → gleiche Zahlen.
+
+**Konsequenz umgesetzt:** 34 `cost_*`-Zeilen aus `[MODELS]` entfernt. Übrig bleiben nur die 4 Zeilen der Custom-Modelle (`smollm2-360m`, `codey-lab/...` = eigenes Deployment, 0.0 ist dort die Wahrheit — keine externe Quelle kennt sie). **Die Sektion selbst bleibt** — `requests_per_min/day`, `context_tokens`, `capabilities` und das Provider-Mapping gibt es in keiner Preisquelle.
+
+**Live bewiesen (26/26 Checks):** Alle 17 übrigen Modelle füllen Kosten automatisch:
+`claude-*` → litellm (z. B. opus 0.005/0.025 $/1k) · `gemini-3.*-preview` → openrouter · `mistral-7b` → litellm (**OpenRouter hat es aus dem Katalog genommen** — der Fallback greift genau richtig) · `smollm2-360m` → pyfun/0.0 · unbekannt → unknown.
+
+> ⚠️ Beachte: `claude-opus-4-6` zeigt jetzt **0.005/0.025** (LiteLLM) statt deiner alten 0.015/0.075. Prüfe das gegen deine echte Rechnung — falls du andere Konditionen hast, einfach die `cost_*`-Zeilen für DIESES Modell wieder eintragen (Override gewinnt immer).
+
+**Kleiner Fix nebenbei:** `.pyfun`-Kosten kamen als String (`"0.00000"`), Auto-Werte als Float — `get_pricing()` normalisiert jetzt alles auf Float. Und `/api list_active_tools` liefert jetzt auch `pricing_stats` (vorher nur die MCP-Version).
+
+### 8.2 Gedächtnis-Orchestrierung — dein Architektur-Wunsch, umgesetzt
+
+**Dein Design:** SQLite = Kurzzeit-Gedächtnis (alle KI-Tools lesen/schreiben) · Wichtiges → PostgreSQL = Dauer-Gedächtnis · Auswahl was wichtig ist = **dein** Bullshit-Filter (deine Sache).
+
+```
+persist_result (MCP + /api)
+   ↓ enqueue_persist()        ← sofort, IMMER, kein Crash
+persist_queue (SQLite)        ← überlebt Restarts (BEWIESEN: 3 vor, 3 nach Reboot)
+   ↓ flush_persist_queue()    ← Background-Flusher, Retry alle 60 s (config)
+PostgreSQL hub_results        ← CREATE TABLE IF NOT EXISTS + INSERT
+```
+
+| Eigenschaft | Umsetzung |
+|---|---|
+| Ohne `DATABASE_URL` | `status: "queued"` statt RuntimeError/502 — **kein Crash mehr** (vorher Befund!) |
+| PG temporär weg | Eintrag bleibt, `attempts`+1, sanitisierter `last_error` (nur Exception-Typ) |
+| PG wieder da | Flusher (5 s nach Boot, dann Intervall) holt alles nach |
+| Schema | `hub_results(id, created_at, source, model, score, payload JSONB)` |
+| **Score-Slot** | `score REAL` — Spalte + Parameter durchgereicht bis PostgreSQL, **uninterpretiert**. Dein Filter schreibt später einfach mit `score` mit oder filtert beim Lesen. Kein Hub-Code rührt ihn an. |
+| Observability | `persist_status` (MCP + /api): queue_depth, ältester Eintrag, Fehlversuche, Bridge-Status |
+| Grenzen | Queue max. 500 (älteste fliegen raus, wie `tool_cache`) · at-least-once (Duplikat statt Verlust) · HF Spaces: `/tmp`-SQLite überlebt Container-Reset nicht — dort ist PG das einzige Dauer-Gedächtnis |
+
+**Live bewiesen:** queued ohne PG ✅ · score 0.85 + source + model landen korrekt ✅ · `db_query` liest die Queue ✅ · MCP registriert `persist_result` + `persist_status` (8 Tools) ✅ · **Restart: 3 Einträge überleben** ✅
+
+### 8.3 ShellMaster = dein CLI-Commander — SECURITY LEVEL ROT
+
+Bestätigt, was du erkannt hast: Er ist für den **lokalen Quart-Agenten** gebaut (`localhost:5004`, Bearer-Token, Befehle auf DEINEM Rechner). Schutzmuster im Code: Hardblock-Liste (rm -rf, mkfs, …) + JSONL-Registry + **explizite Bestätigung** vor jeder Ausführung + Recovery-Plan im Gedächtnis.
+
+Trotzdem gilt: **Stufe rot, nur lokal.** Dokumentiert in `.pyfun` (Kommentar-Block über `[TOOL.shellmaster]`). Zusätzlich entschärft: Token-Field in `.pyfun` war eine Einladung, ein Secret in die Config zu legen — jetzt gibt es `shellmaster_env_key = "SHELLMASTER_TOKEN"` (→ `.env`, exakt wie bei allen Providern), das `.pyfun`-Feld ist nur noch lokaler Test-Fallback. `active` bleibt `"false"`.
+
+---
+
+*Rebuild nach PyFundaments-Architektur: Guardian → Orchestrator → sandboxes app/* · No key = no tool = no crash.*

app/.pyfun

@@ -0,0 +1,561 @@
+# =============================================================================
+# .pyfun — PyFundaments App Configuration
+# Single source of truth for app/* modules (provider, models, tools, hub)
+# Part of: Universal MCP Hub on PyFundaments
+# =============================================================================
+# RULES:
+#   - All values in double quotes "value"
+#   - NO secrets here! Keys stay in .env → only ENV-VAR NAMES referenced here
+#   - Comment-out unused sections with #  → keep structure, parsers need it!
+#   - DO NOT DELETE headers or [X_END]   → parsers rely on these markers
+#   - Empty/unused values: ""            → never leave bare =
+# =============================================================================
+# TIERS:
+#   LAZY:       fill [HUB] + one [LLM_PROVIDER.*] only        → works
+#   NORMAL:     + [SEARCH_PROVIDER.*] + [MODELS.*]             → works better
+#   PRODUCTIVE: + [TOOLS] + [FALLBACK] + [HUB_LIMITS]          → full power
+# =============================================================================
+# DO NOT DELETE — file identifier used by all parsers
+[PYFUN_FILE = .pyfun]
+
+# =============================================================================
+# HUB — Core identity & transport config
+# =============================================================================
+[HUB]
+HUB_NAME            = "Multi-LLM-API-Gateway"
+HUB_VERSION         = "1.2.0"
+HUB_DESCRIPTION     = "Universal Hub built on PyFundaments"
+
+# Transport: sse (legacy/HF Spaces fallback) | streamable-http (MCP spec 2025-11-25)
+HUB_TRANSPORT       = "streamable-http"
+
+# Stateless: true = HF Spaces + horizontal scaling safe
+# false = nur wenn du Server-initiated Notifications brauchst
+HUB_STATELESS       = "true"
+
+HUB_HOST            = "0.0.0.0"
+HUB_PORT            = "7860"
+HUB_MODE            = "mcp"
+HUB_SPACE_URL       = ""
+[HUB_END]
+
+# =============================================================================
+# HUB_LIMITS — Request & retry behavior
+# =============================================================================
+[HUB_LIMITS]
+MAX_PARALLEL_REQUESTS   = "5"
+RETRY_COUNT             = "3"
+RETRY_DELAY_SEC         = "2"
+REQUEST_TIMEOUT_SEC     = "60"
+SEARCH_TIMEOUT_SEC      = "30"
+[HUB_LIMITS_END]
+
+# =============================================================================
+# PROVIDERS — All external API providers
+# Secrets stay in .env! Only ENV-VAR NAMES are referenced here.
+# =============================================================================
+[PROVIDERS]
+
+# ── LLM Providers ─────────────────────────────────────────────────────────────
+[LLM_PROVIDERS]
+
+
+  #  customs LLM
+  [LLM_PROVIDER.smollm]
+  active        = "true"
+  base_url      = "https://codey-lab-smollm2-customs.hf.space/v1"
+  env_key       = "SMOLLM_API_KEY"
+  default_model = "smollm2-360m"
+  models        = "smollm2-360m, codey-lab/model.universal-mcp-hub"
+  fallback_to   = "gemini"
+  [LLM_PROVIDER.smollm_END]
+
+  # AI Wrapper
+
+  [LLM_PROVIDER.anthropic]
+  active              = "true"
+  base_url            = "https://api.anthropic.com/v1"
+  env_key             = "ANTHROPIC_API_KEY"
+  api_version_header  = "2023-06-01"
+  default_model       = "claude-haiku-4-5-20251001"
+  models              = "claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001"
+  supports_cache   = "true"
+  fallback_to         = "gemini"
+  [LLM_PROVIDER.anthropic_END]
+
+  [LLM_PROVIDER.gemini]
+  active        = "true"
+  base_url      = "https://generativelanguage.googleapis.com/v1beta"
+  env_key       = "GEMINI_API_KEY"
+  default_model = "gemini-2.5-flash"
+  models        = "gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3.1-flash-lite-preview, gemini-3-flash-preview, gemini-3.1-pro-preview"
+  supports_cache = "true"
+  fallback_to   = "openrouter"
+  [LLM_PROVIDER.gemini_END]
+
+  [LLM_PROVIDER.openrouter]
+  active              = "true"
+  base_url            = "https://openrouter.ai/api/v1"
+  env_key             = "OPENROUTER_API_KEY"      # → .env: OPENROUTER_API_KEY=sk-or-...
+  default_model       = "nvidia/nemotron-nano-9b-v2:free"
+  models              = "meta-llama/llama-3-8b-instruct, mistralai/mistral-7b-instruct, nvidia/nemotron-nano-9b-v2:free, google/gemma-3-27b-it:free, openai/gpt-oss-20b:free, mistralai/Mistral-7B-Instruct-v0.3, meta-llama/Llama-3.3-70B-Instruct"
+  fallback_to         = "huggingface"                      
+  [LLM_PROVIDER.openrouter_END]
+
+  [LLM_PROVIDER.huggingface]
+  active             = "true"
+  base_url           = "https://api-inference.huggingface.co/v1"
+  env_key            = "HF_TOKEN"                # → .env: HF_TOKEN=hf_...
+  default_model = "Qwen/Qwen2.5-Coder-32B-Instruct"
+  models        = "Qwen/Qwen2.5-Coder-32B-Instruct, meta-llama/Llama-3.1-8B-Instruct, mistralai/Mistral-Nemo-Instruct-2407, Qwen/Qwen2.5-72B-Instruct"
+  
+  fallback_to        = "smollm" # ← last in chain, no further fallback
+  [LLM_PROVIDER.huggingface_END]
+
+  # ── Add more LLM providers below ──────────────────────────────────────────
+  # [LLM_PROVIDER.mistral]
+  # active            = "false"
+  # base_url          = "https://api.mistral.ai/v1"
+  # env_key           = "MISTRAL_API_KEY"
+  # default_model     = "mistral-large-latest"
+  # models            = "mistral-large-latest, mistral-small-latest"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.mistral_END]
+
+  # [LLM_PROVIDER.openai]
+  # active            = "false"
+  # base_url          = "https://api.openai.com/v1"
+  # env_key           = "OPENAI_API_KEY"
+  # default_model     = "gpt-4o"
+  # models            = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.openai_END]
+
+[LLM_PROVIDERS_END]
+
+# ── Search Providers ───────────────────────────────────────────────────────────
+[SEARCH_PROVIDERS]
+
+  [SEARCH_PROVIDER.brave]
+  active              = "true"
+  base_url            = "https://api.search.brave.com/res/v1/web/search"
+  env_key             = "BRAVE_API_KEY"           # → .env: BRAVE_API_KEY=BSA...
+  default_results     = "5"
+  max_results         = "20"
+  fallback_to         = "tavily"
+  [SEARCH_PROVIDER.brave_END]
+
+  [SEARCH_PROVIDER.tavily]
+  active              = "true"
+  base_url            = "https://api.tavily.com/search"
+  env_key             = "TAVILY_API_KEY"          # → .env: TAVILY_API_KEY=tvly-...
+  default_results     = "5"
+  max_results         = "10"
+  include_answer      = "true"                    # AI-synthesized answer
+  fallback_to         = ""
+  [SEARCH_PROVIDER.tavily_END]
+
+  # ── Add more search providers below ───────────────────────────────────────
+  # [SEARCH_PROVIDER.serper]
+  # active            = "false"
+  # base_url          = "https://google.serper.dev/search"
+  # env_key           = "SERPER_API_KEY"
+  # fallback_to       = ""
+  # [SEARCH_PROVIDER.serper_END]
+
+[SEARCH_PROVIDERS_END]
+
+# ── Web / Action Providers (Webhooks, Bots, Social) ───────────────────────────
+# [WEB_PROVIDERS]
+
+  # [WEB_PROVIDER.discord]
+  # active            = "false"
+  # base_url          = "https://discord.com/api/v10"
+  # env_key           = "BOT_TOKEN"
+  # [WEB_PROVIDER.discord_END]
+
+  # [WEB_PROVIDER.github]
+  # active            = "false"
+  # base_url          = "https://api.github.com"
+  # env_key           = "GITHUB_TOKEN"
+  # [WEB_PROVIDER.github_END]
+
+# [WEB_PROVIDERS_END]
+
+[PROVIDERS_END]
+
+# =============================================================================
+# MODELS — Token & rate limits per model
+# Parser builds: MODELS[provider][model_name] → limits dict
+# COSTS: cost_*-Zeilen sind seit v1.1 OPTIONAL — [PRICING] füllt sie automatisch
+# aus OpenRouter + LiteLLM nach (OR markiert nie auf: per-Token = Vendor-
+# Listenpreis; ~5.5% Gebühr fällt nur beim Kredit-Kauf an, nicht pro Token).
+# Deine manuellen cost_* gewinnen IMMER als Override — sinnvoll für eigene
+# Deployments (smollm = 0.0, weil eigener Server) und Sonderkonditionen.
+# =============================================================================
+[MODELS]
+
+  [MODEL.claude-opus-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "32000"
+  requests_per_min    = "5"
+  requests_per_day    = "300"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-opus-4-6_END]
+
+  [MODEL.claude-sonnet-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "16000"
+  requests_per_min    = "50"
+  requests_per_day    = "1000"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-sonnet-4-6_END]
+
+  [MODEL.claude-haiku-4-5-20251001]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "8000"
+  requests_per_min    = "50"
+  requests_per_day    = "2000"
+  capabilities        = "text, code, fast"
+  [MODEL.claude-haiku-4-5-20251001_END]
+
+  [MODEL.gemini-3.1-flash-lite-preview]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1000"
+  capabilities        = "text, code, vision, fast, cheap"
+  [MODEL.gemini-3.1-flash-lite-preview_END]
+
+  [MODEL.gemini-3-flash-preview]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "10"
+  requests_per_day    = "1000"
+  capabilities        = "text, code, vision, audio, frontier"
+  [MODEL.gemini-3-flash-preview_END]
+
+  [MODEL.gemini-3.1-pro-preview]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "64000"
+  requests_per_min    = "5"
+  requests_per_day    = "1000"
+  capabilities        = "text, code, vision, audio, reasoning, agents"
+  [MODEL.gemini-3.1-pro-preview_END]
+
+  [MODEL.gemini-2.5-flash]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1500"
+  capabilities        = "text, code, vision, audio"
+  [MODEL.gemini-2.5-flash_END]
+
+  [MODEL.gemini-2.5-flash-lite]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1500"
+  capabilities        = "text, code, vision, audio"
+  [MODEL.gemini-2.5-flash-lite_END]
+
+
+  [MODEL.gemini-2.0-flash]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1500"
+  capabilities        = "text, code, vision, audio"
+  [MODEL.gemini-2.0-flash_END]
+
+  
+  [MODEL.mistral-7b-instruct]
+  provider            = "openrouter"
+  context_tokens      = "32000"
+  max_output_tokens   = "4096"
+  requests_per_min    = "60"
+  requests_per_day    = "10000"
+  capabilities        = "text, code, fast, cheap"
+  [MODEL.mistral-7b-instruct_END]
+  
+  [MODEL.dolphin-mistral-24b-venice-edition]
+  provider            = "openrouter"
+  context_tokens      = "32768"
+  max_output_tokens   = "4096"
+  requests_per_min    = ""
+  requests_per_day    = ""
+  capabilities        = "uncensored, text, code, fast, very cheap"
+  [MODEL.dolphin-mistral-24b-venice-edition_END]
+
+  [MODEL.nvidia-nemotron-nano-9b-v2]
+  provider            = "openrouter"
+  context_tokens      = "131072"
+  max_output_tokens   = "4096"
+  requests_per_min    = ""
+  requests_per_day    = ""
+  capabilities        = "text, code, reasoning, fast, free"
+  [MODEL.nvidia-nemotron-nano-9b-v2_END]
+
+  [MODEL.gemma-3-27b-it]
+  provider            = "openrouter"
+  context_tokens      = "131072"
+  max_output_tokens   = "8192"
+  requests_per_min    = ""
+  requests_per_day    = ""
+  capabilities        = "text, code, vision, multilingual, free"
+  [MODEL.gemma-3-27b-it_END]
+
+  [MODEL.gpt-oss-20b]
+  provider            = "openrouter"
+  context_tokens      = "128000"
+  max_output_tokens   = "4096"
+  requests_per_min    = ""
+  requests_per_day    = ""
+  capabilities        = "text, code, free"
+  [MODEL.gpt-oss-20b_END]
+
+  [MODEL.deephermes-3-llama-3-8b-preview]
+  provider            = "openrouter"
+  context_tokens      = "131072"
+  max_output_tokens   = "4096"
+  requests_per_min    = ""
+  requests_per_day    = ""
+  capabilities        = "text, code, reasoning, uncensored, free"
+  [MODEL.deephermes-3-llama-3-8b-preview_END]
+
+  [MODEL.Mistral-7B-Instruct-v0.3]
+  provider            = "openrouter"
+  context_tokens      = "32768"
+  max_output_tokens   = "4096"
+  requests_per_min    = "60"
+  requests_per_day    = "10000"
+  capabilities        = "text, code, fast, cheap"
+  [MODEL.Mistral-7B-Instruct-v0.3_END]
+
+  [MODEL.Llama-3.3-70B-Instruct]
+  provider            = "openrouter"
+  context_tokens      = "131072"
+  max_output_tokens   = "8192"
+  requests_per_min    = "60"
+  requests_per_day    = "10000"
+  capabilities        = "text, code, reasoning, multilingual"
+  [MODEL.Llama-3.3-70B-Instruct_END]
+
+  # customs llms
+  [MODEL.smollm2-360m]
+  provider           = "smollm"
+  context_tokens     = "8192"
+  max_output_tokens  = "300"
+  requests_per_min   = "60"
+  requests_per_day   = "10000"
+  cost_input_per_1k  = "0.00000"
+  cost_output_per_1k = "0.00000"
+  capabilities       = "text, assistant, navigation, free, local"
+  [MODEL.smollm2-360m_END]
+
+  [MODEL.codey-lab/model.universal-mcp-hub]
+  provider           = "smollm"
+  context_tokens     = "8192"
+  max_output_tokens  = "300"
+  requests_per_min   = "60"
+  requests_per_day   = "10000"
+  cost_input_per_1k  = "0.00000"
+  cost_output_per_1k = "0.00000"
+  capabilities       = "text, assistant, navigation, free, custom, finetuned"
+  [MODEL.codey-lab/model.universal-mcp-hub_END]
+
+[MODELS_END]
+
+# =============================================================================
+# TOOLS — Tool definitions + provider mapping
+# Tools are registered in mcp.py only if their provider ENV key exists!
+# =============================================================================
+[TOOLS]
+
+  [TOOL.llm_complete]
+  active              = "true"
+  description         = "Send prompt to any configured LLM provider"
+  provider_type       = "llm"
+  default_provider    = "anthropic"
+  timeout_sec         = "60"
+  system_prompt       = "You are a helpful assistant integrated into the Universal MCP Hub. Answer concisely and only what is asked."
+  [TOOL.llm_complete_END]
+
+  [TOOL.code_review]
+  active              = "true"
+  description         = "Review code for bugs, security issues and improvements"
+  provider_type       = "llm"
+  default_provider    = "anthropic"
+  timeout_sec         = "60"
+  system_prompt       = "You are an expert code reviewer. Analyze the given code for bugs, security issues, and improvements. Be specific and concise."
+  [TOOL.code_review_END]
+
+  [TOOL.summarize]
+  active              = "true"
+  description         = "Summarize text into concise bullet points"
+  provider_type       = "llm"
+  default_provider    = "gemini"
+  timeout_sec         = "30"
+  system_prompt       = "You are a summarization expert. Summarize the given text in 3-5 bullet points. Be concise and accurate."
+  [TOOL.summarize_END]
+
+  [TOOL.translate]
+  active              = "true"
+  description         = "Translate text — auto-detects source language"
+  provider_type       = "llm"
+  default_provider    = "gemini"
+  timeout_sec         = "30"
+  system_prompt       = "You are a professional translator. Translate the given text accurately. Auto-detect the source language. Output only the translation, no explanation."
+  [TOOL.translate_END]
+
+  [TOOL.web_search]
+  active              = "true"
+  description         = "Search the web via configured search provider"
+  provider_type       = "search"
+  default_provider    = "brave"
+  timeout_sec         = "30"
+  [TOOL.web_search_END]
+
+  [TOOL.db_query]
+  active              = "true"
+  description         = "Execute SELECT queries on connected database (read-only)"
+  provider_type       = "db"
+  readonly            = "true"
+  timeout_sec         = "10"
+  [TOOL.db_query_END]
+
+  [TOOL.persist_result]
+  active           = "true"
+  description      = "Persist important results to long-term memory (PostgreSQL) — restart-safe queue in SQLite, flushes automatically"
+  provider_type    = "persist"
+  state_read_key   = ""          # welcher hub_state Key → leer = prompt direkt
+  target_table     = "hub_results"
+  timeout_sec      = "10"
+  # score-Parameter (optional, float) = reservierter Slot fuer den
+  # Bullshit-Filter — wird unverarbeitet durchgereicht und landet als
+  # eigene Spalte in PostgreSQL. Filter/Scoring baust DU, nicht der Hub.
+  [TOOL.persist_result_END]
+
+  # ── Future tools ──────────────────────────────────────────────────────────
+  # [TOOL.image_gen]
+  # active            = "false"
+  # description       = "Generate images via configured provider"
+  # provider_type     = "image"
+  # default_provider  = ""
+  # timeout_sec       = "120"
+  # [TOOL.image_gen_END]
+
+  # [TOOL.code_exec]
+  # active            = "false"
+  # description       = "Execute sandboxed code snippets"
+  # provider_type     = "sandbox"
+  # timeout_sec       = "30"
+  # [TOOL.code_exec_END]
+
+  # ── Shellmaster 2.0 ──────────────────────────────────────────────────────────
+  # SECURITY LEVEL: ROT — dein CLI-Commander. LLM generiert → Hardblock+
+  # Registry-Check → DEINE Bestätigung → Ausführung auf DEINEM lokalen
+  # Rechner (Agent :5004). NUR lokal — NIEMALS auf öffentlichen HF Spaces
+  # aktivieren! Token gehört in .env (shellmaster_env_key), nicht hierher.
+  [TOOL.shellmaster]
+  active                       = "false"
+  shellmaster_agent_url        = "http://localhost:5004"
+  shellmaster_env_key          = "SHELLMASTER_TOKEN"   # → .env, wie bei allen Providern
+  shellmaster_token            = ""                    # Fallback nur für lokale Tests
+  description                  = "AI-powered shell assistant — generates and executes safe shell commands"
+  provider_type                = "llm"
+  default_provider             = "smollm"
+  timeout_sec                  = "30"
+  shellmaster_commands_file    = "shellmaster_commands.jsonl"
+  shellmaster_commands_dataset = ""
+  shellmaster_customs_model    = ""
+  system_prompt                = "You are ShellMaster. Generate safe shell commands for the requested task. Output ONLY valid JSON: {\"command\": \"cmd here\", \"backup\": \"backup cmd or empty\", \"recovery\": \"recovery cmd or empty\", \"risk\": \"low|medium|high\"}"
+  [TOOL.shellmaster_END]
+
+  [TOOL.shellmaster_confirm]
+  active      = "false"
+  description = "Confirm and execute the last ShellMaster command — runs backup first"
+  [TOOL.shellmaster_confirm_END]
+
+  [TOOL.shellmaster_recover]
+  active      = "false"
+  description = "Execute recovery plan for last ShellMaster command"
+  [TOOL.shellmaster_recover_END]
+
+  [TOOL.shellmaster_commands]
+  active      = "false"
+  description = "List allowed ShellMaster commands from registry"
+  [TOOL.shellmaster_commands_END]
+
+[TOOLS_END]
+
+# =============================================================================
+# DB_SYNC — Internal SQLite config for app/* IPC
+# This is NOT the cloud DB — that lives in .env → DATABASE_URL
+# =============================================================================
+[DB_SYNC]
+SQLITE_PATH         = "app/.hub_state.db"       # internal state, never commit!
+SYNC_INTERVAL_SEC   = "30"                       # how often to flush to SQLite
+MAX_CACHE_ENTRIES   = "1000"
+PERSIST_QUEUE_MAX   = "500"                      # restart-safe queue: SQLite → PostgreSQL
+PERSIST_FLUSH_INTERVAL_SEC = "60"                # retry interval for the PG flusher
+[DB_SYNC_END]
+
+# =============================================================================
+# PRICING — Auto model costs (OpenRouter + LiteLLM)
+# WHY: not every provider has a pricing API (Anthropic/Google: none).
+# These two public sources fill cost_input_per_1k / cost_output_per_1k
+# automatically. Your [MODELS] values ALWAYS win as override.
+# Cache lives in db_sync hub_state, TTL-gated (default 24h).
+# =============================================================================
+[PRICING]
+PRICING_ENABLED       = "true"
+PRICING_TTL_HOURS     = "24"
+OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models"
+LITELLM_PRICES_URL    = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+[PRICING_END]
+
+# =============================================================================
+# DEBUG — app/* debug behavior (fundaments debug stays in .env)
+# NOTE (v1.1.0): This section is NOT YET WIRED — no app/* code reads it.
+# Real debug switches live in .env: PYFUNDAMENTS_DEBUG / LOG_LEVEL /
+# LOG_TO_TMP / ENABLE_PUBLIC_LOGS (see example-mcp___.env).
+# Defaults below are SAFE (OFF) so wiring this later cannot leak data.
+# =============================================================================
+[DEBUG]
+DEBUG               = "OFF"                       # ON | OFF (not wired yet)
+DEBUG_LEVEL         = "WARN"                      # FULL | WARN | ERROR (not wired yet)
+LOG_FILE            = "hub_debug.log"             # (not wired yet)
+LOG_REQUESTS        = "false"                     # (not wired yet)
+LOG_RESPONSES       = "false"                     # (not wired yet — would log sensitive data!)
+[DEBUG_END]
+
+# =============================================================================
+# PARSER_PROVIDER FREE ENDPOINTS — soon
+# =============================================================================
+[PARSER_PROVIDER]
+#[PARSER_PROVIDER.metaculus]
+#active    = "true"
+#base_url  = "https://www.metaculus.com/api2"
+#env_key   = ""          # public API, kein key!
+#category  = "research"
+#legal_de  = "true"      # ← Deutschland-Check direkt in config!
+#[PARSER_PROVIDER.metaculus_END]
+
+#[PARSER_PROVIDER.polymarket]
+#active    = "false"
+#base_url  = "https://gamma-api.polymarket.com"
+#env_key   = ""
+#legal_de  = "false"
+#[PARSER_PROVIDER.polymarket_END]
+[PARSER_PROVIDER_END]
+

app/README.md

@@ -0,0 +1,2 @@
+> Haha! Sandboxed MCP server! (No nelson image cause big "D")
+

app/__init__.py

@@ -0,0 +1,7 @@
+# app/__init__.py
+#from . import config
+#from . import providers
+#from . import models
+#from . import tools
+#from . import db_sync
+#from . import mcp

app/app.py

@@ -0,0 +1,317 @@
+# =============================================================================
+# root/app/app.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file is the Orchestrator of the sandboxed app/* layer.
+#   It is ONLY started by main.py (the "Guardian").
+#   All fundament services are injected via the `fundaments` dictionary.
+#   Direct execution is blocked by design.
+#
+# SANDBOX RULES:
+#   - fundaments dict is ONLY unpacked inside start_application()
+#   - fundaments are NEVER stored globally or passed to other app/* modules
+#   - app/* modules read their own config from app/.pyfun
+#   - app/* internal state/IPC uses app/db_sync.py (SQLite) — NOT postgresql.py
+#   - Secrets stay in .env → Guardian reads them → never touched by app/*
+# =============================================================================
+from quart import Quart, request, jsonify  # async Flask — ASGI compatible
+import logging
+from hypercorn.asyncio import serve        # ASGI server — async native, replaces waitress
+from hypercorn.config import Config        # hypercorn config
+from datetime import datetime, timezone
+import asyncio
+from typing import Dict, Any
+# =============================================================================
+# Import app/* modules — MINIMAL BUILD
+# Each module reads its own config from app/.pyfun independently.
+# NO fundaments passed into these modules!
+# =============================================================================
+from . import mcp                   # MCP transport layer (Streamable HTTP / SSE via ASGI mount)
+from . import config as app_config  # app/.pyfun parser — used only in app/*
+from . import providers    # API provider registry — reads app/.pyfun
+from . import models       # Model config + token/rate limits — reads app/.pyfun
+from . import pricing      # Auto model costs (OpenRouter + LiteLLM) — reads app/.pyfun
+from . import tools        # MCP tool definitions + provider mapping — reads app/.pyfun
+from . import db_sync      # Internal SQLite IPC — app/* state & communication
+from . import shellmaster  # ShellMaster 2.0 — safe shell assistant (inactive by default)
+#                          # db_sync ≠ postgresql.py! Cloud DB is Guardian-only.
+# Future modules (will uncomment when ready):
+# from . import discord_api  # Discord bot integration
+# from . import hf_hooks     # HuggingFace Space hooks
+# from . import git_hooks    # GitHub/GitLab webhook handler
+# from . import web_api      # Generic REST API handler
+# =============================================================================
+# Loggers — one per module for clean log filtering
+# =============================================================================
+logger        = logging.getLogger('application')
+logger_mcp    = logging.getLogger('mcp')
+logger_config = logging.getLogger('config')
+logger_tools     = logging.getLogger('tools')
+logger_providers = logging.getLogger('providers')
+logger_models    = logging.getLogger('models')
+logger_db_sync   = logging.getLogger('db_sync')
+
+
+
+# ── NEU: nach den Imports, vor app = Quart(__name__) ──────────────────────────
+
+def _make_mount_middleware(outer_app, prefixes, inner_app, strip_prefix: bool = False):
+    """
+    ASGI-Middleware: leitet Requests mit passendem Prefix an inner_app
+    (FastMCP Streamable HTTP / SSE) weiter, alles andere geht an outer_app (Quart).
+    Lifespan-Scopes gehen immer an outer_app (Quart).
+
+    WICHTIG: Prefix wird standardmaessig NICHT gestript - FastMCP registriert
+    seine Route intern selbst (settings.streamable_http_path = "/mcp").
+    Wer stript, erzeugt 404s. Genau das war der Break im alten Build.
+    """
+    async def middleware(scope, receive, send):
+        path = scope.get("path", "")
+        for prefix in prefixes:
+            if path == prefix or path.startswith(prefix + "/"):
+                if strip_prefix:
+                    scope = dict(scope)
+                    stripped = path[len(prefix):] or "/"
+                    scope["path"] = stripped
+                    scope["raw_path"] = stripped.encode()
+                await inner_app(scope, receive, send)
+                return
+        await outer_app(scope, receive, send)
+    return middleware
+
+# =============================================================================
+# Quart app instance
+# =============================================================================
+app = Quart(__name__)
+START_TIME = datetime.now(timezone.utc)
+# =============================================================================
+# Quart Routes
+# =============================================================================
+@app.route("/", methods=["GET"])
+async def health_check():
+    """
+    Health check endpoint.
+    Used by HuggingFace Spaces and monitoring systems to verify the app is running.
+    """
+    uptime = datetime.now(timezone.utc) - START_TIME
+    return jsonify({
+        "status": "running",
+        "service": "Universal MCP Hub",
+        "uptime_seconds": int(uptime.total_seconds()),
+    })
+
+
+@app.route("/api", methods=["POST"])
+async def api_endpoint():
+    """
+    REST tool gateway: POST {"tool": "name", "params": {...}}
+    Hook point: add auth / rate limiting here before dispatching.
+    """
+    try:
+        data      = await request.get_json(silent=True) or {}
+        tool_name = data.get("tool")
+        params    = data.get("params", {}) or {}
+
+        if not tool_name:
+            return jsonify({"error": "Missing 'tool'"}), 400
+
+        # System tools — handle directly, no prompt needed!
+        if tool_name == "list_active_tools":
+            return jsonify({"result": {
+                "active_tools":            tools.list_all(),
+                "active_llm_providers":    providers.list_active_llm(),
+                "active_search_providers": providers.list_active_search(),
+                "available_models":        models.list_all(),
+                "pricing_stats":           pricing.stats(),
+            }})
+
+        if tool_name == "health_check":
+            return jsonify({"result": {"status": "ok"}})
+
+        # db_query — handled by db_sync directly, not tools.run()
+        if tool_name == "db_query":
+            sql = params.get("sql", "") or params.get("prompt", "")
+            if not sql:
+                return jsonify({"error": "db_query requires 'sql' (or 'prompt') parameter"}), 400
+            result = await db_sync.query(sql)
+            return jsonify({"result": result})
+
+        # persist_status — memory orchestration observability (no prompt needed)
+        if tool_name == "persist_status":
+            return jsonify({"result": await db_sync.persist_queue_stats()})
+
+        # get_model_pricing — auto-fetched costs, .pyfun values win as override
+        if tool_name == "get_model_pricing":
+            model_name = params.get("model_name", "") or params.get("model", "")
+            if not model_name:
+                return jsonify({"error": "get_model_pricing requires 'model_name'"}), 400
+            result = await pricing.get_pricing(model_name)
+            return jsonify({"result": result})
+
+        # rename 'provider' → 'provider_name' for tools.run()
+        if "provider" in params:
+            params["provider_name"] = params.pop("provider")
+
+        result = await tools.run(tool_name, **params)
+        return jsonify({"result": result})
+
+    except ValueError as e:                    # unknown tool / missing prompt → 400
+        return jsonify({"error": str(e)}), 400
+    except KeyError as e:
+        return jsonify({"error": str(e.args[0])}), 404
+    except RuntimeError as e:
+        # Provider-Kette erschöpft — Message ist upstream sanitisiert
+        # (nur HTTP-Status + safe_url, niemals Keys/Bodies)
+        return jsonify({"error": str(e)}), 502
+    except Exception as e:
+        logger.error(f"API error: {type(e).__name__}: {e}")
+        return jsonify({"error": "Internal error"}), 500
+
+
+@app.route("/crypto", methods=["POST"])
+async def crypto_endpoint():
+    """
+    Encrypted API endpoint.
+    Encryption handled by app/* layer — no direct fundaments access here.
+    """
+    # TODO: implement via app/* encryption wrapper
+    data = await request.get_json()
+    return jsonify({"status": "not_implemented"}), 501
+
+
+# Future routes (uncomment when ready):
+# @app.route("/discord", methods=["POST"])
+# async def discord_interactions():
+#     """Discord interactions endpoint — signature verification via discord_api module."""
+#     pass
+
+# @app.route("/webhook/hf", methods=["POST"])
+# async def hf_webhook():
+#     """HuggingFace Space event hooks."""
+#     pass
+
+# @app.route("/webhook/git", methods=["POST"])
+# async def git_webhook():
+#     """GitHub / GitLab webhook handler."""
+#     pass
+# =============================================================================
+# Main entry point — called exclusively by Guardian (main.py)
+# =============================================================================
+async def start_application(fundaments: Dict[str, Any]) -> None:
+    """
+    Main entry point for the sandboxed app layer.
+    Called exclusively by main.py after all fundament services are initialized.
+
+    Args:
+        fundaments: Dictionary of initialized services from Guardian (main.py).
+                    Services are unpacked here and NEVER stored globally or
+                    passed into other app/* modules.
+    """
+    logger.info("Application starting...")
+
+    # =========================================================================
+    # Unpack fundaments — ONLY here, NEVER elsewhere in app/*
+    # These are the 6 fundament services from fundaments/*
+    # =========================================================================
+    config_service          = fundaments["config"]          # fundaments/config_handler.py
+    db_service              = fundaments["db"]              # fundaments/postgresql.py — None if not configured
+    encryption_service      = fundaments["encryption"]      # fundaments/encryption.py — None if keys not set
+    access_control_service  = fundaments["access_control"]  # fundaments/access_control.py — None if no DB
+    user_handler_service    = fundaments["user_handler"]    # fundaments/user_handler.py — None if no DB
+    security_service        = fundaments["security"]        # fundaments/security.py — None if deps missing
+
+    # --- Log active fundament services ---
+    if encryption_service:
+        logger.info("Encryption service active.")
+
+    if user_handler_service and security_service:
+        logger.info("Auth services active (user_handler + security).")
+
+    if access_control_service and security_service:
+        logger.info("Access control active.")
+
+    if db_service and not user_handler_service:
+        logger.info("Database-only mode active (e.g. ML pipeline).")
+
+    if not db_service:
+        logger.info("Database-free mode active (e.g. Discord bot, API client).")
+
+    # =========================================================================
+    # Initialize app/* internal services — MINIMAL BUILD
+    # Each module reads its own config from app/.pyfun — no fundaments passed in.
+    # =========================================================================
+
+    # db_sync only if cloud_DB used to!
+    # PSQL bridge — nur wenn Guardian DB-Service injiziert hat
+    await db_sync.initialize()
+
+    if db_service:
+        # asyncpg Pool direkt nutzen — kein execute_secured_query nötig
+        db_sync.set_psql_writer(db_service.execute)
+        logger.info("PostgreSQL bridge active.")
+    else:
+        logger.info("PostgreSQL bridge inactive — no DATABASE_URL configured.")
+
+    # Memory-Orchestrierung: Retry-Flusher starten — läuft MIT und OHNE PG.
+    # Ohne Writer bleibt alles restart-safe in der SQLite-Queue liegen
+    # (persist_result ohne DATABASE_URL = queued, kein Crash).
+    db_sync.start_persist_flusher()
+
+    # ShellMaster — bleibt inaktiv, bis .pyfun [TOOL.shellmaster] active="true"
+    # UND token + commands-Datei vorhanden sind (siehe shellmaster.initialize)
+    await shellmaster.initialize()
+
+    # Auto-Pricing — füllt Kosten aus OpenRouter/LiteLLM nach, .pyfun gewinnt.
+    # Läuft im Hintergrund — blockiert den Start NICHT (no fetch = no crash).
+    await pricing.initialize()
+
+    await mcp.initialize()
+
+    # =========================================================================
+    # MCP: ASGI-App holen, DANACH mounten, DANACH lifespan starten
+    # (get_asgi_app() muss VOR mcp.lifespan() kommen — siehe mcp.py)
+    # =========================================================================
+    hub_cfg   = app_config.get_hub()
+    mcp_asgi  = mcp.get_asgi_app()
+    app.asgi_app = _make_mount_middleware(app.asgi_app, mcp.mount_prefixes(), mcp_asgi)
+    logger.info(f"MCP mounted: {', '.join(mcp.mount_prefixes())}")
+
+    # --- Read HOST/PORT from app/.pyfun [HUB] ---
+    host = hub_cfg.get("HUB_HOST", "0.0.0.0")
+    port = int(hub_cfg.get("HUB_PORT", "7860"))  # hub_cfg bereits gelesen
+
+    # --- Configure hypercorn ---
+    config = Config()
+    config.bind = [f"{host}:{port}"]
+
+    logger.info(f"Starting hypercorn on {host}:{port}...")
+
+    # --- Run hypercorn — blocks until shutdown ---
+    # mcp.lifespan() ist PFLICHT: startet den FastMCP Session-Manager.
+    # Ohne ihn schlägt jeder /mcp-Request mit
+    # 'Task group is not initialized' fehl.
+    async with mcp.lifespan():
+        logger.info("All services running.")
+        await serve(app, config)
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == '__main__':
+    print("WARNING: Running app.py directly. Fundament modules might not be correctly initialized.")
+    print("Please run 'python main.py' instead for proper initialization.")
+
+    test_fundaments = {
+        "config":           None,
+        "db":               None,
+        "encryption":       None,
+        "access_control":   None,
+        "user_handler":     None,
+        "security":         None,
+    }
+
+    asyncio.run(start_application(test_fundaments))

app/config.py

@@ -0,0 +1,298 @@
+# =============================================================================
+# app/config.py
+# .pyfun parser for app/* modules
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# USAGE in any app/* module:
+#   from . import config
+#   cfg = config.get()
+#   providers = cfg["LLM_PROVIDERS"]
+# =============================================================================
+# USAGE
+# in providers.py
+# from . import config
+
+# active = config.get_active_llm_providers()
+# → { "anthropic": { "base_url": "...", "env_key": "ANTHROPIC_API_KEY", ... }, ... }
+# =============================================================================
+# in models.py  
+# from . import config
+
+# anthropic_models = config.get_models_for_provider("anthropic")
+# =============================================================================
+# in tools.py
+# from . import config
+
+# active_tools = config.get_active_tools()
+# =============================================================================
+import os
+import logging
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger('app.config')
+
+# Path to .pyfun — lives in app/ next to this file
+PYFUN_PATH = os.path.join(os.path.dirname(__file__), ".pyfun")
+
+# Internal cache — loaded once at first get()
+_cache: Optional[Dict[str, Any]] = None
+
+
+def _parse_value(value: str) -> str:
+    """Strip quotes and inline comments from a value."""
+    value = value.strip()
+    # Remove inline comment
+    if " #" in value:
+        value = value[:value.index(" #")].strip()
+    # Strip surrounding quotes
+    if value.startswith('"') and value.endswith('"'):
+        value = value[1:-1]
+    return value
+
+
+def _parse() -> Dict[str, Any]:
+    """
+    Parses the app/.pyfun file into a nested dictionary.
+
+    Structure:
+        [SECTION]
+            [SUBSECTION]
+                [BLOCK.name]
+                key = "value"
+                [BLOCK.name_END]
+            [SUBSECTION_END]
+        [SECTION_END]
+
+    Returns nested dict:
+        {
+            "HUB": { "HUB_NAME": "...", ... },
+            "LLM_PROVIDERS": {
+                "anthropic": { "active": "true", "base_url": "...", ... },
+                "gemini":    { ... },
+            },
+            "MODELS": {
+                "claude-opus-4-6": { "provider": "anthropic", ... },
+            },
+            ...
+        }
+    """
+    if not os.path.isfile(PYFUN_PATH):
+        logger.critical(f".pyfun not found at: {PYFUN_PATH}")
+        raise FileNotFoundError(f".pyfun not found at: {PYFUN_PATH}")
+
+    result: Dict[str, Any] = {}
+
+    # Parser state
+    section: Optional[str]      = None   # e.g. "HUB", "PROVIDERS"
+    subsection: Optional[str]   = None   # e.g. "LLM_PROVIDERS"
+    block_type: Optional[str]   = None   # e.g. "LLM_PROVIDER", "MODEL", "TOOL"
+    block_name: Optional[str]   = None   # e.g. "anthropic", "claude-opus-4-6"
+
+    with open(PYFUN_PATH, "r", encoding="utf-8") as f:
+        for raw_line in f:
+            line = raw_line.strip()
+
+            # Skip empty lines and full-line comments
+            if not line or line.startswith("#"):
+                continue
+
+            # Skip file identifier
+            if line.startswith("[PYFUN_FILE"):
+                continue
+
+            # --- Block END markers (most specific first) ---
+            if line.endswith("_END]") and "." in line:
+                # e.g. [LLM_PROVIDER.anthropic_END] or [MODEL.claude-opus-4-6_END]
+                block_type = None
+                block_name = None
+                continue
+
+            if line.endswith("_END]") and not "." in line:
+                # e.g. [LLM_PROVIDERS_END], [HUB_END], [MODELS_END]
+                inner = line[1:-1].replace("_END", "")
+                if subsection and inner == subsection:
+                    subsection = None
+                elif section and inner == section:
+                    section = None
+                continue
+
+            # --- Block START markers ---
+            if line.startswith("[") and line.endswith("]"):
+                inner = line[1:-1]
+
+                # Named block: [LLM_PROVIDER.anthropic] or [MODEL.claude-opus-4-6]
+                if "." in inner:
+                    parts = inner.split(".", 1)
+                    block_type = parts[0]   # e.g. LLM_PROVIDER, MODEL, TOOL
+                    block_name = parts[1]   # e.g. anthropic, claude-opus-4-6
+
+                    # Determine which top-level key to store under
+                    if block_type == "LLM_PROVIDER":
+                        result.setdefault("LLM_PROVIDERS", {})
+                        result["LLM_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "SEARCH_PROVIDER":
+                        result.setdefault("SEARCH_PROVIDERS", {})
+                        result["SEARCH_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "WEB_PROVIDER":
+                        result.setdefault("WEB_PROVIDERS", {})
+                        result["WEB_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "MODEL":
+                        result.setdefault("MODELS", {})
+                        result["MODELS"].setdefault(block_name, {})
+                    elif block_type == "TOOL":
+                        result.setdefault("TOOLS", {})
+                        result["TOOLS"].setdefault(block_name, {})
+                    continue
+
+                # Subsection: [LLM_PROVIDERS], [SEARCH_PROVIDERS] etc.
+                if section and not subsection:
+                    subsection = inner
+                    result.setdefault(inner, {})
+                    continue
+
+                # Top-level section: [HUB], [PROVIDERS], [MODELS] etc.
+                section = inner
+                result.setdefault(inner, {})
+                continue
+
+            # --- Key = Value ---
+            if "=" in line:
+                key, _, val = line.partition("=")
+                key = key.strip()
+                val = _parse_value(val)
+
+                # Strip provider prefix from key (e.g. "anthropic.base_url" → "base_url")
+                if block_name and key.startswith(f"{block_name}."):
+                    key = key[len(block_name) + 1:]
+
+                # Store in correct location
+                if block_type and block_name:
+                    if block_type == "LLM_PROVIDER":
+                        result["LLM_PROVIDERS"][block_name][key] = val
+                    elif block_type == "SEARCH_PROVIDER":
+                        result["SEARCH_PROVIDERS"][block_name][key] = val
+                    elif block_type == "WEB_PROVIDER":
+                        result["WEB_PROVIDERS"][block_name][key] = val
+                    elif block_type == "MODEL":
+                        result["MODELS"][block_name][key] = val
+                    elif block_type == "TOOL":
+                        result["TOOLS"][block_name][key] = val
+                elif section:
+                    result[section][key] = val
+
+    logger.info(f".pyfun loaded. Sections: {list(result.keys())}")
+    return result
+
+
+def load() -> Dict[str, Any]:
+    """Force (re)load of .pyfun — clears cache."""
+    global _cache
+    _cache = _parse()
+    return _cache
+
+
+def get() -> Dict[str, Any]:
+    """
+    Returns parsed .pyfun config as nested dict.
+    Loads and caches on first call — subsequent calls return cache.
+    """
+    global _cache
+    if _cache is None:
+        _cache = _parse()
+    return _cache
+
+
+def get_section(section: str) -> Dict[str, Any]:
+    """
+    Returns a specific top-level section.
+    Returns empty dict if section not found.
+    """
+    return get().get(section, {})
+
+
+def get_llm_providers() -> Dict[str, Any]:
+    """Returns all LLM providers (active and inactive)."""
+    return get().get("LLM_PROVIDERS", {})
+
+
+def get_active_llm_providers() -> Dict[str, Any]:
+    """Returns only LLM providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_llm_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_search_providers() -> Dict[str, Any]:
+    """Returns all search providers."""
+    return get().get("SEARCH_PROVIDERS", {})
+
+
+def get_active_search_providers() -> Dict[str, Any]:
+    """Returns only search providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_search_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_models() -> Dict[str, Any]:
+    """Returns all model definitions."""
+    return get().get("MODELS", {})
+
+
+def get_models_for_provider(provider_name: str) -> Dict[str, Any]:
+    """Returns all models for a specific provider."""
+    return {
+        name: cfg
+        for name, cfg in get_models().items()
+        if cfg.get("provider", "") == provider_name
+    }
+
+
+def get_tools() -> Dict[str, Any]:
+    """Returns all tool definitions."""
+    return get().get("TOOLS", {})
+
+
+def get_active_tools() -> Dict[str, Any]:
+    """Returns only tools where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_tools().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_hub() -> Dict[str, Any]:
+    """Returns [HUB] section."""
+    return get_section("HUB")
+
+
+def get_limits() -> Dict[str, Any]:
+    """Returns [HUB_LIMITS] section."""
+    return get_section("HUB_LIMITS")
+
+
+def get_db_sync() -> Dict[str, Any]:
+    """Returns [DB_SYNC] section."""
+    return get_section("DB_SYNC")
+
+
+def get_debug() -> Dict[str, Any]:
+    """Returns [DEBUG] section."""
+    return get_section("DEBUG")
+
+
+def is_debug() -> bool:
+    """Returns True if DEBUG = 'ON' in .pyfun."""
+    return get_debug().get("DEBUG", "OFF").upper() == "ON"
+
+
+def get_pricing() -> Dict[str, Any]:
+    """Returns [PRICING] section — auto model cost fetching."""
+    return get_section("PRICING")

app/db_sync.py

@@ -0,0 +1,554 @@
+
+# =============================================================================
+# app/db_sync.py
+# Internal SQLite IPC — app/* state & communication
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   DB path comes from app/.pyfun [DB_SYNC] → SQLITE_PATH via app/config.py.
+#
+# CRITICAL RULES:
+#   - This is NOT postgresql.py — cloud DB is Guardian-only!
+#   - db_sync ONLY manages its own tables (hub_state, tool_cache)
+#   - NEVER touch Guardian tables (users, sessions) — those belong to user_handler.py
+#   - SQLite path is shared with user_handler.py via SQLITE_PATH
+#   - app/* modules call db_sync.write() / db_sync.read() — never aiosqlite directly
+#
+# TABLE OWNERSHIP:
+#   users, sessions  → Guardian (fundaments/user_handler.py) — DO NOT TOUCH!
+#   hub_state        → db_sync (app/* internal state)
+#   tool_cache       → db_sync (app/* tool response cache)
+#   persist_queue    → db_sync (restart-safe queue → PostgreSQL long-term memory)
+# =============================================================================
+
+import asyncio
+import re
+import aiosqlite
+import logging
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from . import config
+
+logger = logging.getLogger("db_sync")
+
+# =============================================================================
+# Internal State
+# =============================================================================
+_db_path: Optional[str] = None
+_initialized: bool = False
+
+
+# =============================================================================
+# Initialization — called by app/app.py (parameterless, sandboxed)
+# =============================================================================
+
+async def initialize() -> None:
+    global _db_path, _initialized
+
+    if _initialized:
+        return
+
+    db_cfg   = config.get_db_sync()
+    raw_path = db_cfg.get("SQLITE_PATH", "app/.hub_state.db")
+    
+    # HF Spaces: SPACE_ID is set → filesystem is read-only except /tmp/
+    import os
+    if os.getenv("SPACE_ID"):
+        filename = os.path.basename(raw_path)
+        _db_path = f"/tmp/{filename}"
+        logger.info(f"HF Space detected — SQLite relocated to {_db_path}")
+    else:
+        _db_path = raw_path
+
+    await _init_tables()
+
+    _initialized = True
+    logger.info(f"db_sync initialized — path: {_db_path}")
+
+
+# =============================================================================
+# SECTION 1 — Table Setup (app/* tables only!)
+# =============================================================================
+
+async def _init_tables() -> None:
+    """
+    Creates app/* internal tables if they don't exist.
+    NEVER modifies Guardian tables (users, sessions).
+    """
+    async with aiosqlite.connect(_db_path) as db:
+
+        # hub_state — generic key/value store for app/* modules
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS hub_state (
+                key        TEXT PRIMARY KEY,
+                value      TEXT,
+                updated_at TEXT
+            )
+        """)
+
+        # tool_cache — cached tool responses to reduce API calls
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS tool_cache (
+                id         INTEGER PRIMARY KEY AUTOINCREMENT,
+                tool_name  TEXT NOT NULL,
+                prompt     TEXT NOT NULL,
+                response   TEXT NOT NULL,
+                provider   TEXT,
+                model      TEXT,
+                created_at TEXT
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_tool_cache_tool
+            ON tool_cache(tool_name)
+        """)
+
+        # persist_queue — Dauer-Gedächtnis-Queue: überlebt Restarts,
+        # bis der Eintrag erfolgreich nach PostgreSQL geflusht wurde.
+        # score-Spalte = reservierter Slot für den Bullshit-Filter (Nutzer-eigenes
+        # Scoring, später) — wird von db_sync NICHT interpretiert.
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS persist_queue (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                target_table TEXT NOT NULL,
+                payload      TEXT NOT NULL,
+                source       TEXT,
+                model        TEXT,
+                score        REAL,
+                queued_at    TEXT NOT NULL,
+                attempts     INTEGER NOT NULL DEFAULT 0,
+                last_error   TEXT
+            )
+        """)
+
+        await db.commit()
+
+    logger.info("db_sync tables ready.")
+
+
+# =============================================================================
+# SECTION 2 — Key/Value Store (hub_state table)
+# =============================================================================
+
+async def write(key: str, value: Any) -> None:
+    """
+    Write a value to hub_state key/value store.
+    Value is JSON-serialized — supports dicts, lists, strings, numbers.
+
+    Args:
+        key:   Unique key string (e.g. 'scheduler.last_run').
+        value: Any JSON-serializable value.
+    """
+    _check_init()
+    now = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("""
+            INSERT OR REPLACE INTO hub_state (key, value, updated_at)
+            VALUES (?, ?, ?)
+        """, (key, json.dumps(value), now))
+        await db.commit()
+
+
+async def read(key: str, default: Any = None) -> Any:
+    """
+    Read a value from hub_state key/value store.
+    Returns default if key does not exist.
+
+    Args:
+        key:     Key string to look up.
+        default: Default value if key not found. Default: None.
+
+    Returns:
+        Deserialized value, or default if not found.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute(
+            "SELECT value FROM hub_state WHERE key = ?", (key,)
+        )
+        row = await cursor.fetchone()
+
+    if row is None:
+        return default
+
+    try:
+        return json.loads(row[0])
+    except (json.JSONDecodeError, TypeError):
+        return row[0]
+
+
+async def delete(key: str) -> None:
+    """
+    Delete a key from hub_state.
+
+    Args:
+        key: Key string to delete.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("DELETE FROM hub_state WHERE key = ?", (key,))
+        await db.commit()
+
+
+# =============================================================================
+# SECTION 3 — Tool Cache (tool_cache table)
+# =============================================================================
+
+async def cache_write(
+    tool_name: str,
+    prompt: str,
+    response: str,
+    provider: str = None,
+    model: str = None,
+) -> None:
+    """
+    Cache a tool response to reduce redundant API calls.
+
+    Args:
+        tool_name: Tool name (e.g. 'llm_complete', 'web_search').
+        prompt:    The input prompt/query that was used.
+        response:  The response to cache.
+        provider:  Provider name used (optional).
+        model:     Model name used (optional).
+    """
+    _check_init()
+
+    db_cfg      = config.get_db_sync()
+    max_entries = int(db_cfg.get("MAX_CACHE_ENTRIES", "1000"))
+    now         = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("""
+            INSERT INTO tool_cache (tool_name, prompt, response, provider, model, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """, (tool_name, prompt, response, provider, model, now))
+
+        # Enforce MAX_CACHE_ENTRIES — delete oldest if exceeded
+        await db.execute("""
+            DELETE FROM tool_cache WHERE id NOT IN (
+                SELECT id FROM tool_cache ORDER BY created_at DESC LIMIT ?
+            )
+        """, (max_entries,))
+
+        await db.commit()
+
+
+async def cache_read(tool_name: str, prompt: str) -> Optional[str]:
+    """
+    Read a cached tool response.
+    Returns None if no cache entry exists.
+
+    Args:
+        tool_name: Tool name to look up.
+        prompt:    The exact prompt/query to match.
+
+    Returns:
+        Cached response string, or None if not found.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute("""
+            SELECT response FROM tool_cache
+            WHERE tool_name = ? AND prompt = ?
+            ORDER BY created_at DESC LIMIT 1
+        """, (tool_name, prompt))
+        row = await cursor.fetchone()
+
+    return row[0] if row else None
+
+
+# =============================================================================
+# SECTION 4 — Read-Only Query (for mcp.py db_query tool)
+# =============================================================================
+
+async def query(sql: str) -> List[Dict]:
+    """
+    Execute a read-only SELECT query on the internal hub state database.
+    Only SELECT statements are permitted — write operations are blocked.
+    Called by mcp.py db_query tool when db_sync.py is active.
+
+    Args:
+        sql: SQL SELECT statement to execute.
+
+    Returns:
+        List of result rows as dicts.
+
+    Raises:
+        ValueError: If the query is not a SELECT statement.
+    """
+    _check_init()
+
+    if not sql.strip().upper().startswith("SELECT"):
+        raise ValueError("Only SELECT queries are permitted in db_query tool.")
+
+    async with aiosqlite.connect(_db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(sql)
+        rows   = await cursor.fetchall()
+        return [dict(r) for r in rows]
+
+
+# =============================================================================
+# SECTION 5 — Helpers
+# =============================================================================
+
+def _check_init() -> None:
+    """Raise RuntimeError if db_sync was not initialized."""
+    if not _initialized or not _db_path:
+        raise RuntimeError("db_sync not initialized — call initialize() first.")
+
+
+def is_ready() -> bool:
+    """Returns True if db_sync is initialized and ready."""
+    return _initialized and _db_path is not None
+
+
+# =============================================================================
+# SECTION 6 — Memory Orchestration: SQLite (Kurzzeit) → PostgreSQL (Dauer)
+# =============================================================================
+# ARCHITECTURE (Gedächtnis-Design):
+#   SQLite (hub_state / tool_cache / persist_queue) = Kurzzeit-Gedächtnis.
+#   Alle app/* Tools lesen/schreiben hier — immer verfügbar, kein Key nötig.
+#   PostgreSQL = Dauer-Gedächtnis — WICHTIGE Dinge wandern dorthin.
+#
+#   persist_result Tool → enqueue_persist()   (sofort, immer, kein Crash)
+#                          ↓
+#                    persist_queue (SQLite, überlebt Restarts)
+#                          ↓
+#            flush_persist_queue() → PostgreSQL (Guardian-Writer)
+#            (Background-Retry bis die DB da ist — siehe start_persist_flusher)
+#
+#   Delivery-Semantik: at-least-once (PG-Insert + Queue-Delete sind nicht
+#   atomar über zwei Systeme). Für ein Gedächtnis ist ein seltener Duplikat-
+#   Eintrag unkritisch — Datenverlust wäre es.
+#
+#   HF-Spaces-Hinweis: SPACE_ID verschiebt SQLite nach /tmp — Queue überbrückt
+#   dort DB-Ausfälle innerhalb der Container-Lebenszeit; dauerhaft ist nur PG.
+# =============================================================================
+_psql_writer = None
+_flush_task: Optional[asyncio.Task] = None
+_pg_tables_ensured: set = set()
+
+# Defense: Tabellennamen kommen aus .pyfun, aber wir validieren trotzdem.
+_SAFE_TABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Ziel-Schema in PostgreSQL — source/model/score als eigene Spalten,
+# damit dein Bullshit-Filter später direkt auf score filtern kann.
+_PG_DDL = """
+    CREATE TABLE IF NOT EXISTS {table} (
+        id          BIGSERIAL PRIMARY KEY,
+        created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        source      TEXT,
+        model       TEXT,
+        score       REAL,
+        payload     JSONB NOT NULL
+    )
+"""
+
+
+def set_psql_writer(writer_fn) -> None:
+    """
+    Receives the asyncpg execute callable from Guardian via app.py.
+    Called once in start_application() if db_service is available.
+    app/* never imports postgresql.py directly — this is the only bridge.
+    """
+    global _psql_writer
+    _psql_writer = writer_fn
+    _pg_tables_ensured.clear()  # neue Connection → CREATE TABLE erneut sicherstellen
+    logger.info("PostgreSQL writer registered.")
+
+
+async def enqueue_persist(
+    table: str,
+    payload: Any,
+    source: str = "",
+    model: str = "",
+    score: Optional[float] = None,
+) -> int:
+    """
+    Queue an entry for the PostgreSQL long-term memory.
+    ALWAYS works (no writer needed) — this is the 'no crash' guarantee:
+    persist_result ohne DATABASE_URL = Eintrag wartet restart-safe in der Queue.
+
+    Args:
+        table:   Target table in PostgreSQL (from .pyfun target_table).
+        payload: JSON-serializable data to persist.
+        source:  Which tool/component produced this entry.
+        model:   Which model produced this entry.
+        score:   Optional quality score — reserved slot for the bullshit filter.
+
+    Returns:
+        Queue depth after insert (int).
+    """
+    _check_init()
+    max_q = int(config.get_db_sync().get("PERSIST_QUEUE_MAX", "500"))
+    now  = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute(
+            """INSERT INTO persist_queue
+               (target_table, payload, source, model, score, queued_at)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (table, json.dumps(payload, ensure_ascii=False, default=str),
+             source, model, score, now),
+        )
+        # Queue begrenzen — älteste zuerst raus (gleiche Regel wie tool_cache)
+        await db.execute(
+            "DELETE FROM persist_queue WHERE id NOT IN "
+            "(SELECT id FROM persist_queue ORDER BY id DESC LIMIT ?)",
+            (max_q,),
+        )
+        await db.commit()
+        cursor = await db.execute("SELECT COUNT(*) FROM persist_queue")
+        return int((await cursor.fetchone())[0])
+
+
+async def flush_persist_queue(limit: int = 50) -> Dict[str, Any]:
+    """
+    Try to move queued entries to PostgreSQL. NEVER raises.
+
+    No writer  → no-op with reason (entries keep waiting — no crash).
+    Writer set → CREATE TABLE IF NOT EXISTS + INSERT per entry + queue delete.
+    Failure    → attempts+1 + sanitized last_error, entry stays queued.
+
+    Args:
+        limit: Max entries per flush run (bounded work per interval).
+
+    Returns:
+        Dict: {flushed, errors, remaining, reason}
+    """
+    _check_init()
+
+    if not _psql_writer:
+        return {
+            "flushed": 0, "errors": 0,
+            "remaining": await _queue_count(),
+            "reason": "no_postgres_writer",
+        }
+
+    flushed = errors = 0
+    async with aiosqlite.connect(_db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(
+            "SELECT id, target_table, payload, source, model, score "
+            "FROM persist_queue ORDER BY id ASC LIMIT ?",
+            (limit,),
+        )
+        rows = await cursor.fetchall()
+
+        for row in rows:
+            table = row["target_table"]
+            try:
+                if not _SAFE_TABLE_NAME.match(table or ""):
+                    raise ValueError("invalid table name")
+                if table not in _pg_tables_ensured:
+                    await _psql_writer(_PG_DDL.format(table=table))
+                    _pg_tables_ensured.add(table)
+                await _psql_writer(
+                    f"INSERT INTO {table} (source, model, score, payload) "
+                    "VALUES ($1, $2, $3, $4::jsonb)",
+                    row["source"], row["model"], row["score"], row["payload"],
+                )
+                await db.execute("DELETE FROM persist_queue WHERE id = ?", (row["id"],))
+                await db.commit()
+                flushed += 1
+            except Exception as e:
+                errors += 1
+                # Sanitized: nur Exception-TYP — niemals DSN/Payload in Logs oder DB
+                await db.execute(
+                    "UPDATE persist_queue SET attempts = attempts + 1, last_error = ? "
+                    "WHERE id = ?",
+                    (type(e).__name__, row["id"]),
+                )
+                await db.commit()
+
+    remaining = await _queue_count()
+    if flushed:
+        logger.info(f"Persist flush: {flushed} → PostgreSQL, {remaining} queued.")
+    if errors:
+        logger.warning(f"Persist flush: {errors} failed — stay queued (retry next interval).")
+    return {"flushed": flushed, "errors": errors, "remaining": remaining}
+
+
+async def _queue_count() -> int:
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute("SELECT COUNT(*) FROM persist_queue")
+        return int((await cursor.fetchone())[0])
+
+
+async def persist_queue_stats() -> Dict[str, Any]:
+    """
+    Zustand des Gedächtnisses — Observability für die Orchestrierung.
+    Wird von persist_status (MCP + /api) gelesen.
+    """
+    _check_init()
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute(
+            "SELECT COUNT(*), MIN(queued_at), "
+            "SUM(CASE WHEN attempts > 0 THEN 1 ELSE 0 END) FROM persist_queue"
+        )
+        row = await cursor.fetchone()
+    count, oldest, failed = row[0] or 0, row[1], row[2] or 0
+    return {
+        "queue_depth": count,
+        "oldest_queued_at": oldest,
+        "entries_with_failed_attempts": failed,
+        "postgres_bridge": "active" if _psql_writer else "inactive (DATABASE_URL not set)",
+        "note": "queue is restart-safe — flushes to PostgreSQL as soon as the bridge is active",
+    }
+
+
+def start_persist_flusher() -> None:
+    """
+    Background retry loop — started by app.py AFTER db_sync.initialize().
+    Works with AND without writer: ohne PG bleibt alles einfach liegen.
+    """
+    global _flush_task
+    if _flush_task is not None:
+        return
+    interval = float(config.get_db_sync().get("PERSIST_FLUSH_INTERVAL_SEC", "60"))
+    _flush_task = asyncio.create_task(_persist_flush_loop(interval))
+    logger.info(f"Persist flusher started (interval: {interval}s).")
+
+
+async def _persist_flush_loop(interval: float) -> None:
+    # Erster Versuch kurz nach dem Boot — fängt Einträge der letzten Session ab
+    # (genau dann, wenn PG wieder da ist, während er vorher down war).
+    await asyncio.sleep(5)
+    while True:
+        try:
+            result = await flush_persist_queue()
+            if result.get("flushed") or result.get("errors"):
+                logger.info(f"Persist flusher: {result}")
+        except Exception as e:
+            logger.warning(f"Persist flusher error (non-fatal): {type(e).__name__}")
+        await asyncio.sleep(interval)
+
+
+async def persist(table: str, data: dict) -> None:
+    """
+    Legacy direct-write — jetzt queue-safe: enqueue + sofortiger Flush-Versuch.
+    Beißt nicht mehr ohne DATABASE_URL (früher: RuntimeError). Backward-kompatibel
+    für externe Aufrufer; tools.py nutzt jetzt enqueue_persist() direkt.
+    """
+    await enqueue_persist(table, payload=data)
+    await flush_persist_queue(limit=1)
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/mcp.py

@@ -0,0 +1,495 @@
+# =============================================================================
+# root/app/mcp.py
+# 14.03.2026
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+# TRANSPORT:
+#   Primary:  Streamable HTTP (MCP spec 2025-11-25) → single /mcp endpoint
+#             Configured via HUB_TRANSPORT = "streamable-http" in .pyfun [HUB]
+#             ASGI-App via get_asgi_app() → mounted by app/app.py
+#
+#   Fallback: SSE (legacy, deprecated per spec) → /mcp route via Quart
+#             Configured via HUB_TRANSPORT = "sse" in .pyfun [HUB]
+#             handle_request() called directly by app/app.py Quart route
+#
+#   All MCP traffic (both transports) passes through app/app.py first —
+#   auth checks, rate limiting, logging can be added there before reaching MCP.
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are registered via tools.py — NOT hardcoded here.
+#   No key = no provider = no tool = no crash.
+#   Server always starts, just with fewer tools.
+#   Adding a new tool = update .pyfun + providers.py only. Never touch mcp.py.
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search provider registry + fallback chain
+#   models.py    → model limits, costs, capabilities from .pyfun [MODELS]
+#   tools.py     → tool registry + execution — reads .pyfun [TOOLS]
+#   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
+#   mcp.py       → registers tools only, delegates all logic to tools.py
+# =============================================================================
+import contextlib
+import logging
+from typing import Dict, Any
+from . import config as app_config
+from . import providers
+from . import models
+from . import pricing
+from . import tools
+
+logger = logging.getLogger('mcp')
+
+# =============================================================================
+# Globals — set once during initialize(), never touched elsewhere
+# =============================================================================
+_mcp       = None   # FastMCP instance
+_transport = None   # "streamable-http" | "sse" — from .pyfun [HUB] HUB_TRANSPORT
+_stateless = None   # True = HF Spaces / horizontal scaling safe
+
+# =============================================================================
+# Initialization — called exclusively by app/app.py
+# =============================================================================
+async def initialize() -> None:
+    """
+    Initializes the MCP instance and registers all tools.
+    Called once by app/app.py during startup sequence.
+    No fundaments passed in — fully sandboxed.
+
+    Reads HUB_TRANSPORT and HUB_STATELESS from .pyfun [HUB].
+
+    Transport modes:
+        streamable-http → get_asgi_app() returns ASGI app → app.py mounts it
+        sse             → handle_request() used by Quart route in app.py
+
+    Registration order:
+        1. LLM tools    → via tools.py + providers.py (key-gated)
+        2. Search tools → via tools.py + providers.py (key-gated)
+        3. System tools → always registered, no key required
+        4. DB tools     → db_sync SELECT-only (app/* tables)
+        5. Persist tools → memory orchestration (works WITHOUT PostgreSQL — queue)
+    """
+    global _mcp, _transport, _stateless
+
+    hub_cfg    = app_config.get_hub()
+    _transport = hub_cfg.get("HUB_TRANSPORT", "streamable-http").lower()
+    _stateless = hub_cfg.get("HUB_STATELESS", "true").lower() == "true"
+
+    logger.info(f"MCP Hub initializing (transport: {_transport}, stateless: {_stateless})...")
+
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        logger.critical("FastMCP not installed. Run: pip install mcp")
+        raise
+
+    _mcp = FastMCP(
+        name=hub_cfg.get("HUB_NAME", "Universal MCP Hub"),
+        instructions=(
+            f"{hub_cfg.get('HUB_DESCRIPTION', 'Universal MCP Hub on PyFundaments')} "
+            "Use list_active_tools to see what is currently available."
+        ),
+        stateless_http=_stateless,  # True = no session state, HF Spaces safe
+    )
+
+    # --- Initialize registries ---
+    providers.initialize()
+    models.initialize()
+    tools.initialize()
+
+    # --- Register MCP tools ---
+    _register_llm_tools(_mcp)
+    _register_search_tools(_mcp)
+    _register_system_tools(_mcp)
+    _register_pricing_tools(_mcp)
+    _register_db_tools(_mcp)    # db_sync ready — SELECT-only, app/* tables
+    _register_persist_tools(_mcp)  # memory orchestration — queue-safe, no PG required
+
+    logger.info(f"MCP Hub initialized. Transport: {_transport}")
+
+
+# =============================================================================
+# ASGI App — used by app/app.py for Streamable HTTP transport
+# =============================================================================
+def get_asgi_app():
+    """
+    Returns the ASGI app for the configured transport.
+    Called by app/app.py AFTER initialize() — mounted as ASGI sub-app.
+
+    Streamable HTTP: mounts on /mcp — single endpoint for all MCP traffic.
+    SSE (fallback):  returns sse_app() for legacy client compatibility.
+
+    NOTE: For SSE transport, app/app.py uses the Quart route + handle_request()
+          instead — get_asgi_app() is only called for streamable-http.
+    """
+    if _mcp is None:
+        raise RuntimeError("MCP not initialized — call initialize() first.")
+
+    if _transport == "streamable-http":
+        logger.info("MCP ASGI app: Streamable HTTP → /mcp")
+        return _mcp.streamable_http_app()
+    else:
+        # SSE as ASGI app — only used if app.py mounts it directly
+        # (normally app.py uses the Quart route + handle_request() for SSE)
+        logger.info("MCP ASGI app: SSE (legacy) → /sse")
+        return _mcp.sse_app()
+
+
+# =============================================================================
+# Mount Prefixes — welche URL-Prefixe gehören der MCP-ASGI-App
+# =============================================================================
+def mount_prefixes():
+    """URL prefixes the mounted ASGI app owns (used by app/app.py)."""
+    if _transport == "streamable-http":
+        return ("/mcp",)
+    return ("/sse", "/messages")
+
+
+# =============================================================================
+# Lifespan — Session-Manager für die Lebensdauer des Servers
+# =============================================================================
+@contextlib.asynccontextmanager
+async def lifespan():
+    """
+    Runs the FastMCP session manager for the lifetime of the server.
+
+    WHY: FastMCP's streamable_http_app() starts its session manager in the
+    Starlette lifespan. Because app/app.py mounts it behind a plain ASGI
+    middleware (lifespan scope goes to Quart, not to the inner app), we have
+    to run it ourselves — otherwise every request fails with
+    'Task group is not initialized'.
+    Call AFTER get_asgi_app() (it creates the session manager).
+    """
+    if _mcp is not None and _transport == "streamable-http":
+        async with _mcp.session_manager.run():
+            yield
+    else:
+        yield
+
+
+# =============================================================================
+# Tool Registration — delegates all logic to tools.py
+# =============================================================================
+
+def _register_llm_tools(mcp) -> None:
+    """
+    Register LLM completion tool.
+    All logic delegated to tools.py → providers.py.
+    Adding a new LLM provider = update .pyfun + providers.py. Never touch this.
+    """
+    if not providers.list_active_llm():
+        logger.info("No active LLM providers — llm_complete tool skipped.")
+        return
+
+    @mcp.tool()
+    async def llm_complete(
+        prompt: str,
+        provider: str = None,
+        model: str = None,
+        max_tokens: int = 1024,
+    ) -> str:
+        """
+        Send a prompt to any configured LLM provider.
+        Automatically follows the fallback chain defined in .pyfun if a provider fails.
+
+        Args:
+            prompt:     The input text to send to the model.
+            provider:   Provider name (e.g. 'anthropic', 'gemini', 'openrouter', 'huggingface').
+                        Defaults to default_provider from .pyfun [TOOL.llm_complete].
+            model:      Model name override. Defaults to provider's default_model in .pyfun.
+            max_tokens: Maximum tokens in the response. Default: 1024.
+
+        Returns:
+            Model response as plain text string.
+        """
+        return await tools.run(
+            tool_name="llm_complete",
+            prompt=prompt,
+            provider_name=provider,
+            model=model,
+            max_tokens=max_tokens,
+        )
+
+    logger.info(f"Tool registered: llm_complete (active providers: {providers.list_active_llm()})")
+
+
+def _register_search_tools(mcp) -> None:
+    """
+    Register web search tool.
+    All logic delegated to tools.py → providers.py.
+    Adding a new search provider = update .pyfun + providers.py. Never touch this.
+    """
+    if not providers.list_active_search():
+        logger.info("No active search providers — web_search tool skipped.")
+        return
+
+    @mcp.tool()
+    async def web_search(
+        query: str,
+        provider: str = None,
+        max_results: int = 5,
+    ) -> str:
+        """
+        Search the web via any configured search provider.
+        Automatically follows the fallback chain defined in .pyfun if a provider fails.
+
+        Args:
+            query:       Search query string.
+            provider:    Provider name (e.g. 'brave', 'tavily').
+                         Defaults to default_provider from .pyfun [TOOL.web_search].
+            max_results: Maximum number of results to return. Default: 5.
+
+        Returns:
+            Formatted search results as plain text string.
+        """
+        return await tools.run(
+            tool_name="web_search",
+            prompt=query,
+            provider_name=provider,
+            max_results=max_results,
+        )
+
+    logger.info(f"Tool registered: web_search (active providers: {providers.list_active_search()})")
+
+
+def _register_system_tools(mcp) -> None:
+    """
+    System tools — always registered, no ENV key required.
+    Exposes hub status and model info without touching secrets.
+    """
+
+    @mcp.tool()
+    def list_active_tools() -> Dict[str, Any]:
+        """
+        List all active providers and registered tools.
+        Shows ENV key names only — never exposes values or secrets.
+
+        Returns:
+            Dict with hub info, active LLM providers, active search providers,
+            available tools and model names.
+        """
+        hub = app_config.get_hub()
+        return {
+            "hub":                     hub.get("HUB_NAME", "Universal MCP Hub"),
+            "version":                 hub.get("HUB_VERSION", ""),
+            "transport":               _transport,
+            "active_llm_providers":    providers.list_active_llm(),
+            "active_search_providers": providers.list_active_search(),
+            "active_tools":            tools.list_all(),
+            "available_models":        models.list_all(),
+            "pricing_stats":           pricing.stats(),
+        }
+
+    logger.info("Tool registered: list_active_tools")
+
+    @mcp.tool()
+    def health_check() -> Dict[str, str]:
+        """
+        Health check endpoint for HuggingFace Spaces and monitoring systems.
+
+        Returns:
+            Dict with service status and active transport.
+        """
+        return {
+            "status":    "ok",
+            "service":   "Universal MCP Hub",
+            "transport": _transport,
+        }
+
+    logger.info("Tool registered: health_check")
+
+    @mcp.tool()
+    async def get_model_info(model_name: str) -> Dict[str, Any]:
+        """
+        Get limits, costs, and capabilities for a specific model.
+        Costs are MERGED: .pyfun manual values win, auto-fetched values
+        (OpenRouter / LiteLLM) fill the gaps.
+
+        Args:
+            model_name: Model name as defined in .pyfun [MODELS] (e.g. 'claude-sonnet-4-6').
+
+        Returns:
+            Dict with context size, max output tokens, rate limits, costs, and capabilities.
+            Returns pricing source info. Empty dict if model unknown.
+        """
+        # .pyfun [MODELS] als Basis + Auto-Pricing füllt Lücken
+        merged = await pricing.get_pricing(model_name)
+        if not merged.get("provider") and not merged.get("cost_input_per_1k"):
+            return merged  # komplett unbekanntes Model
+        return merged
+
+    logger.info("Tool registered: get_model_info")
+
+
+# =============================================================================
+# Pricing Tools — auto-fetched model costs (OpenRouter + LiteLLM)
+# =============================================================================
+def _register_pricing_tools(mcp) -> None:
+    """
+    Register pricing tools.
+    Answers the question nobody wants to maintain by hand:
+    'Was kostet dieses Model?' — ohne [.MODELS] Kosten von Hand zu pflegen.
+    """
+
+    @mcp.tool()
+    async def get_model_pricing(model_name: str) -> Dict[str, Any]:
+        """
+        Get current pricing for a model — auto-fetched, no manual maintenance.
+
+        Merge order (highest priority first):
+            1. .pyfun [MODELS] manual values — your override always wins
+            2. OpenRouter public models API (all OR models, per-token USD)
+            3. LiteLLM community price list (Anthropic, Gemini, OpenAI, ...)
+
+        Args:
+            model_name: Model name (e.g. 'claude-opus-4-6', 'gemini-2.5-flash',
+                        'meta-llama/llama-3.3-70b-instruct').
+
+        Returns:
+            Dict with cost_input_per_1k, cost_output_per_1k (USD),
+            context_tokens, max_output_tokens, source, pricing_note.
+        """
+        return await pricing.get_pricing(model_name)
+
+    logger.info("Tool registered: get_model_pricing")
+
+    @mcp.tool()
+    async def refresh_pricing() -> Dict[str, Any]:
+        """
+        Force a pricing refresh from OpenRouter + LiteLLM.
+        Updates the db_sync cache (TTL-gated, default 24h).
+
+        Returns:
+            Dict with fetched_at, per-source model counts, and total cached models.
+        """
+        return await pricing.refresh()
+
+    logger.info("Tool registered: refresh_pricing")
+
+
+# =============================================================================
+# DB Tools — db_sync.py is ready, enabled
+# =============================================================================
+def _register_db_tools(mcp) -> None:
+    """
+    Register internal SQLite query tool.
+    Uses db_sync.py (app/* internal SQLite) — NOT postgresql.py (Guardian-only)!
+
+    SECURITY: Only SELECT queries are permitted.
+    Enforced at application level in db_sync.query() — not just in docs.
+    Tables accessible: hub_state, tool_cache  (app/* only)
+    Tables blocked:    users, sessions         (Guardian-only, different owner)
+
+    Requirements (all met):
+        1. This function enabled
+        2. _register_db_tools(_mcp) called in initialize()
+        3. db_sync.initialize() runs in app/app.py BEFORE mcp.initialize()
+    """
+    from . import db_sync
+
+    @mcp.tool()
+    async def db_query(sql: str) -> list:
+        """
+        Execute a read-only SELECT query on the internal hub state database.
+
+        Only SELECT statements are permitted — all write operations are blocked
+        at the db_sync layer (not just by convention).
+
+        Accessible tables:
+            hub_state   — current hub runtime state (tool status, uptime, etc.)
+            tool_cache  — cached tool results for repeated queries
+
+        NOT accessible (Guardian-only):
+            users       — managed by fundaments/user_handler.py
+            sessions    — managed by fundaments/user_handler.py
+
+        Args:
+            sql: SQL SELECT statement. Example: "SELECT * FROM hub_state LIMIT 10"
+
+        Returns:
+            List of result rows as dicts. Empty list if no results.
+
+        Raises:
+            ValueError: If statement is not a SELECT query.
+            RuntimeError: If db_sync is not initialized.
+        """
+        return await db_sync.query(sql)
+
+    logger.info("Tool registered: db_query (SQLite SELECT-only, app/* tables)")
+
+
+# =============================================================================
+# Persist Tools — Gedächtnis-Orchestrierung (SQLite-Queue → PostgreSQL)
+# =============================================================================
+def _register_persist_tools(mcp) -> None:
+    """
+    Register memory-orchestration tools.
+
+    persist_result works WITHOUT PostgreSQL: entries queue restart-safe in
+    the SQLite persist_queue (db_sync) and flush automatically once the
+    Guardian-injected PostgreSQL bridge is active. No key = queued, not crash.
+    """
+    if "persist_result" not in tools.list_all():
+        logger.info("persist_result not active in .pyfun — skipped.")
+        return
+
+    @mcp.tool()
+    async def persist_result(
+        prompt: str = None,
+        source: str = None,
+        model: str = None,
+        score: float = None,
+    ) -> Dict[str, Any]:
+        """
+        Persist a result to long-term memory (PostgreSQL).
+
+        Restart-safe: without DATABASE_URL the entry queues in SQLite and
+        flushes automatically once PostgreSQL is available. Never crashes.
+
+        Args:
+            prompt: The text/result to persist (or hub_state key via .pyfun state_read_key).
+            source: Which tool/component produced this entry (optional).
+            model:  Which model produced this entry (optional).
+            score:  Optional quality score — reserved slot, set by your own filter.
+
+        Returns:
+            Dict with status ('persisted' | 'queued'), target_table, queue_depth.
+        """
+        return await tools.run(
+            tool_name="persist_result",
+            prompt=prompt,
+            source=source,
+            model=model,
+            score=score,
+        )
+
+    logger.info("Tool registered: persist_result (queue-safe memory orchestration)")
+
+    @mcp.tool()
+    async def persist_status() -> Dict[str, Any]:
+        """
+        Show memory orchestration status: queue depth, oldest entry,
+        failed attempts, and whether the PostgreSQL bridge is active.
+
+        Returns:
+            Dict with queue stats — observability for the memory pipeline.
+        """
+        from . import db_sync
+        return await db_sync.persist_queue_stats()
+
+    logger.info("Tool registered: persist_status")
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == '__main__':
+    print("WARNING: Run via main.py → app.py, not directly.")

app/models.py

@@ -0,0 +1,75 @@
+# =============================================================================
+# # app/models.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are registered via models.py and models.py .
+#   No key = no provider = no tool = no crash.
+#   Adding a new provider = update .pyfun + providers.py only. Never touch mcp.py!
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search provider registry + fallback chain
+#   models.py    → model limits, costs, capabilities from .pyfun [MODELS]
+#   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
+#   mcp.py       → registers tools only, delegates all logic to providers/*
+# =============================================================================
+# app/models.py
+from . import config
+import logging
+
+logger = logging.getLogger("models")
+
+_registry: dict = {}
+
+def initialize() -> None:
+    """Build model registry from .pyfun [MODELS]"""
+    global _registry
+    _registry = config.get_models()
+    logger.info(f"Models loaded: {list(_registry.keys())}")
+
+
+def get(model_name: str) -> dict:
+    """Get model config by name. Falls back to raw .pyfun if not initialized yet."""
+    if _registry:
+        return _registry.get(model_name, {})
+    return config.get_models().get(model_name, {})
+
+
+def get_limit(model_name: str, key: str, default=None):
+    """Get specific limit for a model."""
+    return _registry.get(model_name, {}).get(key, default)
+
+
+def for_provider(provider_name: str) -> dict:
+    """Get all models for a provider."""
+    return config.get_models_for_provider(provider_name)
+
+
+def max_tokens(model_name: str) -> int:
+    return int(get_limit(model_name, "max_output_tokens", "1024"))
+
+
+def context_size(model_name: str) -> int:
+    return int(get_limit(model_name, "context_tokens", "4096"))
+
+
+def cost_input(model_name: str) -> float:
+    return float(get_limit(model_name, "cost_input_per_1k", "0"))
+
+
+def cost_output(model_name: str) -> float:
+    return float(get_limit(model_name, "cost_output_per_1k", "0"))
+
+
+def list_all() -> list:
+    return list(_registry.keys())

app/pricing.py

@@ -0,0 +1,449 @@
+# =============================================================================
+# app/pricing.py
+# Auto Model Pricing — weil niemand Lust hat, Kosten von Hand zu pflegen.
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun [PRICING] via app/config.py.
+#
+# WHY THIS EXISTS:
+#   Not every provider has a pricing API (Anthropic & Google: none).
+#   Manually maintaining cost_input_per_1k in [MODELS] sucks. Solution:
+#   two free public sources cover almost everything, .pyfun stays the override.
+#
+# SOURCES (priority: .pyfun manual > OpenRouter > LiteLLM):
+#   1. .pyfun [MODELS]           → your values ALWAYS win (manual override)
+#   2. OpenRouter /api/v1/models → public, no key. Pricing per token for all
+#                                  OR models + context_length + max_completion_tokens
+#   3. LiteLLM community JSON    → github.com/BerriAI/litellm main branch.
+#                                  input_cost_per_token / output_cost_per_token
+#                                  for Anthropic, Gemini, OpenAI, Mistral, ...
+#
+# PRINCIPLE (same as everything here):
+#   No network = no crash. No match = costs stay as configured.
+#   Server always starts — pricing refresh runs in the BACKGROUND.
+#
+# CACHING:
+#   Fetched data lands in db_sync hub_state ("pricing.cache") with TTL
+#   from .pyfun (default 24h). Restart within TTL = no external call.
+#
+# MCP TOOLS (registered in mcp.py):
+#   get_model_pricing(model_name)  → merged cost info for one model
+#   refresh_pricing()              → force refresh, returns source counts
+# =============================================================================
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import config
+from . import db_sync
+
+logger = logging.getLogger("pricing")
+
+# =============================================================================
+# Internal State
+# =============================================================================
+_cache: Dict[str, Dict[str, Any]] = {}   # normalized_name → {cost_in_1k, cost_out_1k, context, max_out, source}
+_meta: Dict[str, Any] = {}               # {"fetched_at": iso, "sources": {...}, "model_count": int}
+_task: Optional[asyncio.Task] = None     # background refresh task
+_initialized: bool = False
+
+# Loose index: alnum-only keys for dot/dash-insensitive matching.
+# Why: OpenRouter writes 'claude-opus-4.6', LiteLLM 'claude-opus-4-6',
+# your .pyfun 'claude-opus-4-6'. All should find each other.
+_loose_index: Dict[str, str] = {}        # loose_key → normalized cache key
+_loose_dirty: bool = True
+
+_HUB_STATE_KEY = "pricing.cache"
+
+# Known vendor prefixes used by OpenRouter / LiteLLM IDs
+# ("anthropic/claude-...", "gemini/gemini-...", "meta-llama/llama-...", ...)
+_VENDOR_PREFIXES = (
+    "anthropic/", "google/", "openai/", "meta-llama/", "mistralai/", "mistral/",
+    "qwen/", "nvidia/", "microsoft/", "deepseek/", "x-ai/", "xai/", "perplexity/",
+    "cohere/", "gryphe/", "thedrummer/", "undi95/", "cognitivecomputations/",
+    "gemini/", "groq/", "together_ai/", "together/", "openrouter/", "fireworks_ai/",
+    "azure/", "vertex_ai/", "bedrock/", "cloudflare/", "voyage/", "sambanova/",
+    "ai21/", "huggingface/", "ollama/", "ollama_chat/",
+)
+
+
+# =============================================================================
+# Normalization — model IDs differ wildly between sources
+# =============================================================================
+def _normalize(name: str) -> str:
+    """
+    Normalize a model name for matching across sources.
+    'anthropic/claude-haiku-4.5' → 'claude-haiku-4.5'
+    'Claude-Haiku-4.5'           → 'claude-haiku-4.5'
+    Dots vs dashes are kept — providers are inconsistent there by design.
+    """
+    n = (name or "").strip().lower()
+    for prefix in _VENDOR_PREFIXES:
+        if n.startswith(prefix):
+            n = n[len(prefix):]
+            break
+    return n
+
+
+def _safe_int(value: Any) -> Optional[int]:
+    """int() that returns None instead of raising (LiteLLM ships doc samples
+    like sample_spec.max_input_tokens = 'max input tokens, if the provider specifies it')."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _per_token_to_per_1k(cost: Any) -> Optional[float]:
+    """'0.0000015' per token → 0.0015 per 1k tokens. Returns None on garbage."""
+    try:
+        val = float(cost)
+    except (TypeError, ValueError):
+        return None
+    if val < 0:  # negative = OpenRouter's "we pay you" marker → treat as 0
+        val = 0.0
+    return round(val * 1000, 6)
+
+
+def _loose(name: str) -> str:
+    """Strip everything except a-z0-9 — kills dot/dash/underscore differences."""
+    return "".join(ch for ch in name if ch.isalnum())
+
+
+def _rebuild_loose_index() -> None:
+    """Rebuild the alnum-only lookup index after a cache change."""
+    global _loose_index, _loose_dirty
+    _loose_index = {_loose(k): k for k in _cache}
+    _loose_dirty = False
+
+
+def _lookup(model_name: str) -> Optional[Dict[str, Any]]:
+    """
+    Cache lookup with graceful fallback:
+        1. exact normalized match ('claude-opus-4-6')
+        2. loose alnum match ('claude-opus-4.6' ≈ 'claude-opus-4-6')
+    """
+    norm = _normalize(model_name)
+    hit = _cache.get(norm)
+    if hit:
+        return hit
+    if _loose_dirty:
+        _rebuild_loose_index()
+    loose_key = _loose_index.get(_loose(norm))
+    if loose_key:
+        return _cache.get(loose_key)
+    return None
+
+
+# =============================================================================
+# Source Fetchers — each returns {normalized_name: entry}
+# =============================================================================
+async def _fetch_openrouter(url: str) -> Dict[str, Dict[str, Any]]:
+    """
+    OpenRouter public models endpoint — no key required.
+    https://openrouter.ai/api/v1/models → data[].{id, pricing{prompt,completion}, context_length}
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    async with httpx.AsyncClient() as client:
+        r = await client.get(url, timeout=30)
+        r.raise_for_status()
+        payload = r.json()
+
+    for m in payload.get("data", []):
+        model_id = m.get("id", "")
+        if not model_id:
+            continue
+        pricing = m.get("pricing", {}) or {}
+        entry: Dict[str, Any] = {"source": "openrouter"}
+
+        cost_in  = _per_token_to_per_1k(pricing.get("prompt"))
+        cost_out = _per_token_to_per_1k(pricing.get("completion"))
+        if cost_in is not None:
+            entry["cost_input_per_1k"] = cost_in
+        if cost_out is not None:
+            entry["cost_output_per_1k"] = cost_out
+        if m.get("context_length"):
+            ctx = _safe_int(m["context_length"])
+            if ctx:
+                entry["context_tokens"] = ctx
+
+        # max_completion_tokens is nested under top_provider in OR payloads
+        max_out = _safe_int((m.get("top_provider") or {}).get("max_completion_tokens"))
+        if max_out:
+            entry["max_output_tokens"] = max_out
+
+        out[_normalize(model_id)] = entry
+    return out
+
+
+async def _fetch_litellm(url: str) -> Dict[str, Dict[str, Any]]:
+    """
+    LiteLLM community price list — no key required.
+    github.com/BerriAI/litellm → model_prices_and_context_window.json
+    Keys like 'claude-sonnet-4-5', 'gemini/gemini-2.5-flash', 'gpt-4o'.
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    async with httpx.AsyncClient() as client:
+        r = await client.get(url, timeout=30)
+        r.raise_for_status()
+        payload = r.json()
+
+    for model_id, info in payload.items():
+        if not isinstance(info, dict):
+            continue  # skip metadata keys like "additional_vendor_names"
+        entry: Dict[str, Any] = {"source": "litellm"}
+
+        cost_in  = _per_token_to_per_1k(info.get("input_cost_per_token"))
+        cost_out = _per_token_to_per_1k(info.get("output_cost_per_token"))
+        if cost_in is not None:
+            entry["cost_input_per_1k"] = cost_in
+        if cost_out is not None:
+            entry["cost_output_per_1k"] = cost_out
+        if info.get("max_input_tokens"):
+            ctx = _safe_int(info["max_input_tokens"])
+            if ctx:
+                entry["context_tokens"] = ctx
+        if info.get("max_output_tokens"):
+            max_out = _safe_int(info["max_output_tokens"])
+            if max_out:
+                entry["max_output_tokens"] = max_out
+
+        out[_normalize(model_id)] = entry
+    return out
+
+
+# =============================================================================
+# Cache — db_sync hub_state, TTL-gated
+# =============================================================================
+def _cache_is_fresh() -> bool:
+    if not _cache or not _meta.get("fetched_at"):
+        return False
+    from datetime import datetime, timezone
+    try:
+        fetched = datetime.fromisoformat(_meta["fetched_at"])
+    except (ValueError, TypeError):
+        return False
+    ttl_hours = float(config.get_pricing().get("PRICING_TTL_HOURS", "24"))
+    age = datetime.now(timezone.utc) - fetched
+    return age.total_seconds() < ttl_hours * 3600
+
+
+async def _load_cache_from_db() -> None:
+    """Read pricing cache from db_sync — never raises."""
+    global _cache, _meta, _loose_dirty
+    try:
+        stored = await db_sync.read(_HUB_STATE_KEY, default=None)
+        if isinstance(stored, dict) and stored.get("models"):
+            _cache = stored["models"]
+            _meta = stored.get("meta", {})
+            _loose_dirty = True
+            logger.info(
+                f"Pricing cache loaded from db_sync: {len(_cache)} models "
+                f"(fetched_at: {_meta.get('fetched_at', 'unknown')})"
+            )
+    except Exception as e:
+        logger.warning(f"Pricing cache load failed (continuing without): {type(e).__name__}")
+
+
+async def _save_cache_to_db() -> None:
+    """Write pricing cache to db_sync — never raises."""
+    try:
+        await db_sync.write(_HUB_STATE_KEY, {"models": _cache, "meta": _meta})
+    except Exception as e:
+        logger.warning(f"Pricing cache save failed: {type(e).__name__}")
+
+
+# =============================================================================
+# Refresh — fetch sources, merge, cache
+# =============================================================================
+async def refresh() -> Dict[str, Any]:
+    """
+    Fetch all pricing sources, rebuild the auto-pricing cache.
+    Never raises — a failing source is just skipped (no fetch = no crash).
+    """
+    global _cache, _meta, _loose_dirty
+    from datetime import datetime, timezone
+
+    cfg       = config.get_pricing()
+    or_url    = cfg.get("OPENROUTER_MODELS_URL", "https://openrouter.ai/api/v1/models")
+    llm_url   = cfg.get(
+        "LITELLM_PRICES_URL",
+        "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
+    )
+
+    merged: Dict[str, Dict[str, Any]] = {}
+    sources: Dict[str, int] = {}
+
+    # --- Source 1: OpenRouter ---
+    try:
+        or_models = await _fetch_openrouter(or_url)
+        merged.update(or_models)
+        sources["openrouter"] = len(or_models)
+        logger.info(f"Pricing source OpenRouter: {len(or_models)} models.")
+    except Exception as e:
+        sources["openrouter"] = 0
+        logger.warning(f"Pricing source OpenRouter failed: {type(e).__name__} — skipped.")
+
+    # --- Source 2: LiteLLM (fills gaps — never overwrites OpenRouter) ---
+    try:
+        llm_models = await _fetch_litellm(llm_url)
+        for name, entry in llm_models.items():
+            if name not in merged:
+                merged[name] = entry
+        sources["litellm"] = len(llm_models)
+        logger.info(f"Pricing source LiteLLM: {len(llm_models)} models.")
+    except Exception as e:
+        sources["litellm"] = 0
+        logger.warning(f"Pricing source LiteLLM failed: {type(e).__name__} — skipped.")
+
+    if merged:
+        _cache = merged
+        _meta = {
+            "fetched_at": datetime.now(timezone.utc).isoformat(),
+            "sources": sources,
+            "model_count": len(merged),
+        }
+        _loose_dirty = True
+        await _save_cache_to_db()
+
+    return {
+        "fetched_at": _meta.get("fetched_at"),
+        "sources": sources,
+        "models_cached": len(_cache),
+    }
+
+
+# =============================================================================
+# Initialization — called by app/app.py, NON-BLOCKING
+# =============================================================================
+async def initialize() -> None:
+    """
+    Prepare auto-pricing. Loads the db_sync cache if fresh; otherwise kicks
+    off a BACKGROUND refresh (asyncio.create_task) — the server never waits
+    for external pricing APIs. No network = no crash.
+    """
+    global _initialized, _task
+    if _initialized:
+        return
+
+    cfg = config.get_pricing()
+    enabled = cfg.get("PRICING_ENABLED", "true").lower() == "true"
+
+    if not enabled:
+        logger.info("Auto-pricing disabled in .pyfun [PRICING] — .pyfun [MODELS] values only.")
+        _initialized = True
+        return
+
+    await _load_cache_from_db()
+
+    if _cache_is_fresh():
+        logger.info("Auto-pricing cache fresh — no external fetch needed.")
+    else:
+        logger.info("Auto-pricing cache stale/empty — background refresh started.")
+        _task = asyncio.create_task(_background_refresh())
+
+    _initialized = True
+
+
+async def _background_refresh() -> None:
+    """Runs refresh() and swallows everything — background task must never crash the app."""
+    try:
+        await refresh()
+    except Exception as e:
+        logger.warning(f"Pricing background refresh failed (non-fatal): {type(e).__name__}")
+
+
+# =============================================================================
+# Public API — merged view: .pyfun manual values WIN over auto-fetched
+# =============================================================================
+async def get_pricing(model_name: str) -> Dict[str, Any]:
+    """
+    Returns merged pricing info for one model.
+
+    Merge order (highest priority first):
+        1. .pyfun [MODELS.<model>]   → your manual values always win
+        2. auto-fetched cache        → OpenRouter / LiteLLM
+        3. nothing                   → costs omitted, source: "unknown"
+
+    Returns dict with: model, provider (if known from .pyfun),
+    cost_input_per_1k, cost_output_per_1k (USD), context_tokens,
+    max_output_tokens, source ("pyfun" | "openrouter" | "litellm" | "unknown"),
+    pricing_note.
+    """
+    from . import models as models_mod
+
+    result: Dict[str, Any] = {"model": model_name}
+    notes = []
+
+    # --- Layer 1: .pyfun manual config (models.py reads [MODELS]) ---
+    manual = models_mod.get(model_name)
+    if manual:
+        result["provider"] = manual.get("provider", "")
+        for key in ("cost_input_per_1k", "cost_output_per_1k",
+                    "context_tokens", "max_output_tokens",
+                    "requests_per_min", "requests_per_day", "capabilities"):
+            if manual.get(key):
+                value = manual[key]
+                if key.startswith("cost_"):
+                    # .pyfun-Werte sind Strings ("0.015") — Auto-Werte sind float.
+                    # Normalisieren, damit die API immer Zahlen liefert.
+                    try:
+                        value = round(float(value), 6)
+                    except (TypeError, ValueError):
+                        pass
+                result[key] = value
+        if manual.get("cost_input_per_1k") or manual.get("cost_output_per_1k"):
+            result["source"] = "pyfun"
+            notes.append(".pyfun manual values (override)")
+        else:
+            notes.append(".pyfun entry has no costs — auto values used")
+
+    # --- Layer 2: auto-fetched cache fills the gaps ---
+    auto = _lookup(model_name)
+    if auto:
+        for key in ("cost_input_per_1k", "cost_output_per_1k",
+                    "context_tokens", "max_output_tokens"):
+            if key not in result and auto.get(key) is not None:
+                result[key] = auto[key]
+        if "source" not in result:
+            result["source"] = auto.get("source", "auto")
+            notes.append(f"auto-fetched from {auto.get('source', 'unknown')}")
+    elif "source" not in result:
+        result["source"] = "unknown"
+        notes.append("no auto source matched this model name")
+
+    # --- Stale hint ---
+    if _cache and not _cache_is_fresh():
+        notes.append("cache stale — refresh_pricing() to update")
+
+    result["pricing_note"] = "; ".join(notes) if notes else "ok"
+    return result
+
+
+def is_ready() -> bool:
+    """True if pricing cache holds at least one model."""
+    return bool(_cache)
+
+
+def stats() -> Dict[str, Any]:
+    """Cache stats for list_active_tools / debugging."""
+    return {
+        "models_cached": len(_cache),
+        "fetched_at": _meta.get("fetched_at"),
+        "sources": _meta.get("sources", {}),
+        "fresh": _cache_is_fresh(),
+    }
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/providers.py

@@ -0,0 +1,825 @@
+# =============================================================================
+# app/providers.py
+# 09.03.2026 | updated 23.03.2026
+# LLM + Search Provider Registry + Fallback Chain
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+# PROVIDER PRINCIPLE:
+#   No key = no provider = no tool = no crash.
+#   Server always starts, just with fewer providers.
+#   Adding a new provider = update .pyfun + add class here. Never touch mcp.py!
+#
+# FALLBACK CHAIN:
+#   Defined in .pyfun per provider via fallback_to field.
+#   anthropic → fails → gemini → fails → openrouter → fails → RuntimeError
+#   Visited set prevents infinite loops.
+#
+# SECURITY NOTE:
+#   API keys are NEVER logged or included in exception messages.
+#   All errors are sanitized before propagation — only HTTP status codes
+#   and safe_url (query params stripped) are ever exposed in logs.
+#
+# CACHING NOTE:
+#   Anthropic → prompt_caching (cache_control: ephemeral)
+#     Requires anthropic-beta: prompt-caching-2024-07-31 header.
+#     Caches system prompt + long user prompts (>1024 tokens estimated).
+#     Saves up to 90% input token costs on repeated context.
+#     Enable per provider in .pyfun: supports_cache = "true"
+#
+#   Gemini → Implicit caching (automatic, no extra API call needed)
+#     Google automatically caches repeated prompt prefixes server-side.
+#     No code change needed — Gemini handles it transparently.
+#     Explicit Context Caching API exists but requires separate cache management
+#     and is only worth it for very large static contexts (32k+ tokens).
+#     Enable per provider in .pyfun: supports_cache = "true"
+#     (currently used as log hint only for Gemini — implicit cache is always on)
+#
+# HOW TO ADD A NEW LLM PROVIDER — 3 steps, nothing else to touch:
+#   1. Add class below (copy a dummy, implement complete())
+#   2. Register name → class in _PROVIDER_CLASSES dict
+#   3. Add [LLM_PROVIDER.yourprovider] block in app/.pyfun
+#      → env_key, base_url, default_model, fallback_to
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search registry + fallback chain
+#   tools.py     → calls providers.llm_complete() / providers.search()
+#   mcp.py       → calls providers.list_active_llm() / list_active_search()
+# =============================================================================
+
+import os
+import logging
+import httpx
+
+from . import config
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logger = logging.getLogger("providers")
+
+
+# =============================================================================
+# SECTION 1 — Base Provider
+# Shared HTTP logic — implemented ONCE, reused by all providers.
+# =============================================================================
+
+class BaseProvider:
+    """
+    Base class for all LLM providers.
+    Subclasses only implement complete() — HTTP logic lives here.
+    """
+    def __init__(self, name: str, cfg: dict):
+        self.name          = name
+        self.key           = os.getenv(cfg.get("env_key", ""))
+        self.base_url      = cfg.get("base_url", "")
+        self.fallback      = cfg.get("fallback_to", "")
+        self.timeout       = int(config.get_limits().get("REQUEST_TIMEOUT_SEC", "60"))
+        self.model         = cfg.get("default_model", "")
+        self.supports_cache = cfg.get("supports_cache", "false").lower() == "true"
+        # Safe key hint for debug logs — never log the full key
+        self._key_hint = (
+            f"{self.key[:4]}...{self.key[-4:]}"
+            if self.key and len(self.key) > 8
+            else "***"
+        )
+
+    async def complete(self, prompt: str, model: str, max_tokens: int) -> str:
+        """Override in each provider subclass."""
+        raise NotImplementedError
+
+    async def _post(self, url: str, headers: dict, payload: dict) -> dict:
+        """
+        Shared HTTP POST — used by all providers.
+        Raises RuntimeError with sanitized message on non-2xx responses.
+        API keys are never included in raised exceptions or log output.
+        """
+        safe_url = url.split("?")[0]  # strip query params (may contain API keys)
+        logger.debug(f"POST → {safe_url}")
+        async with httpx.AsyncClient() as client:
+            r = await client.post(
+                url,
+                headers=headers,
+                json=payload,
+                timeout=self.timeout,
+            )
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                # Sanitize: only status code + safe_url, never headers or body
+                raise RuntimeError(
+                    f"HTTP {e.response.status_code} from {safe_url}"
+                ) from None
+            return r.json()
+
+
+# =============================================================================
+# SECTION 2 — LLM Provider Implementations
+# Only the API-specific parsing logic differs per provider.
+# =============================================================================
+
+# --- SmolLM2 (Custom Assistant Space) ----------------------------------------
+class SmolLMProvider(BaseProvider):
+    """
+    SmolLM2 Custom Assistant Space — OpenAI-compatible, ADI routing included.
+    Free tier on HF Spaces (CPU). Falls back to next provider on 503.
+    Response includes extra 'adi' field with score + decision (ignored by hub).
+    Deploy: https://github.com/VolkanSah/Multi-LLM-API-Gateway (smollm-space/)
+
+    .pyfun block:
+        [LLM_PROVIDER.smollm]
+        active        = "true"
+        base_url      = "https://codey-lab-SmolLM2-customs.hf.space/v1"
+        env_key       = "SMOLLM_API_KEY"
+        default_model = "smollm2-360m"
+        models        = "smollm2-360m, codey-lab/model.universal-mcp-hub"
+        fallback_to   = "anthropic"
+        [LLM_PROVIDER.smollm_END]
+    """
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 150) -> str:
+        data = await self._post(
+            f"{self.base_url}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "X-IP-Token":     self.key,
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":      model or self.model,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            },
+        )
+        return data["choices"][0]["message"]["content"]
+
+
+# --- Anthropic ----------------------------------------------------------------
+class AnthropicProvider(BaseProvider):
+    """
+    Anthropic Claude API — Messages endpoint.
+
+    Prompt Caching (supports_cache = "true" in .pyfun):
+        Uses cache_control: ephemeral on system prompt and long user prompts.
+        Requires anthropic-beta: prompt-caching-2024-07-31 header.
+        Cache TTL: 5 minutes, extended on each cache hit.
+        Min tokens to cache: ~1024 (Anthropic requirement).
+        Cost: cache write ~25% more, cache read ~90% less than normal input.
+
+    .pyfun block:
+        [LLM_PROVIDER.anthropic]
+        active           = "true"
+        base_url         = "https://api.anthropic.com/v1"
+        env_key          = "ANTHROPIC_API_KEY"
+        api_version_header = "2023-06-01"
+        default_model    = "claude-haiku-4-5"
+        supports_cache   = "true"
+        fallback_to      = "gemini"
+        [LLM_PROVIDER.anthropic_END]
+    """
+
+    # Rough chars-per-token estimate — avoids importing tiktoken in sandbox
+    _CHARS_PER_TOKEN = 4
+    _CACHE_MIN_TOKENS = 1024
+
+    def _is_cacheable(self, text: str) -> bool:
+        """Estimate if text is long enough to benefit from caching."""
+        return len(text) >= self._CACHE_MIN_TOKENS * self._CHARS_PER_TOKEN
+
+    async def complete(
+        self,
+        prompt: str,
+        model: str = None,
+        max_tokens: int = 1024,
+        system: str = None,
+    ) -> str:
+        cfg = config.get_active_llm_providers().get("anthropic", {})
+
+        headers = {
+            "x-api-key":         self.key,
+            "anthropic-version": cfg.get("api_version_header", "2023-06-01"),
+            "content-type":      "application/json",
+        }
+
+        # --- Build user content ---
+        # Add cache_control if caching enabled + prompt long enough
+        if self.supports_cache and self._is_cacheable(prompt):
+            user_content = [
+                {
+                    "type":          "text",
+                    "text":          prompt,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ]
+            headers["anthropic-beta"] = "prompt-caching-2024-07-31"
+            logger.debug("Anthropic: prompt cache_control applied to user message.")
+        else:
+            user_content = prompt  # short prompt — plain string, no overhead
+
+        payload = {
+            "model":      model or self.model,
+            "max_tokens": max_tokens,
+            "messages":   [{"role": "user", "content": user_content}],
+        }
+
+        # --- Optional system prompt with cache_control ---
+        if system:
+            if self.supports_cache and self._is_cacheable(system):
+                payload["system"] = [
+                    {
+                        "type":          "text",
+                        "text":          system,
+                        "cache_control": {"type": "ephemeral"},
+                    }
+                ]
+                headers["anthropic-beta"] = "prompt-caching-2024-07-31"
+                logger.debug("Anthropic: prompt cache_control applied to system prompt.")
+            else:
+                payload["system"] = system
+
+        data = await self._post(f"{self.base_url}/messages", headers, payload)
+        return data["content"][0]["text"]
+
+
+# --- Gemini ------------------------------------------------------------------
+class GeminiProvider(BaseProvider):
+    """
+    Google Gemini API — generateContent endpoint.
+
+    Implicit Caching (always active on Gemini side, no code needed):
+        Google automatically caches repeated prompt prefixes server-side.
+        No extra API call, no cache key, no TTL management needed.
+        Just send the same prompt structure and Gemini handles the rest.
+        supports_cache = "true" in .pyfun logs cache hint only.
+
+    Explicit Context Caching (NOT implemented here — when to use it):
+        Only worth the extra API complexity for very large static contexts
+        (32k+ tokens, e.g. large documents sent on every request).
+        Requires separate POST to /cachedContents, returns a cache_name,
+        which is then referenced in generateContent as cachedContent.name.
+        Implement as a separate tool (cache_create / cache_use) when needed.
+
+    .pyfun block:
+        [LLM_PROVIDER.gemini]
+        active         = "true"
+        base_url       = "https://generativelanguage.googleapis.com/v1beta"
+        env_key        = "GEMINI_API_KEY"
+        default_model  = "gemini-2.0-flash"
+        supports_cache = "true"
+        fallback_to    = "openrouter"
+        [LLM_PROVIDER.gemini_END]
+    """
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        m        = model or self.model
+        safe_url = f"{self.base_url}/models/{m}:generateContent"
+
+        if self.supports_cache:
+            logger.debug(f"Gemini: implicit caching active for model {m} (server-side, automatic).")
+
+        async with httpx.AsyncClient() as client:
+            r = await client.post(
+                safe_url,
+                params={"key": self.key},  # key in query param, never in logs
+                json={
+                    "contents":         [{"parts": [{"text": prompt}]}],
+                    "generationConfig": {"maxOutputTokens": max_tokens},
+                },
+                timeout=self.timeout,
+            )
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise RuntimeError(
+                    f"HTTP {e.response.status_code} from {safe_url}"
+                ) from None
+            return r.json()["candidates"][0]["content"]["parts"][0]["text"]
+
+
+# --- OpenRouter ---------------------------------------------------------------
+class OpenRouterProvider(BaseProvider):
+    """OpenRouter API — OpenAI-compatible chat completions endpoint.
+
+    Required headers: HTTP-Referer + X-Title (required by OpenRouter for
+    free models and rate limit attribution).
+    """
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        data = await self._post(
+            f"{self.base_url}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "HTTP-Referer":  os.getenv("APP_URL", "https://huggingface.co"),
+                "X-Title":       os.getenv("HUB_NAME", "Universal AI Hub"),  # required!
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":      model or self.model,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            },
+        )
+        return data["choices"][0]["message"]["content"]
+
+
+# --- HuggingFace --------------------------------------------------------------
+class HuggingFaceProvider(BaseProvider):
+    """HuggingFace Inference API — OpenAI-compatible serverless endpoint.
+
+    base_url in .pyfun: https://api-inference.huggingface.co/v1
+    Model goes in payload, not in URL.
+    Free tier: max ~8B models. PRO required for 70B+.
+    """
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 512) -> str:
+        m    = model or self.model
+        data = await self._post(
+            f"{self.base_url}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":      m,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            },
+        )
+        return data["choices"][0]["message"]["content"]
+
+
+# =============================================================================
+# DUMMY PROVIDERS — copy, uncomment, adapt
+# Steps: (1) uncomment class  (2) add to _PROVIDER_CLASSES  (3) add to .pyfun
+# =============================================================================
+
+# --- OpenAI -------------------------------------------------------------------
+# .pyfun block to add:
+#
+#   [LLM_PROVIDER.openai]
+#   active        = "true"
+#   base_url      = "https://api.openai.com/v1"
+#   env_key       = "OPENAI_API_KEY"
+#   default_model = "gpt-4o-mini"
+#   models        = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
+#   fallback_to   = ""
+#   [LLM_PROVIDER.openai_END]
+#
+# class OpenAIProvider(BaseProvider):
+#     """OpenAI API — OpenAI-compatible chat completions endpoint."""
+#
+#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+#         data = await self._post(
+#             f"{self.base_url}/chat/completions",
+#             headers={
+#                 "Authorization": f"Bearer {self.key}",
+#                 "content-type":  "application/json",
+#             },
+#             payload={
+#                 "model":      model or self.model,
+#                 "max_tokens": max_tokens,
+#                 "messages":   [{"role": "user", "content": prompt}],
+#             },
+#         )
+#         return data["choices"][0]["message"]["content"]
+
+
+# --- Mistral ------------------------------------------------------------------
+# .pyfun block to add:
+#
+#   [LLM_PROVIDER.mistral]
+#   active        = "true"
+#   base_url      = "https://api.mistral.ai/v1"
+#   env_key       = "MISTRAL_API_KEY"
+#   default_model = "mistral-large-latest"
+#   models        = "mistral-large-latest, mistral-small-latest, codestral-latest"
+#   fallback_to   = ""
+#   [LLM_PROVIDER.mistral_END]
+#
+# class MistralProvider(BaseProvider):
+#     """Mistral AI API — OpenAI-compatible chat completions endpoint."""
+#
+#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+#         data = await self._post(
+#             f"{self.base_url}/chat/completions",
+#             headers={
+#                 "Authorization": f"Bearer {self.key}",
+#                 "content-type":  "application/json",
+#             },
+#             payload={
+#                 "model":      model or self.model,
+#                 "max_tokens": max_tokens,
+#                 "messages":   [{"role": "user", "content": prompt}],
+#             },
+#         )
+#         return data["choices"][0]["message"]["content"]
+
+
+# --- xAI (Grok) ---------------------------------------------------------------
+# .pyfun block to add:
+#
+#   [LLM_PROVIDER.xai]
+#   active        = "true"
+#   base_url      = "https://api.x.ai/v1"
+#   env_key       = "XAI_API_KEY"
+#   default_model = "grok-3-mini"
+#   models        = "grok-3, grok-3-mini, grok-3-fast"
+#   fallback_to   = ""
+#   [LLM_PROVIDER.xai_END]
+#
+# class XAIProvider(BaseProvider):
+#     """xAI Grok API — OpenAI-compatible chat completions endpoint."""
+#
+#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+#         data = await self._post(
+#             f"{self.base_url}/chat/completions",
+#             headers={
+#                 "Authorization": f"Bearer {self.key}",
+#                 "content-type":  "application/json",
+#             },
+#             payload={
+#                 "model":      model or self.model,
+#                 "max_tokens": max_tokens,
+#                 "messages":   [{"role": "user", "content": prompt}],
+#             },
+#         )
+#         return data["choices"][0]["message"]["content"]
+
+
+# =============================================================================
+# SECTION 3 — Provider Registry
+# Built from .pyfun [LLM_PROVIDERS] at initialize().
+# Maps provider names → classes.
+# To activate a dummy: uncomment class above + add entry here.
+# =============================================================================
+
+_PROVIDER_CLASSES = {
+    "smollm":      SmolLMProvider,
+    "anthropic":   AnthropicProvider,
+    "gemini":      GeminiProvider,
+    "openrouter":  OpenRouterProvider,
+    "huggingface": HuggingFaceProvider,
+    # "openai":   OpenAIProvider,    # ← uncomment to activate
+    # "mistral":  MistralProvider,   # ← uncomment to activate
+    # "xai":      XAIProvider,       # ← uncomment to activate
+}
+
+_registry: dict = {}
+
+
+def initialize() -> None:
+    """
+    Build provider registries from .pyfun [LLM_PROVIDERS] + [SEARCH_PROVIDERS].
+    Called once by mcp.py during startup sequence.
+    Skips providers with missing ENV keys — no crash, just fewer tools.
+    """
+    global _registry
+    active = config.get_active_llm_providers()
+
+    for name, cfg in active.items():
+        env_key = cfg.get("env_key", "")
+        if not env_key or not os.getenv(env_key):
+            logger.info(f"Provider '{name}' skipped — ENV key not set.")
+            continue
+        cls = _PROVIDER_CLASSES.get(name)
+        if not cls:
+            logger.info(f"Provider '{name}' has no handler yet — skipped.")
+            continue
+        _registry[name] = cls(name, cfg)
+        cache_hint = " [cache: ON]" if cfg.get("supports_cache", "false") == "true" else ""
+        logger.info(f"Provider registered: {name}{cache_hint}")
+
+    # Search providers — same key-gating principle
+    _initialize_search()
+
+
+# =============================================================================
+# SECTION 4 — LLM Execution + Fallback Chain
+# =============================================================================
+
+async def llm_complete(
+    prompt: str,
+    provider_name: str = None,
+    model: str = None,
+    max_tokens: int = 1024,
+    system: str = None,
+) -> str:
+    """
+    Send prompt to LLM provider with automatic fallback chain.
+    Fallback order is defined in .pyfun via fallback_to field.
+    Raises RuntimeError if all providers in the chain fail.
+
+    Args:
+        prompt:        Input text to send to the model.
+        provider_name: Provider name override. Defaults to default_provider
+                       from .pyfun [TOOL.llm_complete].
+        model:         Model name override. Defaults to provider's default_model.
+        max_tokens:    Max tokens in response. Default: 1024.
+        system:        Optional system prompt. Passed to providers that support it.
+                       AnthropicProvider caches it automatically if supports_cache = true
+                       and the system prompt is long enough (>= ~1024 tokens).
+
+    Returns:
+        Model response as plain text string.
+    """
+    if not provider_name:
+        tools_cfg     = config.get_active_tools()
+        provider_name = tools_cfg.get("llm_complete", {}).get("default_provider", "anthropic")
+
+    visited = set()
+    current = provider_name
+
+    while current and current not in visited:
+        visited.add(current)
+        provider = _registry.get(current)
+
+        if not provider:
+            logger.warning(f"Provider '{current}' not in registry — trying fallback.")
+        else:
+            try:
+                # Pass system prompt if provider supports it (Anthropic)
+                # Other providers accept **kwargs and ignore unknown params safely
+                if system is not None and hasattr(provider, 'complete'):
+                    import inspect
+                    sig = inspect.signature(provider.complete)
+                    if 'system' in sig.parameters:
+                        result = await provider.complete(prompt, model, max_tokens, system=system)
+                    else:
+                        result = await provider.complete(prompt, model, max_tokens)
+                else:
+                    result = await provider.complete(prompt, model, max_tokens)
+
+                logger.info(f"Response from provider: '{current}'")
+                return f"[{current}] {result}"
+            except Exception as e:
+                # Log only exception type + sanitized message — never raw {e}
+                # which may contain headers, keys, or response bodies
+                logger.warning(
+                    f"Provider '{current}' failed: {type(e).__name__}: {e} — trying fallback."
+                )
+
+        cfg     = config.get_active_llm_providers().get(current, {})
+        current = cfg.get("fallback_to", "")
+
+    raise RuntimeError("All providers failed — no fallback available.")
+
+
+# Alias — used internally by tools.py
+complete = llm_complete
+
+
+# =============================================================================
+# SECTION 5 — Search Execution
+# Same pattern as LLM providers: class + _SEARCH_PROVIDER_CLASSES + fallback.
+# Adding a search provider = add class + register + .pyfun block. Nothing else.
+# =============================================================================
+
+class BaseSearchProvider:
+    """
+    Base class for all search providers.
+    Subclasses only implement search() — HTTP logic lives here.
+    """
+    def __init__(self, name: str, cfg: dict):
+        self.name        = name
+        self.key         = os.getenv(cfg.get("env_key", ""))
+        self.base_url    = cfg.get("base_url", "")
+        self.fallback    = cfg.get("fallback_to", "")
+        self.timeout     = int(config.get_limits().get("SEARCH_TIMEOUT_SEC", "30"))
+        self.default_results = int(cfg.get("default_results", "5"))
+        self.max_results     = int(cfg.get("max_results", "20"))
+        self._key_hint = (
+            f"{self.key[:4]}...{self.key[-4:]}"
+            if self.key and len(self.key) > 8
+            else "***"
+        )
+
+    async def search(self, query: str, max_results: int) -> str:
+        """Override in each search provider subclass."""
+        raise NotImplementedError
+
+    async def _get(self, url: str, headers: dict, params: dict) -> dict:
+        """Shared HTTP GET with sanitized errors (never leak keys/bodies)."""
+        safe_url = url.split("?")[0]
+        async with httpx.AsyncClient() as client:
+            r = await client.get(url, headers=headers, params=params, timeout=self.timeout)
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise RuntimeError(f"HTTP {e.response.status_code} from {safe_url}") from None
+            return r.json()
+
+    async def _post(self, url: str, headers: dict, payload: dict) -> dict:
+        """Shared HTTP POST with sanitized errors."""
+        safe_url = url.split("?")[0]
+        async with httpx.AsyncClient() as client:
+            r = await client.post(url, headers=headers, json=payload, timeout=self.timeout)
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise RuntimeError(f"HTTP {e.response.status_code} from {safe_url}") from None
+            return r.json()
+
+    def _clip(self, max_results: int) -> int:
+        """Clamp requested results into [1, max_results]."""
+        try:
+            n = int(max_results)
+        except (TypeError, ValueError):
+            n = self.default_results
+        return max(1, min(n, self.max_results))
+
+
+# --- Brave Search ---------------------------------------------------------------
+class BraveSearchProvider(BaseSearchProvider):
+    """
+    Brave Search API — web search endpoint.
+    Auth via X-Subscription-Token header (NOT Bearer!).
+
+    .pyfun block:
+        [SEARCH_PROVIDER.brave]
+        active          = "true"
+        base_url        = "https://api.search.brave.com/res/v1/web/search"
+        env_key         = "BRAVE_API_KEY"
+        default_results = "5"
+        max_results     = "20"
+        fallback_to     = "tavily"
+        [SEARCH_PROVIDER.brave_END]
+    """
+
+    async def search(self, query: str, max_results: int = 5) -> str:
+        data = await self._get(
+            self.base_url,
+            headers={
+                "X-Subscription-Token": self.key,
+                "Accept":              "application/json",
+                "Accept-Encoding":     "gzip",
+            },
+            params={
+                "q":     query,
+                "count": self._clip(max_results),
+            },
+        )
+        results = data.get("web", {}).get("results", [])
+        if not results:
+            raise RuntimeError("Brave returned no results")
+        lines = [f"[{self.name}] Search results for: '{query}'"]
+        for i, r in enumerate(results, 1):
+            lines.append(f"{i}. {r.get('title', '')}\n   {r.get('url', '')}\n   {r.get('description', '')}")
+        return "\n\n".join(lines)
+
+
+# --- Tavily ---------------------------------------------------------------------
+class TavilySearchProvider(BaseSearchProvider):
+    """
+    Tavily Search API — AI-optimized web search.
+    include_answer = "true" in .pyfun → adds AI-synthesized answer on top.
+
+    .pyfun block:
+        [SEARCH_PROVIDER.tavily]
+        active          = "true"
+        base_url        = "https://api.tavily.com/search"
+        env_key         = "TAVILY_API_KEY"
+        default_results = "5"
+        max_results     = "10"
+        include_answer  = "true"
+        fallback_to     = ""
+        [SEARCH_PROVIDER.tavily_END]
+    """
+
+    def __init__(self, name: str, cfg: dict):
+        super().__init__(name, cfg)
+        self.include_answer = cfg.get("include_answer", "false").lower() == "true"
+
+    async def search(self, query: str, max_results: int = 5) -> str:
+        data = await self._post(
+            self.base_url,
+            headers={"Content-Type": "application/json"},
+            payload={
+                "api_key":       self.key,   # Tavily takes the key in the payload
+                "query":         query,
+                "max_results":   self._clip(max_results),
+                "include_answer": self.include_answer,
+            },
+        )
+        results = data.get("results", [])
+        if not results and not data.get("answer"):
+            raise RuntimeError("Tavily returned no results")
+        lines = [f"[{self.name}] Search results for: '{query}'"]
+        if self.include_answer and data.get("answer"):
+            lines.append(f"AI answer: {data['answer']}")
+        for i, r in enumerate(results, 1):
+            lines.append(f"{i}. {r.get('title', '')}\n   {r.get('url', '')}\n   {r.get('content', '')}")
+        return "\n\n".join(lines)
+
+
+# =============================================================================
+# Search Registry — built from .pyfun [SEARCH_PROVIDERS] at initialize()
+# =============================================================================
+
+_SEARCH_PROVIDER_CLASSES = {
+    "brave":  BraveSearchProvider,
+    "tavily": TavilySearchProvider,
+    # "serper": SerperSearchProvider,   # ← uncomment to activate
+}
+
+_search_registry: dict = {}
+
+
+def _initialize_search() -> None:
+    """
+    Build search provider registry from .pyfun [SEARCH_PROVIDERS].
+    Called inside initialize() — same key-gating as LLM providers:
+    no ENV key = provider skipped, no crash.
+    """
+    global _search_registry
+    for name, cfg in config.get_active_search_providers().items():
+        env_key = cfg.get("env_key", "")
+        if not env_key or not os.getenv(env_key):
+            logger.info(f"Search provider '{name}' skipped — ENV key not set.")
+            continue
+        cls = _SEARCH_PROVIDER_CLASSES.get(name)
+        if not cls:
+            logger.info(f"Search provider '{name}' has no handler yet — skipped.")
+            continue
+        _search_registry[name] = cls(name, cfg)
+        logger.info(f"Search provider registered: {name}")
+
+
+async def search(
+    query: str,
+    provider_name: str = None,
+    max_results: int = 5,
+) -> str:
+    """
+    Search the web via configured search provider with automatic fallback chain.
+    Fallback order is defined in .pyfun via fallback_to field.
+    Raises RuntimeError if all providers in the chain fail.
+
+    Args:
+        query:         Search query string.
+        provider_name: Provider name override (e.g. 'brave', 'tavily').
+                       Defaults to default_provider from .pyfun [TOOL.web_search].
+        max_results:   Maximum number of results. Default: 5.
+
+    Returns:
+        Formatted search results as plain text string.
+    """
+    if not provider_name:
+        tools_cfg     = config.get_active_tools()
+        provider_name = tools_cfg.get("web_search", {}).get("default_provider", "brave")
+
+    visited = set()
+    current = provider_name
+
+    while current and current not in visited:
+        visited.add(current)
+        provider = _search_registry.get(current)
+
+        if not provider:
+            logger.warning(f"Search provider '{current}' not in registry — trying fallback.")
+        else:
+            try:
+                result = await provider.search(query, max_results)
+                logger.info(f"Search response from provider: '{current}'")
+                return result
+            except Exception as e:
+                logger.warning(
+                    f"Search provider '{current}' failed: {type(e).__name__}: {e} — trying fallback."
+                )
+
+        cfg     = config.get_active_search_providers().get(current, {})
+        current = cfg.get("fallback_to", "")
+
+    raise RuntimeError("All search providers failed — no fallback available.")
+
+
+# =============================================================================
+# SECTION 6 — Registry Helpers
+# Used by mcp.py for tool registration decisions.
+# =============================================================================
+
+def list_active_llm() -> list:
+    """Returns list of active LLM provider names."""
+    return list(_registry.keys())
+
+
+def list_active_search() -> list:
+    """Returns list of active search provider names."""
+    return list(_search_registry.keys())
+
+
+def get(name: str) -> BaseProvider:
+    """Get a specific provider instance by name."""
+    return _registry.get(name)
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/shellmaster.py

@@ -0,0 +1,323 @@
+# =============================================================================
+# app/shellmaster.py
+# ShellMaster 2.0 — Modular Shell Tool
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Multi-LLM-API-Gateway
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   Modular tool living in app/* only.
+#   NO low-level access, NO os.environ, NO fundaments access.
+#   Config comes from app/.pyfun [TOOL.shellmaster] via app/config.py.
+#   LLM (SmolLM2) generates commands — shellmaster validates + confirms + executes.
+#
+# FLOW:
+#   tools.py calls shellmaster.run(user_input)
+#       ↓
+#   LLM generates JSON {command, backup, recovery, risk}
+#       ↓
+#   validate against JSONL registry (local file or HF Dataset)
+#       ↓
+#   return confirmation request to user (NEVER auto-execute!)
+#       ↓
+#   user confirms → send to agent → return output
+#       ↓
+#   store recovery plan in db_sync
+#
+# CONFIRMATION FLOW:
+#   Every command requires explicit user confirmation.
+#   High-risk commands require backup + recovery plan from LLM.
+#   Recovery plan is stored in db_sync hub_state for later use.
+# =============================================================================
+
+import json
+import logging
+import os
+import httpx
+from pathlib import Path
+from typing import Optional
+
+from . import config
+from . import db_sync
+
+logger = logging.getLogger("shellmaster")
+
+# =============================================================================
+# HARDCODED BLOCKS — cannot be overridden by registry or LLM
+# Both Unix and Windows covered
+# =============================================================================
+_HARDCODED_BLOCKED = {
+    # ── Unix destructive ──────────────────────────────────────────────────────
+    "rm -rf", "rm -r /", "rm -f /",
+    "mkfs", "dd if=", "> /dev/sd", "> /dev/hd",
+    "shred /dev/", "wipefs",
+    # ── Windows destructive ───────────────────────────────────────────────────
+    "format c:", "format d:", "format /fs",
+    "rmdir /s", "rd /s", "del /f /s /q c:\\",
+    # ── Unix system destruction ───────────────────────────────────────────────
+    ":(){ :|:& };:",
+    "chmod -r 777 /", "chmod -r 000 /", "chmod 000 /",
+    "chown -r root /", "chown -r 0:0 /",
+    # ── Windows system destruction ────────────────────────────────────────────
+    "icacls c:\\ /grant", "icacls c:\\ /deny",
+    "takeown /f c:\\",
+    "reg delete hklm", "reg delete hkcu",
+    # ── Unix privilege escalation ─────────────────────────────────────────────
+    "sudo su", "sudo -i", "sudo -s",
+    "su root", "su -", "passwd root", "visudo",
+    # ── Windows privilege escalation ──────────────────────────────────────────
+    "runas /user:administrator",
+    "net user administrator",
+    "net localgroup administrators",
+    "psexec -s",
+    # ── Critical system files — Unix ─────────────────────────────────────────
+    "/etc/passwd", "/etc/shadow", "/etc/sudoers",
+    "/etc/crontab", "/boot/", "/proc/sysrq",
+    # ── Critical system files — Windows ──────────────────────────────────────
+    "c:\\windows\\system32\\", "c:\\windows\\system\\",
+    "hklm\\system", "hklm\\security",
+    # ── Shutdown/reboot — Unix ────────────────────────────────────────────────
+    "reboot", "halt", "poweroff",
+    "init 0", "init 6",
+    "systemctl poweroff", "systemctl reboot", "systemctl halt",
+    # ── Shutdown/reboot — Windows ─────────────────────────────────────────────
+    "shutdown /s", "shutdown /r", "shutdown /h",
+    # ── Network destruction ───────────────────────────────────────────────────
+    "iptables -f", "iptables --flush", "ufw disable",
+    "netsh firewall set opmode disable",
+    "netsh advfirewall set allprofiles state off",
+}
+
+
+def _is_hardblocked(cmd_str: str) -> bool:
+    """Check if command contains any hardcoded blocked pattern."""
+    cmd_lower = cmd_str.lower().strip()
+    return any(blocked in cmd_lower for blocked in _HARDCODED_BLOCKED)
+
+
+# =============================================================================
+# Module State — populated by initialize()
+# =============================================================================
+_cfg         = {}
+_agent_url   = ""
+_token       = ""
+_cmd_file    = Path("shellmaster_commands.jsonl")
+_timeout     = 30
+_initialized = False
+
+
+# =============================================================================
+# Initialization — called by app/app.py
+# =============================================================================
+
+async def initialize() -> None:
+    """
+    Initialize ShellMaster from app/.pyfun [TOOL.shellmaster].
+    Called by app/app.py — never reads os.environ directly.
+    """
+    global _cfg, _agent_url, _token, _cmd_file, _timeout, _initialized
+
+    tools_cfg = config.get_active_tools()
+    _cfg      = tools_cfg.get("shellmaster", {})
+
+    if not _cfg or _cfg.get("active", "false").lower() != "true":
+        logger.info("ShellMaster not active in .pyfun — skipped")
+        return
+
+    _agent_url = _cfg.get("shellmaster_agent_url", "http://localhost:5004")
+    # Token: ENV zuerst (shellmaster_env_key → .env, Guardian lädt ENV) —
+    # das .pyfun-Feld ist nur noch Fallback. Secrets gehören NICHT in .pyfun
+    # (gleiche Regel wie bei allen Providern: env_key = NAME, Wert in .env).
+    env_key  = _cfg.get("shellmaster_env_key", "")
+    _token   = os.getenv(env_key, "") if env_key else ""
+    if not _token:
+        _token = _cfg.get("shellmaster_token", "")
+    _timeout   = int(_cfg.get("timeout_sec", "30"))
+
+    # Command registry — local file first
+    cmd_file_path = _cfg.get("shellmaster_commands_file", "shellmaster_commands.jsonl")
+    _cmd_file     = Path(cmd_file_path)
+
+    if not _token:
+        logger.warning("ShellMaster: shellmaster_token not set in .pyfun — disabled")
+        return
+
+    if not _cmd_file.exists():
+        logger.warning(f"ShellMaster: commands file not found: {_cmd_file} — disabled")
+        return
+
+    allowed = sum(
+        1 for line in _cmd_file.open()
+        if line.strip() and json.loads(line).get("allowed", False)
+    )
+    logger.info(f"ShellMaster initialized | agent: {_agent_url} | allowed commands: {allowed}")
+    _initialized = True
+
+
+# =============================================================================
+# Command Registry
+# =============================================================================
+
+def _load_registry() -> dict:
+    """
+    Load command registry from local JSONL.
+    Hot-reloaded on each call — no restart needed for registry changes.
+    TODO: merge with HF Dataset registry if shellmaster_commands_dataset is set.
+    """
+    registry = {}
+    try:
+        with open(_cmd_file) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                cmd = json.loads(line)
+                registry[cmd["id"]] = cmd
+    except Exception as e:
+        logger.error(f"Registry load failed: {type(e).__name__}: {e}")
+    return registry
+
+
+def _validate_command(cmd_str: str) -> tuple[bool, str]:
+    """
+    Validate a command string against registry + hardblock list.
+
+    Returns:
+        (True, command_id) if valid and allowed
+        (False, reason)    if blocked
+    """
+    # Hardblock first — no exceptions
+    if _is_hardblocked(cmd_str):
+        return False, "blocked by system policy"
+
+    # Match against registry
+    registry = _load_registry()
+    cmd_lower = cmd_str.lower().strip()
+
+    for cmd_id, cmd in registry.items():
+        # Check both unix and win templates
+        for os_key in ("unix", "win"):
+            template_base = cmd.get(os_key, "").split()[0].lower()
+            if template_base and cmd_lower.startswith(template_base):
+                if not cmd.get("allowed", False):
+                    return False, f"command '{cmd_id}' is blocked in registry"
+                return True, cmd_id
+
+    return False, f"command not found in registry: {cmd_str[:50]}"
+
+
+def list_commands(category: str = None) -> list:
+    """List allowed commands, optionally filtered by category."""
+    cmds = [c for c in _load_registry().values() if c.get("allowed", False)]
+    if category:
+        cmds = [c for c in cmds if c.get("category") == category]
+    return cmds
+
+
+# =============================================================================
+# Confirmation Flow
+# =============================================================================
+
+def build_confirmation(llm_result: dict) -> str:
+    """
+    Build confirmation message from LLM-generated command plan.
+    Returns formatted string for user to confirm/deny.
+    """
+    command  = llm_result.get("command", "")
+    backup   = llm_result.get("backup", "")
+    recovery = llm_result.get("recovery", "")
+    risk     = llm_result.get("risk", "unknown").upper()
+
+    lines = [
+        f"⚠️  ShellMaster — Confirmation Required",
+        f"",
+        f"Command:  {command}",
+        f"Risk:     {risk}",
+    ]
+
+    if backup:
+        lines.append(f"Backup:   {backup}")
+    if recovery:
+        lines.append(f"Recovery: {recovery}")
+
+    lines += [
+        f"",
+        f"Type 'confirm shellmaster' to execute or 'cancel' to abort.",
+    ]
+    return "\n".join(lines)
+
+
+async def store_recovery_plan(command: str, backup: str, recovery: str) -> None:
+    """Store recovery plan in db_sync hub_state for later use."""
+    try:
+        await db_sync.write("shellmaster.last_command", {
+            "command":  command,
+            "backup":   backup,
+            "recovery": recovery,
+        })
+        logger.info("ShellMaster: recovery plan stored in db_sync")
+    except Exception as e:
+        logger.warning(f"ShellMaster: recovery plan store failed: {type(e).__name__}")
+
+
+async def get_recovery_plan() -> dict:
+    """Retrieve last recovery plan from db_sync."""
+    return await db_sync.read("shellmaster.last_command", default={})
+
+
+# =============================================================================
+# Agent Execution — only called after explicit user confirmation
+# =============================================================================
+
+async def execute_confirmed(command: str) -> str:
+    """
+    Execute a command on the local agent.
+    ONLY called after explicit user confirmation — never auto-execute!
+
+    Args:
+        command: Raw shell command string (already validated).
+
+    Returns:
+        Command output or error message.
+    """
+    if not _initialized:
+        return "ShellMaster not initialized."
+
+    # Final hardblock check before sending to agent
+    if _is_hardblocked(command):
+        logger.warning(f"HARDBLOCK on confirmed command: {command[:60]}")
+        return "Blocked by system policy — cannot execute."
+
+    try:
+        async with httpx.AsyncClient() as client:
+            r = await client.post(
+                f"{_agent_url}/command",
+                json={"command": command},
+                headers={
+                    "Authorization": f"Bearer {_token}",
+                    "Content-Type":  "application/json",
+                },
+                timeout=_timeout,
+            )
+            r.raise_for_status()
+            data = r.json()
+            output = data.get("result", data.get("output", ""))
+            logger.info(f"ShellMaster executed: {command[:60]}")
+            return output
+
+    except httpx.ConnectError:
+        return f"ShellMaster Agent not reachable at {_agent_url} — is it running?"
+    except httpx.HTTPStatusError as e:
+        return f"Agent error: HTTP {e.response.status_code}"
+    except Exception as e:
+        logger.warning(f"ShellMaster execute failed: {type(e).__name__}: {e}")
+        return f"Error: {type(e).__name__}"
+
+
+def is_ready() -> bool:
+    return _initialized
+
+
+def get_config() -> dict:
+    return _cfg

app/tools.py

@@ -0,0 +1,276 @@
+# =============================================================================
+# app/tools.py
+# Tool Registry — Modular Wrapper
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+# TOOL REGISTRY PRINCIPLE:
+#   Tools are defined in .pyfun [TOOLS] — never hardcoded here.
+#   Adding a new tool = update .pyfun only. Never touch this file.
+#   config.py parses [TOOLS] and delivers ready-to-use dicts.
+#
+# DEPENDENCY CHAIN:
+#   .pyfun → config.py → tools.py → mcp.py
+#   tools.py delegates execution to providers.py — never calls APIs directly.
+# =============================================================================
+
+import logging
+import os
+from typing import Any, Dict, Optional
+
+from . import config     # reads app/.pyfun — single source of truth
+from . import providers  # LLM + Search execution + fallback chain
+from . import db_sync
+
+logger = logging.getLogger("tools")
+
+# =============================================================================
+# Internal Registry — built from .pyfun [TOOLS] at initialize()
+# =============================================================================
+_registry: Dict[str, Dict] = {}
+
+
+# =============================================================================
+# Initialization — called by app/app.py (parameterless, sandboxed)
+# =============================================================================
+
+def initialize() -> None:
+    """
+    Builds the tool registry from .pyfun [TOOLS].
+    Called once by app/app.py during startup sequence.
+    No fundaments passed in — fully sandboxed.
+
+    Loads all active tools and their config (description, provider_type,
+    default_provider, timeout_sec, system_prompt, etc.) into _registry.
+    Inactive tools (active = "false") are skipped silently.
+    """
+    global _registry
+    _registry = config.get_active_tools()
+    logger.info(f"Tools loaded: {list(_registry.keys())}")
+
+
+# =============================================================================
+# Public API — used by mcp.py tool handlers
+# =============================================================================
+
+async def run(
+    tool_name: str,
+    prompt: Optional[str] = None,
+    provider_name: Optional[str] = None,
+    model: Optional[str] = None,
+    max_tokens: int = 1024,
+    max_results: int = 5,
+    **params: Any,
+) -> str:
+    """
+    Execute a tool by name.
+    Reads tool config from registry, delegates to providers.py / db_sync.py.
+    Applies system_prompt from .pyfun if defined.
+
+    Args:
+        tool_name:     Tool name as defined in .pyfun [TOOLS] (e.g. 'llm_complete').
+        prompt:        User input / query string. For db tools this is the SQL query.
+        provider_name: Override provider. Defaults to tool's default_provider in .pyfun.
+        model:         Override model. Defaults to provider's default_model in .pyfun.
+        max_tokens:    Max tokens for LLM response. Default: 1024.
+        max_results:   Max results for search tools. Default: 5.
+        **params:      Ignored extras — keeps /api calls with unknown keys from crashing.
+
+    Returns:
+        Tool response as plain text string.
+
+    Raises:
+        ValueError:   If tool_name is not found in registry or prompt is missing.
+        RuntimeError: If all providers fail (propagated from providers.py).
+    """
+    tool_cfg = _registry.get(tool_name)
+    if not tool_cfg:
+        raise ValueError(f"Tool '{tool_name}' not found in registry or not active.")
+
+    provider_type    = tool_cfg.get("provider_type", "llm")
+    default_provider = provider_name or tool_cfg.get("default_provider", "")
+    system_prompt    = tool_cfg.get("system_prompt", "")
+
+    # prompt ist für llm/search/db Pflicht — sauberer 400er statt TypeError/500er
+    # persist ist die Ausnahme: ohne state_read_key braucht es einen prompt,
+    # mit state_read_key liest es stattdessen aus hub_state (Gedächtnis-Pattern).
+    if provider_type in ("llm", "search", "db") and (prompt is None or str(prompt).strip() == ""):
+        raise ValueError(
+            f"Tool '{tool_name}' requires a 'prompt' parameter (for db tools: the SQL query)."
+        )
+    if provider_type == "persist" and not tool_cfg.get("state_read_key", "") \
+            and (prompt is None or str(prompt).strip() == ""):
+        raise ValueError(
+            "persist_result requires 'prompt' (or set state_read_key in .pyfun [TOOL.persist_result])."
+        )
+
+    # Build full prompt — prepend system_prompt if defined in .pyfun
+    full_prompt = f"{system_prompt}\n\n{prompt}".strip() if system_prompt else prompt
+
+    # --- LLM tools ---
+    if provider_type == "llm":
+        return await providers.llm_complete(
+            prompt=full_prompt,
+            provider_name=default_provider,
+            model=model,
+            max_tokens=max_tokens,
+        )
+
+    # --- Search tools ---
+    if provider_type == "search":
+        return await providers.search(
+            query=prompt,
+            provider_name=default_provider,
+            max_results=max_results or int(tool_cfg.get("default_results", "5")),
+        )
+
+    # --- DB tools (read-only, delegated to db_sync when ready) ---
+    if provider_type == "db":
+        sql = prompt  # prompt ist hier die SQL-Query
+        return await db_sync.query(sql)
+
+    # --- Persist tools (Gedächtnis-Orchestrierung: SQLite-Queue → PostgreSQL) ---
+    # NIEMALS direkt an PG schreiben — enqueue in die restart-safe Queue,
+    # dann EINEN best-effort Flush-Versuch. Ohne DATABASE_URL = status "queued",
+    # kein Crash. Der Background-Flusher (db_sync) retries später automatisch.
+    if provider_type == "persist":
+        key    = tool_cfg.get("state_read_key", "")
+        table  = tool_cfg.get("target_table", "hub_results")
+        source = str(params.get("source") or tool_name)
+        # score: optionaler Slot für den Bullshit-Filter (Nutzer-eigenes Scoring).
+        # Wird 1:1 durchgereicht — KEIN Tool hier interpretiert oder berechnet ihn.
+        try:
+            score = float(params["score"]) if params.get("score") is not None else None
+        except (TypeError, ValueError):
+            score = None
+        data  = await db_sync.read(key) if key else {"prompt": prompt}
+        depth = await db_sync.enqueue_persist(
+            table, payload=data, source=source, model=model or "", score=score,
+        )
+        flush = await db_sync.flush_persist_queue()  # best effort — sofortiger Versuch
+        if flush.get("flushed", 0) > 0:
+            status, note = "persisted", "written to PostgreSQL"
+        else:
+            status, note = "queued", "restart-safe in SQLite — flushes to PostgreSQL when the bridge becomes active"
+        return {
+            "status":        status,
+            "target_table":  table,
+            "queue_depth":   depth,
+            "flushed":       flush.get("flushed", 0),
+            "note":          note,
+        }
+
+    # --- Unknown provider type ---
+    logger.warning(f"Tool '{tool_name}' has unknown provider_type '{provider_type}' — skipped.")
+    return f"Tool '{tool_name}' provider type '{provider_type}' is not yet implemented."
+
+
+# =============================================================================
+# Registry helpers — used by mcp.py and system tools
+# =============================================================================
+
+def get(tool_name: str) -> Dict[str, Any]:
+    """
+    Get full config dict for a tool.
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Tool config dict, or empty dict if not found.
+    """
+    return _registry.get(tool_name, {})
+
+
+def get_description(tool_name: str) -> str:
+    """
+    Get the description of a tool (from .pyfun).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Description string, or empty string if not found.
+    """
+    return _registry.get(tool_name, {}).get("description", "")
+
+
+def get_system_prompt(tool_name: str) -> str:
+    """
+    Get the system_prompt of a tool (from .pyfun).
+    Returns empty string if no system_prompt is defined.
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        System prompt string, or empty string if not configured.
+    """
+    return _registry.get(tool_name, {}).get("system_prompt", "")
+
+
+def get_timeout(tool_name: str) -> int:
+    """
+    Get the timeout in seconds for a tool (from .pyfun).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Timeout in seconds (int). Defaults to 60 if not configured.
+    """
+    return int(_registry.get(tool_name, {}).get("timeout_sec", "60"))
+
+
+def get_provider_type(tool_name: str) -> str:
+    """
+    Get the provider_type of a tool (llm | search | db | image | sandbox).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Provider type string, or empty string if not found.
+    """
+    return _registry.get(tool_name, {}).get("provider_type", "")
+
+
+def list_all() -> list:
+    """
+    List all active tool names from registry.
+
+    Returns:
+        List of active tool name strings.
+    """
+    return list(_registry.keys())
+
+
+def list_by_type(provider_type: str) -> list:
+    """
+    List all active tools of a specific provider_type.
+
+    Args:
+        provider_type: e.g. 'llm', 'search', 'db', 'image', 'sandbox'.
+
+    Returns:
+        List of tool name strings matching the provider_type.
+    """
+    return [
+        name for name, cfg in _registry.items()
+        if cfg.get("provider_type", "") == provider_type
+    ]
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

example-mcp___.env

@@ -0,0 +1,86 @@
+# ===========================================
+# .env.example — Multi-LLM-API-Gateway
+# Copy this file to .env and fill in the values.
+# IMPORTANT: Never commit the .env file to version control.
+# ===========================================
+# ARCHITECTURE NOTE:
+#   The Guardian (main.py) is the ONLY process that reads this file.
+#   app/* modules NEVER touch .env — they get ENV-VAR NAMES via app/.pyfun
+#   and the values are read with os.getenv() inside the sandbox boundary.
+#
+#   No key set = provider skipped = tool not registered = NO CRASH.
+# ===========================================
+
+# --- LLM Provider Keys ---
+# Which providers activate is defined in app/.pyfun [LLM_PROVIDERS].
+# A provider only registers when its ENV key here is set.
+
+# Anthropic (api.anthropic.com)
+ANTHROPIC_API_KEY=""
+
+# Google Gemini (generativelanguage.googleapis.com)
+GEMINI_API_KEY=""
+
+# OpenRouter (openrouter.ai) — free models available
+OPENROUTER_API_KEY=""
+
+# HuggingFace Inference API (api-inference.huggingface.co)
+HF_TOKEN=""
+
+# SmolLM2 custom Space (your own deployment)
+SMOLLM_API_KEY=""
+
+# --- Search Provider Keys ---
+# Activate search by setting at least one of these.
+
+# Brave Search (api.search.brave.com)
+BRAVE_API_KEY=""
+
+# Tavily (api.tavily.com) — AI-optimized search
+TAVILY_API_KEY=""
+
+# --- App Identity (optional) ---
+# Used by OpenRouter HTTP-Referer header (rate limit attribution)
+APP_URL="https://huggingface.co/spaces/codey-lab/Universal-MCP-Hub"
+
+# ===========================================
+# PyFundaments CORE CONFIGURATION
+# ===========================================
+
+# --- Database Connection (PostgreSQL) ---
+# The complete Data Source Name (DSN) for your PostgreSQL database.
+# This works for both local instances and cloud providers like Neon.tech.
+# Example for Neon: postgresql://user:password@host.eu-central-1.aws.neon.tech/neondb?sslmode=require
+# Example for local: postgresql://user:password@localhost:5432/mydb
+# Leave empty or comment out if your app doesn't need database
+DATABASE_URL="your_database_dsn_here"
+
+# --- Application-Level Encryption Keys ---
+# These keys are used by the application itself to encrypt sensitive data
+# before it is written to the database.
+# The master key must be a 256-bit key (32 bytes).
+MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
+
+# The salt is a unique, persistent value used with the master key.
+# It should also be a secure, random string.
+PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
+
+# ===========================================
+# LOGGING CONFIGURATION (Optional)
+# ===========================================
+
+# PyFundaments Debug Mode (true = startup diagnostics: Python version,
+# sys.path, file checks). Only needed while developing — false for normal use.
+PYFUNDAMENTS_DEBUG="false"
+
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# INFO is enough for daily operation; DEBUG only while hunting a bug.
+LOG_LEVEL="INFO"
+
+# Store logs in /tmp directory (cleared on restart, host-local only)
+LOG_TO_TMP="false"
+
+# Public logging — CAREFUL: stdout logs are PUBLICLY VISIBLE on HF Spaces
+# (Space -> Logs tab). Set to "false" for production. Only keep "true"
+# while actively debugging a deployment.
+ENABLE_PUBLIC_LOGS="false"

fundaments/__init__.py

@@ -0,0 +1 @@
+

fundaments/access_control.py

@@ -0,0 +1,247 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# access_control.py
+# This is the standalone module for access control.
+# It is intended to be imported by main.py or app.py.
+
+import sys
+from typing import Optional, List, Dict, Any
+
+# Your foundational PostgreSQL module is imported here.
+# IMPORTANT: Ensure 'postgresql.py' is in the same directory or accessible
+# via the Python path.
+from fundaments import postgresql as db
+# local db use: db.execute_secured_query(), db.init_db_pool(), etc. but this fundaments are optimized for clouds
+
+
+# If asyncpg is not installed, exit the script gracefully.
+try:
+    import asyncpg
+except ImportError:
+    print("Error: The 'asyncpg' library is required. Please install it with 'pip install asyncpg'.")
+    sys.exit(1)
+
+
+class AccessControl:
+    """
+    Asynchronous class for managing access control.
+    It builds directly on the functions of your secure database module.
+    This is the layer that uses the foundation without modifying it.
+
+    How to extend this class:
+    To add new functionality, simply create a new asynchronous method
+    within this class. This method can call the `db.execute_secured_query`
+    function to interact with the database. For example:
+
+    async def get_user_last_login(self):
+        sql = "SELECT last_login FROM users WHERE id = $1"
+        result = await db.execute_secured_query(sql, self.user_id, fetch_method='fetchrow')
+        return result['last_login'] if result else None
+    """
+    def __init__(self, user_id: Optional[int] = None):
+        self.user_id = user_id
+
+    async def has_permission(self, permission_name: str, user_id: Optional[int] = None) -> bool:
+        """
+        Checks if the user has a specific permission.
+        Uses the secure execute_secured_query function from the foundation.
+
+        Args:
+            permission_name: Name of the permission to check.
+            user_id:         Optional override — lets Security.check_permission()
+                             check ANY user without constructing a new instance.
+                             Falls back to the constructor user_id.
+        """
+        effective_user_id = user_id if user_id is not None else self.user_id
+        if effective_user_id is None:
+            return False
+
+        # SQL Query Explanation:
+        # This query counts the number of rows where the user (user_id)
+        # has a role (user_role_assignments) that is linked to a permission
+        # (role_permissions) which has the specified name (user_permissions.name).
+        # If the count is > 0, the user has the permission.
+        sql = """
+            SELECT COUNT(*) AS count
+            FROM user_role_assignments ura
+            JOIN role_permissions rp ON ura.role_id = rp.role_id
+            JOIN user_permissions up ON rp.permission_id = up.id
+            WHERE ura.user_id = $1 AND up.name = $2
+        """
+        try:
+            result = await db.execute_secured_query(
+                sql,
+                effective_user_id,
+                permission_name,
+                fetch_method='fetchrow'
+            )
+            return result['count'] > 0
+        except Exception as e:
+            # Error handling is managed by your postgresql module.
+            # We just re-raise the exception here to propagate it.
+            raise Exception(f'Failed to check permission: {e}')
+
+    async def get_user_permissions(self) -> List[Dict[str, Any]]:
+        """Returns all permissions for a user."""
+        if self.user_id is None:
+            return []
+
+        # SQL Query Explanation:
+        # This query retrieves all distinct permission names and descriptions
+        # associated with the user's roles. `DISTINCT` ensures each permission
+        # is listed only once.
+        sql = """
+            SELECT DISTINCT up.name, up.description
+            FROM user_role_assignments ura
+            JOIN role_permissions rp ON ura.role_id = rp.role_id
+            JOIN user_permissions up ON rp.permission_id = up.id
+            WHERE ura.user_id = $1
+            ORDER BY up.name
+        """
+        try:
+            return await db.execute_secured_query(sql, self.user_id)
+        except Exception as e:
+            raise Exception(f'Failed to get user permissions: {e}')
+
+    async def get_user_roles(self) -> List[Dict[str, Any]]:
+        """Returns all roles for a user."""
+        if self.user_id is None:
+            return []
+
+        # SQL Query Explanation:
+        # This query selects the details (id, name, description) of the roles
+        # that are assigned to the specified user (user_id) in the
+        # `user_role_assignments` table.
+        sql = """
+            SELECT r.id, r.name, r.description
+            FROM user_role_assignments ura
+            JOIN user_roles r ON ura.role_id = r.id
+            WHERE ura.user_id = $1
+            ORDER BY r.name
+        """
+        try:
+            return await db.execute_secured_query(sql, self.user_id)
+        except Exception as e:
+            raise Exception(f'Failed to get user roles: {e}')
+
+    async def assign_role(self, role_id: int) -> None:
+        """Assigns a role to a user."""
+        if self.user_id is None:
+            raise Exception('No user specified')
+
+        # SQL Query Explanation:
+        # Inserts a new row into the `user_role_assignments` table to create
+        # the relationship between a user and a role.
+        sql = "INSERT INTO user_role_assignments (user_id, role_id) VALUES ($1, $2)"
+        try:
+            await db.execute_secured_query(
+                sql,
+                self.user_id,
+                role_id,
+                fetch_method='execute'
+            )
+        except Exception as e:
+            raise Exception(f'Failed to assign role: {e}')
+
+    async def remove_role(self, role_id: int) -> None:
+        """Removes a role from a user."""
+        if self.user_id is None:
+            raise Exception('No user specified')
+
+        # SQL Query Explanation:
+        # Deletes the row from the `user_role_assignments` table that matches
+        # the specified user ($1) and role ($2).
+        sql = "DELETE FROM user_role_assignments WHERE user_id = $1 AND role_id = $2"
+        try:
+            await db.execute_secured_query(
+                sql,
+                self.user_id,
+                role_id,
+                fetch_method='execute'
+            )
+        except Exception as e:
+            raise Exception(f'Failed to remove role: {e}')
+
+    async def get_all_roles(self) -> List[Dict[str, Any]]:
+        """Returns all available roles."""
+        # SQL Query Explanation:
+        # Selects all roles from the `user_roles` table.
+        sql = "SELECT id, name, description FROM user_roles ORDER BY name"
+        try:
+            return await db.execute_secured_query(sql)
+        except Exception as e:
+            raise Exception(f'Failed to get roles: {e}')
+
+    async def get_all_permissions(self) -> List[Dict[str, Any]]:
+        """Returns all available permissions."""
+        # SQL Query Explanation:
+        # Selects all permissions from the `user_permissions` table.
+        sql = "SELECT id, name, description FROM user_permissions ORDER BY name"
+        try:
+            return await db.execute_secured_query(sql)
+        except Exception as e:
+            raise Exception(f'Failed to get permissions: {e}')
+
+    async def create_role(self, name: str, description: str) -> int:
+        """Creates a new role."""
+        # SQL Query Explanation:
+        # Inserts a new role into the `user_roles` table and returns the
+        # automatically generated ID of the new role (`RETURNING id`).
+        sql = "INSERT INTO user_roles (name, description) VALUES ($1, $2) RETURNING id"
+        try:
+            result = await db.execute_secured_query(
+                sql,
+                name,
+                description,
+                fetch_method='fetchrow'
+            )
+            return result['id']
+        except Exception as e:
+            raise Exception(f'Failed to create role: {e}')
+
+    async def update_role_permissions(self, role_id: int, permission_ids: List[int]) -> None:
+        """Updates the permissions for a role."""
+        # IMPORTANT: Since your module does not handle transactions across multiple
+        # queries, we perform these actions sequentially. Query-level security
+        # is guaranteed by your module.
+        try:
+            # SQL Query Explanation:
+            # Deletes all existing permissions for the given role.
+            sql_delete = "DELETE FROM role_permissions WHERE role_id = $1"
+            await db.execute_secured_query(sql_delete, role_id, fetch_method='execute')
+
+            # SQL Query Explanation:
+            # Inserts a new row for each permission_id passed into the
+            # `role_permissions` table.
+            if permission_ids:
+                sql_insert = "INSERT INTO role_permissions (role_id, permission_id) VALUES ($1, $2)"
+                for permission_id in permission_ids:
+                    await db.execute_secured_query(
+                        sql_insert,
+                        role_id,
+                        permission_id,
+                        fetch_method='execute'
+                    )
+        except Exception as e:
+            # If an error occurs, the underlying foundation will log the issue.
+            # We re-raise the error here.
+            raise Exception(f'Failed to update role permissions: {e}')
+
+    async def get_role_permissions(self, role_id: int) -> List[Dict[str, Any]]:
+        """Returns all permissions for a role."""
+        # SQL Query Explanation:
+        # Selects the details (id, name, description) of all permissions
+        # linked to the specified role.
+        sql = """
+            SELECT p.id, p.name, p.description
+            FROM role_permissions rp
+            JOIN user_permissions p ON rp.permission_id = p.id
+            WHERE rp.role_id = $1
+            ORDER BY p.name
+        """
+        try:
+            return await db.execute_secured_query(sql, role_id)
+        except Exception as e:
+            raise Exception(f'Failed to get role permissions: {e}')

fundaments/config_handler.py

@@ -0,0 +1,115 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/config_handler.py
+# This module loads environment variables without validation.
+# Validation is handled by main.py based on required services.
+import os
+import sys
+from dotenv import load_dotenv
+from typing import Optional, Dict, Any
+
+class ConfigHandler:
+    """
+    A universal configuration loader that reads all environment variables
+    without imposing requirements. This ensures the config handler never
+    needs updates regardless of what services are used.
+    
+    Validation is delegated to main.py which knows what services are needed.
+    """
+    
+    def __init__(self):
+        """
+        Loads all environment variables from .env file and system environment.
+        No validation is performed - that's main.py's responsibility.
+        """
+        load_dotenv()
+        self.config = {}
+        self.load_all_config()
+    
+    def load_all_config(self):
+        """
+        Loads all available environment variables into the config dictionary.
+        No validation - main.py decides what's required based on enabled services.
+        """
+        # Load all environment variables
+        for key, value in os.environ.items():
+            if value:  # Only store non-empty values
+                self.config[key] = value
+    
+    def get(self, key: str) -> Optional[str]:
+        """
+        Retrieves a configuration value by key.
+        Returns None if the key doesn't exist.
+        
+        Args:
+            key: The environment variable name
+            
+        Returns:
+            The value as string or None if not found
+        """
+        return self.config.get(key)
+    
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        """
+        Retrieves a boolean configuration value.
+        Recognizes: true, false, 1, 0, yes, no (case insensitive)
+        
+        Args:
+            key: The environment variable name
+            default: Default value if key not found
+            
+        Returns:
+            Boolean value
+        """
+        value = self.get(key)
+        if value is None:
+            return default
+        
+        return value.lower() in ('true', '1', 'yes', 'on')
+    
+    def get_int(self, key: str, default: int = 0) -> int:
+        """
+        Retrieves an integer configuration value.
+        
+        Args:
+            key: The environment variable name
+            default: Default value if key not found or invalid
+            
+        Returns:
+            Integer value
+        """
+        value = self.get(key)
+        if value is None:
+            return default
+        
+        try:
+            return int(value)
+        except ValueError:
+            return default
+    
+    def has(self, key: str) -> bool:
+        """
+        Checks if a configuration key exists and has a non-empty value.
+        
+        Args:
+            key: The environment variable name
+            
+        Returns:
+            True if key exists and has value, False otherwise
+        """
+        return key in self.config and bool(self.config[key])
+    
+    def get_all(self) -> Dict[str, str]:
+        """
+        Returns all loaded configuration as a dictionary.
+        Useful for debugging or passing to other services.
+        
+        Returns:
+            Dictionary of all loaded environment variables
+        """
+        return self.config.copy()
+
+# Global singleton instance
+config_service = ConfigHandler()

fundaments/debug.py

@@ -0,0 +1,91 @@
+import os
+import sys
+import importlib.util
+import datetime
+import logging
+from logging.handlers import RotatingFileHandler
+
+class PyFundamentsDebug:
+    """
+    Debug-Klasse für PyFundaments.
+    Liest ENV-Variablen und konfiguriert Logging.
+    Gibt Startup-Infos aus, wenn PYFUNDAMENTS_DEBUG=true.
+    """
+
+    def __init__(self):
+        # Debug aktivieren mit ENV VAR (default: False)
+        self.enabled = os.getenv("PYFUNDAMENTS_DEBUG", "false").lower() == "true"
+
+        # Log-Level aus ENV lesen, default INFO
+        log_level_str = os.getenv("LOG_LEVEL", "INFO").upper()
+        self.log_level = getattr(logging, log_level_str, logging.INFO)
+
+        # Logs in /tmp oder stdout? (default False)
+        self.log_to_tmp = os.getenv("LOG_TO_TMP", "false").lower() == "true"
+
+        # Öffentliches Logging an/aus (default True)
+        self.enable_public_logs = os.getenv("ENABLE_PUBLIC_LOGS", "true").lower() == "true"
+
+        # Logger Setup
+        self.logger = logging.getLogger('pyfundaments_debug')
+        self._setup_logger()
+
+    def _setup_logger(self):
+        if not self.enable_public_logs:
+            # Nur kritische Fehler im Log, wenn deaktiviert
+            logging.basicConfig(level=logging.CRITICAL)
+            return
+
+        handlers = []
+        if self.log_to_tmp:
+            log_file = '/tmp/pyfundaments_debug.log'
+            file_handler = RotatingFileHandler(log_file, maxBytes=1024*1024, backupCount=3)
+            handlers.append(file_handler)
+        handlers.append(logging.StreamHandler(sys.stdout))
+
+        logging.basicConfig(
+            level=self.log_level,
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            handlers=handlers
+        )
+
+    def run(self):
+        if not self.enabled:
+            return
+
+        self.logger.info(f"==== PYFUNDAMENTS DEBUG STARTUP ({datetime.datetime.now()}) ====")
+        self.logger.info(f"Python version: {sys.version}")
+        self.logger.info(f"CWD: {os.getcwd()}")
+        self.logger.info(f"sys.path: {sys.path}")
+
+        fund_dir = "fundaments"
+        self.logger.info(f"fundaments exists: {os.path.isdir(fund_dir)}")
+
+        required_files = [
+            "__init__.py",
+            "access_control.py",
+            "postgresql.py",
+            "config_handler.py",
+            "security.py",
+            "user_handler.py",
+            "encryption.py"
+        ]
+
+        for file in required_files:
+            path = os.path.join(fund_dir, file)
+            exists = os.path.isfile(path)
+            readable = os.access(path, os.R_OK)
+            self.logger.info(f"{file} exists: {exists} | readable: {readable}")
+
+        if os.path.isdir(fund_dir):
+            self.logger.info(f"Listing fundaments contents: {os.listdir(fund_dir)}")
+        else:
+            self.logger.warning("fundaments folder not found.")
+
+        spec = importlib.util.find_spec("fundaments")
+        self.logger.info(f"fundaments importable: {spec is not None}")
+
+        conflicts = [mod for mod in sys.modules if mod == "fundaments"]
+        self.logger.info(f"Name conflict in sys.modules: {conflicts}")
+
+        self.logger.info("==== PYFUNDAMENTS DEBUG END ====")

fundaments/encryption.py

@@ -0,0 +1,233 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# encryption.py
+# A secure and robust encryption module using the cryptography library.
+# This module is designed as a core component for a CMS architecture.
+
+import os
+import sys
+import base64
+import binascii
+from typing import Dict, Union, Optional
+
+# IMPORTANT: The cryptography library is required for this module.
+# Please install it with 'pip install cryptography'.
+try:
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+    from cryptography.exceptions import InvalidTag
+except ImportError:
+    print("Error: The 'cryptography' library is required. Please install it with 'pip install cryptography'.")
+    sys.exit(1)
+
+class Encryption:
+    """
+    A class for symmetric encryption and decryption using AES-256-GCM.
+    It securely handles both string data and file streaming.
+    
+    This version is designed as a reusable core component for a larger application.
+    """
+    CIPHER_NAME = 'AES-256-GCM'
+    KEY_LENGTH = 32 # 256 bits
+    NONCE_LENGTH = 12 # 96 bits, standard for GCM
+    TAG_LENGTH = 16 # 128 bits
+    SALT_LENGTH = 16
+
+    @staticmethod
+    def generate_salt() -> str:
+        """
+        Generates a new, cryptographically secure random salt for key derivation.
+        This should be done once during application setup and stored securely.
+        
+        Returns:
+            A hex-encoded string of the salt.
+        """
+        return binascii.hexlify(os.urandom(Encryption.SALT_LENGTH)).decode('utf-8')
+
+    def __init__(self, master_key: str, salt: str):
+        """
+        Initializes the encryption class by deriving a secure key from a master key.
+        The provided master_key and a persistent salt are used for key derivation.
+        
+        Args:
+            master_key: The string to be used as the master key.
+            salt: The hex-encoded string of the persistent salt.
+        
+        Raises:
+            ValueError: If the provided salt is not a valid hex string or has an incorrect length.
+        """
+        try:
+            salt_bytes = binascii.unhexlify(salt)
+        except binascii.Error:
+            raise ValueError("Invalid salt format. Must be a hex-encoded string.")
+        
+        if len(salt_bytes) != self.SALT_LENGTH:
+            raise ValueError(f"Invalid salt length. Expected {self.SALT_LENGTH} bytes, got {len(salt_bytes)}.")
+            
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=self.KEY_LENGTH,
+            salt=salt_bytes,
+            iterations=480000, # Recommended value for 2023+
+            backend=default_backend()
+        )
+        self.key = kdf.derive(master_key.encode('utf-8'))
+
+    def encrypt(self, data: str) -> Dict[str, str]:
+        """
+        Encrypts a string using AES-256-GCM.
+        
+        Args:
+            data: The string to be encrypted.
+
+        Returns:
+            A dictionary containing the base64-encoded ciphertext, hex-encoded IV/nonce,
+            and hex-encoded authentication tag.
+        """
+        nonce = os.urandom(self.NONCE_LENGTH)
+        
+        aesgcm = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce),
+            backend=default_backend()
+        ).encryptor()
+        
+        encrypted_data = aesgcm.update(data.encode('utf-8')) + aesgcm.finalize()
+        tag = aesgcm.tag
+
+        return {
+            'data': base64.b64encode(encrypted_data).decode('utf-8'),
+            'nonce': binascii.hexlify(nonce).decode('utf-8'),
+            'tag': binascii.hexlify(tag).decode('utf-8')
+        }
+
+    def decrypt(self, encrypted_data: str, nonce: str, tag: str) -> str:
+        """
+        Decrypts an AES-256-GCM encrypted string.
+        
+        Args:
+            encrypted_data: The base64-encoded ciphertext.
+            nonce: The hex-encoded nonce/IV.
+            tag: The hex-encoded authentication tag.
+            
+        Returns:
+            The decrypted plaintext string.
+        
+        Raises:
+            ValueError: If nonce, tag, or data format is invalid.
+            InvalidTag: If the authentication tag fails validation.
+        """
+        try:
+            nonce_bytes = binascii.unhexlify(nonce)
+            tag_bytes = binascii.unhexlify(tag)
+            cipher_bytes = base64.b64decode(encrypted_data)
+        except (binascii.Error, ValueError) as e:
+            raise ValueError(f'Invalid data format: {e}')
+        
+        aesgcm = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce_bytes, tag_bytes),
+            backend=default_backend()
+        ).decryptor()
+        
+        try:
+            decrypted_data = aesgcm.update(cipher_bytes) + aesgcm.finalize()
+            return decrypted_data.decode('utf-8')
+        except InvalidTag:
+            raise InvalidTag("Authentication tag validation failed. Data may be corrupted or key is incorrect.")
+
+    def encrypt_file(self, source_path: str, destination_path: str) -> Dict[str, str]:
+        """
+        Encrypts a file using AES-256-GCM with a streaming approach.
+        
+        Args:
+            source_path: Path to the file to be encrypted.
+            destination_path: Path where the encrypted file will be saved.
+            
+        Returns:
+            A dictionary containing the hex-encoded IV/nonce and authentication tag.
+        """
+        nonce = os.urandom(self.NONCE_LENGTH)
+        
+        encryptor = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce),
+            backend=default_backend()
+        ).encryptor()
+        
+        try:
+            with open(source_path, 'rb') as fp_source, open(destination_path, 'wb') as fp_dest:
+                fp_dest.write(nonce)
+                
+                chunk_size = 8192
+                while True:
+                    chunk = fp_source.read(chunk_size)
+                    if not chunk:
+                        break
+                    encrypted_chunk = encryptor.update(chunk)
+                    fp_dest.write(encrypted_chunk)
+                
+                encryptor.finalize()
+                tag = encryptor.tag
+                fp_dest.write(tag)
+            
+            return {
+                'nonce': binascii.hexlify(nonce).decode('utf-8'),
+                'tag': binascii.hexlify(tag).decode('utf-8')
+            }
+        except FileNotFoundError as e:
+            raise ValueError(f"File not found: {e.filename}") from e
+        except Exception as e:
+            raise IOError(f"File encryption failed: {e}") from e
+
+    def decrypt_file(self, source_path: str, destination_path: str) -> None:
+        """
+        Decrypts an AES-256-GCM encrypted file.
+        
+        Args:
+            source_path: Path to the encrypted file.
+            destination_path: Path where the decrypted file will be saved.
+        """
+        try:
+            with open(source_path, 'rb') as fp_source, open(destination_path, 'wb') as fp_dest:
+                nonce = fp_source.read(self.NONCE_LENGTH)
+                if len(nonce) != self.NONCE_LENGTH:
+                    raise ValueError("Incomplete or invalid file format: Nonce is missing.")
+                    
+                fp_source.seek(-self.TAG_LENGTH, os.SEEK_END)
+                tag = fp_source.read(self.TAG_LENGTH)
+                if len(tag) != self.TAG_LENGTH:
+                    raise ValueError("Incomplete or invalid file format: Tag is missing.")
+                    
+                fp_source.seek(self.NONCE_LENGTH, os.SEEK_SET) # Rewind to the start of the ciphertext
+                
+                decryptor = Cipher(
+                    algorithms.AES(self.key),
+                    modes.GCM(nonce, tag),
+                    backend=default_backend()
+                ).decryptor()
+                
+                chunk_size = 8192
+                encrypted_file_size = os.path.getsize(source_path) - self.NONCE_LENGTH - self.TAG_LENGTH
+                
+                bytes_read = 0
+                while bytes_read < encrypted_file_size:
+                    chunk_to_read = min(chunk_size, encrypted_file_size - bytes_read)
+                    chunk = fp_source.read(chunk_to_read)
+                    
+                    decrypted_chunk = decryptor.update(chunk)
+                    fp_dest.write(decrypted_chunk)
+                    bytes_read += len(chunk)
+                
+                decryptor.finalize()
+                
+        except InvalidTag as e:
+            raise IOError(f"File decryption failed. The authentication tag is invalid, suggesting the file was corrupted or tampered with. Error: {e}") from e
+        except FileNotFoundError as e:
+            raise ValueError(f"File not found: {e.filename}") from e
+        except Exception as e:
+            raise IOError(f"File decryption failed due to an unexpected error: {e}") from e

fundaments/postgresql.py

@@ -0,0 +1,179 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/postgresql.py
+import os
+import logging
+import asyncpg
+import ssl
+from urllib.parse import urlparse, urlencode, parse_qs, urlunparse
+from typing import Optional
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+_db_pool: Optional[asyncpg.Pool] = None
+
+def enforce_cloud_security(dsn_url: str) -> str:
+    """
+    Enforces security settings for cloud environments.
+    - Ensures SSL mode is at least 'require'
+    - Removes unsupported options for cloud providers (e.g. statement_timeout for Neon)
+    - Sets connect_timeout and keepalives_idle defaults
+    """
+    parsed = urlparse(dsn_url)
+    query_params = parse_qs(parsed.query)
+
+    # Enforce SSL (at least 'require')
+    sslmode = query_params.get('sslmode', ['prefer'])[0].lower()
+    if sslmode not in ['require', 'verify-ca', 'verify-full']:
+        query_params['sslmode'] = ['require']
+
+    # Set timeouts and keep-alives if not present
+    if 'connect_timeout' not in query_params:
+        query_params['connect_timeout'] = ['5']
+    if 'keepalives_idle' not in query_params:
+        query_params['keepalives_idle'] = ['60']
+
+    # Remove statement_timeout option for Neon
+    if 'neon.tech' in parsed.netloc:
+        if 'options' in query_params:
+            options_clean = []
+            for opt in query_params['options']:
+                if 'statement_timeout' not in opt:
+                    options_clean.append(opt)
+            if options_clean:
+                query_params['options'] = options_clean
+            else:
+                query_params.pop('options')
+            logger.info("Removed unsupported 'statement_timeout' option for Neon.tech.")
+        # Optionally, set a supported option for Neon (usually none)
+    
+    # TODO: Extend here for further providers...
+
+    # Rebuild DSN
+    new_query = urlencode(query_params, doseq=True)
+    new_url = parsed._replace(query=new_query)
+    return urlunparse(new_url)
+
+def mask_dsn(dsn_url: str) -> str:
+    """
+    Masks username/password from DSN so they are not exposed in logs.
+    """
+    parsed = urlparse(dsn_url)
+    safe_netloc = f"{parsed.hostname}:{parsed.port}" if parsed.port else parsed.hostname
+    return parsed._replace(netloc=safe_netloc).geturl()
+
+async def ssl_runtime_check(conn: asyncpg.Connection):
+    """
+    Performs a cloud-aware SSL runtime check on an active connection.
+    For Neon/Supabase (or unknown cloud) only log a warning if pg_stat_ssl is unavailable.
+    """
+    dsn = os.getenv("DATABASE_URL", "")
+    try:
+        ssl_status = await conn.fetchval("""
+            SELECT CASE WHEN ssl THEN 'active' ELSE 'INACTIVE' END
+            FROM pg_stat_ssl WHERE pid = pg_backend_pid()
+        """)
+        if ssl_status != 'active':
+            logger.critical("CRITICAL ERROR: SSL connection is not active!")
+            raise RuntimeError("SSL connection failed")
+        logger.info("SSL connection is active.")
+    except Exception as e:
+        # Cloud: If pg_stat_ssl is not available, don't fail hard.
+        if "neon.tech" in dsn or "supabase" in dsn:
+            logger.warning("SSL check via pg_stat_ssl not possible (cloud restriction). Assuming SSL is active due to sslmode=require.")
+        else:
+            logger.critical(f"SSL runtime check failed: {e}")
+            raise
+
+async def init_db_pool(dsn_url: Optional[str] = None) -> Optional[asyncpg.Pool]:
+    """Initializes the asynchronous database connection pool."""
+    global _db_pool
+    if _db_pool:
+        return _db_pool
+
+    if not dsn_url:
+        dsn_url = os.getenv("DATABASE_URL") or os.getenv("PG_DSN")
+        if not dsn_url:
+            logger.warning("No DATABASE_URL or PG_DSN found. Skipping DB pool initialization.")
+            return None
+
+    # Enforce cloud security and remove unsupported options
+    secured_dsn = enforce_cloud_security(dsn_url)
+
+    # ⚠ WARNING: This logs full credentials — keep only for secure DEV debugging
+    logger.debug(f"[DEV ONLY] Full DSN used for DB connection: {secured_dsn}")
+
+    # Always log a masked DSN for production safety
+    logger.info(f"DSN used for DB connection (masked): {mask_dsn(secured_dsn)}")
+
+    ssl_context = None
+    if 'sslmode=verify-full' in secured_dsn:
+        ssl_context = ssl.create_default_context()
+
+    try:
+        logger.info("Initializing secure database pool...")
+        _db_pool = await asyncpg.create_pool(
+            dsn=secured_dsn,
+            min_size=1,
+            max_size=10,
+            timeout=5,
+            command_timeout=30,
+            ssl=ssl_context
+        )
+        # Post-init checks
+        async with _db_pool.acquire() as conn:
+            await ssl_runtime_check(conn)
+        logger.info("Secure database pool initialized.")
+        return _db_pool
+    except Exception as e:
+        logger.critical(f"Pool initialization failed: {str(e)}")
+        _db_pool = None
+        return None  # Fallback: allow app to run without DB
+
+async def close_db_pool():
+    """Gracefully closes the database connection pool."""
+    global _db_pool
+    if _db_pool:
+        await _db_pool.close()
+        _db_pool = None
+        logger.info("Database pool closed successfully.")
+
+async def execute_secured_query(query: str, *params, fetch_method='fetch'):
+    """
+    Executes a parameterized query with integrated security checks.
+    """
+    global _db_pool
+    if not _db_pool:
+        raise RuntimeError("Database pool not initialized")
+
+    try:
+        async with _db_pool.acquire() as conn:
+            if fetch_method == 'fetch':
+                return await conn.fetch(query, *params)
+            elif fetch_method == 'fetchrow':
+                return await conn.fetchrow(query, *params)
+            elif fetch_method == 'execute':
+                return await conn.execute(query, *params)
+            else:
+                raise ValueError("Invalid fetch_method")
+    except asyncpg.PostgresError as e:
+        error_type = "Security violation" if getattr(e, 'sqlstate', None) == '42501' else "Database error"
+        
+        if os.getenv('APP_ENV') == 'production':
+            logger.error(f"{error_type} [Code: {getattr(e, 'sqlstate', '?')}]")
+        else:
+            logger.error(f"{error_type}: {e}")
+        
+        # Neon: Reconnect if connection terminated (optional)
+        if getattr(e, 'sqlstate', None) == '08006' and 'neon.tech' in (os.getenv("DATABASE_URL") or ''):
+            logger.warning("Neon.tech connection terminated. Restarting pool...")
+            await close_db_pool()
+            await init_db_pool(os.getenv("DATABASE_URL"))
+        
+        raise

fundaments/security.py

@@ -0,0 +1,82 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# fundaments/security.py
+# A central security manager that orchestrates core security functions.
+# This class acts as a single, trusted interface for the application to
+# interact with all underlying security fundamentals.
+
+import logging
+from typing import Dict, Any, Optional
+
+# VORHER: Diese direkten Imports sind überflüssig,
+# da die Instanzen der Klassen über den 'services'-Dictionary
+# im __init__-Konstruktor übergeben werden.
+# Sie sind auch nicht für die Typisierung notwendig,
+# da wir 'Optional[ClassName]' verwenden, was ausreicht.
+# from fundaments.encryption import Encryption
+# from fundaments.access_control import AccessControl
+# from fundaments.postgresql import execute_secured_query
+# from fundaments.user_handler import UserHandler
+
+logger = logging.getLogger('security')
+
+class Security:
+    def __init__(self, services: Dict[str, Any]):
+        # VORHER: Hier werden die Instanzen aus dem übergebenen Dictionary entnommen.
+        self.user_handler: Optional[UserHandler] = services.get("user_handler")
+        self.access_control: Optional[AccessControl] = services.get("access_control")
+        self.encryption: Optional[Encryption] = services.get("encryption")
+
+        # VORHER: Bei fehlenden kritischen Diensten wird die Anwendung sofort gestoppt.
+        # Dies ist eine strikte, aber unflexible Regel.
+        if not self.user_handler:
+            logger.critical("Security manager init failed: UserHandler service missing.")
+            raise RuntimeError("UserHandler service missing")
+
+        if not self.access_control:
+            logger.critical("Security manager init failed: AccessControl service missing.")
+            raise RuntimeError("AccessControl service missing")
+
+        # VORHER: Bei einem nicht-kritischen Dienst wird nur eine Warnung ausgegeben.
+        # Die Anwendung läuft weiter.
+        if not self.encryption:
+            logger.warning("Encryption service not available. Encryption/decryption features will be disabled.")
+
+        logger.info("Security manager initialized and ready.")
+
+    # VORHER: Hier fehlt die Überprüfung, ob 'self.user_handler' None ist.
+    # Wenn der Dienst nicht initialisiert wurde (wie oben), würde dies einen AttributeError auslösen.
+    async def user_login(self, username: str, password: str, request_data: dict) -> bool:
+        logger.info(f"Attempting login for user: {username}")
+        # UserHandler.login() is synchronous (SQLite) — no await.
+        # The old 'await' raised TypeError: bool can't be awaited.
+        if self.user_handler.login(username, password, request_data):
+            return self.user_handler.validate_session(request_data)
+        return False
+
+    # VORHER: Hier fehlt die Überprüfung, ob 'self.access_control' None ist.
+    async def check_permission(self, user_id: int, permission_name: str) -> bool:
+        """Checks permission for ANY user_id (not just the constructor one)."""
+        logger.debug(f"Checking permission '{permission_name}' for user ID {user_id}")
+        return await self.access_control.has_permission(permission_name, user_id=user_id)
+
+    # VORHER: Hier wird geprüft, ob 'self.encryption' None ist, was korrekt ist.
+    def encrypt_data(self, data: str) -> Dict[str, str]:
+        if not self.encryption:
+            raise RuntimeError("Encryption service not initialized.")
+        logger.debug("Encrypting data.")
+        return self.encryption.encrypt(data)
+
+    # VORHER: Hier wird geprüft, ob 'self.encryption' None ist, was korrekt ist.
+    def decrypt_data(self, encrypted_data: str, nonce: str, tag: str) -> Optional[str]:
+        if not self.encryption:
+            logger.error("Encryption service not initialized. Cannot decrypt data.")
+            return None
+        logger.debug("Decrypting data.")
+        try:
+            return self.encryption.decrypt(encrypted_data, nonce, tag)
+        except Exception as e:
+            logger.error(f"Decryption failed: {e}")
+            return None

fundaments/user_handler.py

@@ -0,0 +1,370 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# root/fundaments/user_handler.py
+# A Python module for handling user authentication and session management.
+
+import sqlite3
+import uuid
+from datetime import datetime, timedelta
+from passlib.hash import pbkdf2_sha256
+import os
+
+
+class Database:
+    """
+    Handles the SQLite database connection and initialization.
+    Supports dynamic path selection via environment variables with a 
+    fallback to the local application directory.
+    """
+    def __init__(self, db_name="cms_database.db"):
+        # 1. Attempt to load the database path from an environment variable
+        # This allows for flexible configuration in production/Docker environments
+        env_path = os.getenv("SQLITE_PATH")
+        
+        if env_path:
+            # Use the absolute path provided by the environment variable
+            full_db_path = os.path.abspath(env_path)
+        else:
+            # Fallback logic: Locate the 'app' directory relative to this script
+            # Expected structure: root/fun/user_handler.py -> root/app/
+            base_path = os.path.dirname(os.path.abspath(__file__))
+            app_dir = os.path.join(base_path, "..", "app")
+            full_db_path = os.path.join(app_dir, db_name)
+
+        # 2. Ensure the target directory exists before attempting to connect
+        # SQLite can create the file, but not the parent folders.
+        db_dir = os.path.dirname(full_db_path)
+        if db_dir and not os.path.exists(db_dir):
+            os.makedirs(db_dir)
+            
+        # Initialize the connection and cursor
+        self.conn = sqlite3.connect(full_db_path)
+        self.cursor = self.conn.cursor()
+        
+        # Log the active database path for debugging purposes
+        print(f"Database connected to: {full_db_path}")
+
+    def execute(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        self.conn.commit()
+
+    def fetchone(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        return self.cursor.fetchone()
+
+    def fetchall(self, query, params=None):
+        if params is None:
+            params = []
+        self.cursor.execute(query, params)
+        return self.cursor.fetchall()
+
+    def close(self):
+        self.conn.close()
+
+    def setup_tables(self):
+        """
+        Creates the necessary tables for users and sessions.
+        """
+        self.execute("""
+            CREATE TABLE IF NOT EXISTS users (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                username TEXT UNIQUE NOT NULL,
+                password TEXT NOT NULL,
+                is_admin INTEGER NOT NULL DEFAULT 0,
+                account_locked INTEGER NOT NULL DEFAULT 0,
+                failed_login_attempts INTEGER NOT NULL DEFAULT 0
+            )
+        """)
+        self.execute("""
+            CREATE TABLE IF NOT EXISTS sessions (
+                id TEXT PRIMARY KEY,
+                user_id INTEGER NOT NULL,
+                ip_address TEXT,
+                user_agent TEXT,
+                last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+            )
+        """)
+
+class Security:
+    """
+    Handles secure password hashing and session regeneration.
+    Using passlib for robust and secure password management.
+    """
+    @staticmethod
+    def hash_password(password: str) -> str:
+        """Hashes a password using PBKDF2 with SHA256."""
+        return pbkdf2_sha256.hash(password)
+
+    @staticmethod
+    def verify_password(password: str, hashed_password: str) -> bool:
+        """Verifies a password against a stored hash."""
+        return pbkdf2_sha256.verify(password, hashed_password)
+
+    @staticmethod
+    def regenerate_session(session_id: str):
+        """
+        Simulates regenerating a session ID to prevent session fixation.
+        In a real web framework, this would be a framework-specific function.
+        """
+        print(f"Session regenerated. Old ID: {session_id}")
+        new_session_id = str(uuid.uuid4())
+        print(f"New ID: {new_session_id}")
+        return new_session_id
+
+class UserHandler:
+    """
+    Handles user login, logout, and session validation.
+    This class mirrors the logic from the user's PHP User class.
+    """
+    def __init__(self, db: Database):
+        self.db = db
+        # A simple in-memory session store for this example
+        self._session = {}
+
+    def login(self, username: str, password: str, request_data: dict) -> bool:
+        """
+        Logs in the user by verifying credentials and storing a new session.
+        :param username: The user's username.
+        :param password: The user's plain-text password.
+        :param request_data: A dictionary containing 'ip_address' and 'user_agent'.
+        :return: True if login is successful, False otherwise.
+        """
+        try:
+            # Step 1: Find the user in the database
+            user_data = self.db.fetchone("SELECT id, username, password, is_admin, account_locked, failed_login_attempts FROM users WHERE username = ?", (username,))
+            if user_data is None:
+                print(f"Login failed: Username '{username}' not found.")
+                return False
+
+            user = {
+                'id': user_data[0],
+                'username': user_data[1],
+                'password': user_data[2],
+                'is_admin': user_data[3],
+                'account_locked': user_data[4],
+                'failed_login_attempts': user_data[5]
+            }
+
+            # Check if account is locked
+            if user['account_locked'] == 1:
+                print(f"Login failed: Account for '{username}' is locked.")
+                return False
+
+            # Step 2: Verify the password
+            if Security.verify_password(password, user['password']):
+                print(f"Login successful for user: '{username}'")
+                
+                # Reset failed login attempts on success
+                self.reset_failed_attempts(username)
+
+                # Step 3: Create a new session record in the database
+                session_id = str(uuid.uuid4())
+                ip_address = request_data.get('ip_address', 'unknown')
+                user_agent = request_data.get('user_agent', 'unknown')
+
+                self.db.execute(
+                    "INSERT INTO sessions (id, user_id, ip_address, user_agent) VALUES (?, ?, ?, ?)",
+                    (session_id, user['id'], ip_address, user_agent)
+                )
+
+                # Step 4: Store session data in the in-memory session (or a session store)
+                self._session = {
+                    'session_id': session_id,
+                    'user_id': user['id'],
+                    'username': user['username'],
+                    'is_admin': user['is_admin']
+                }
+
+                # Security: Regenerate session ID
+                self._session['session_id'] = Security.regenerate_session(session_id)
+                return True
+            else:
+                print(f"Login failed: Incorrect password for user '{username}'.")
+                # Increment failed login attempts
+                self.increment_failed_attempts(username)
+                return False
+
+        except sqlite3.Error as e:
+            print(f"Database error during login: {e}")
+            return False
+
+    def logout(self) -> bool:
+        """
+        Logs out the current user by deleting the session from the database.
+        :return: True if logout is successful, False otherwise.
+        """
+        if 'user_id' not in self._session:
+            print("No active session to log out.")
+            return False
+
+        try:
+            # Step 1: Delete the session from the database
+            self.db.execute("DELETE FROM sessions WHERE user_id = ?", (self._session['user_id'],))
+            
+            # Step 2: Clear the in-memory session data
+            self._session.clear()
+            print("User logged out successfully.")
+            return True
+        except sqlite3.Error as e:
+            print(f"Database error during logout: {e}")
+            return False
+
+    def is_logged_in(self) -> bool:
+        """
+        Checks if the current user is logged in.
+        :return: True if a valid session exists, False otherwise.
+        """
+        if 'user_id' not in self._session:
+            return False
+
+        try:
+            # Check for the session in the database
+            session_data = self.db.fetchone(
+                "SELECT * FROM sessions WHERE id = ? AND user_id = ?",
+                (self._session['session_id'], self._session['user_id'])
+            )
+            return session_data is not None
+        except sqlite3.Error as e:
+            print(f"Database error during is_logged_in check: {e}")
+            return False
+
+    def is_admin(self) -> bool:
+        """
+        Checks if the logged-in user is an admin.
+        :return: True if the user is an admin, False otherwise.
+        """
+        return self._session.get('is_admin', 0) == 1
+
+    def validate_session(self, request_data: dict) -> bool:
+        """
+        Validates the current session against IP address and user agent.
+        :param request_data: A dictionary containing 'ip_address' and 'user_agent'.
+        :return: True if the session is valid, False otherwise.
+        """
+        if not self.is_logged_in():
+            return False
+
+        try:
+            ip_address = request_data.get('ip_address', 'unknown')
+            user_agent = request_data.get('user_agent', 'unknown')
+
+            session_data = self.db.fetchone(
+                "SELECT * FROM sessions WHERE id = ? AND user_id = ? AND ip_address = ? AND user_agent = ?",
+                (self._session['session_id'], self._session['user_id'], ip_address, user_agent)
+            )
+            return session_data is not None
+        except sqlite3.Error as e:
+            print(f"Database error during session validation: {e}")
+            return False
+
+    def lock_account(self, username: str):
+        """
+        Locks a user account.
+        :param username: The username of the account to lock.
+        """
+        try:
+            self.db.execute("UPDATE users SET account_locked = 1 WHERE username = ?", (username,))
+            print(f"Account for '{username}' has been locked.")
+        except sqlite3.Error as e:
+            print(f"Database error while locking account: {e}")
+
+    def reset_failed_attempts(self, username: str):
+        """
+        Resets failed login attempts for a user.
+        :param username: The username of the account.
+        """
+        try:
+            self.db.execute("UPDATE users SET failed_login_attempts = 0 WHERE username = ?", (username,))
+        except sqlite3.Error as e:
+            print(f"Database error while resetting failed attempts: {e}")
+
+    def increment_failed_attempts(self, username: str):
+        """
+        Increments failed login attempts and locks the account if a threshold is met.
+        :param username: The username of the account.
+        """
+        try:
+            # Get the current failed attempts
+            user_data = self.db.fetchone("SELECT failed_login_attempts FROM users WHERE username = ?", (username,))
+            if user_data:
+                attempts = user_data[0] + 1
+                self.db.execute(
+                    "UPDATE users SET failed_login_attempts = ? WHERE username = ?",
+                    (attempts, username)
+                )
+                print(f"Failed login attempts for '{username}': {attempts}")
+                
+                # Check for threshold (e.g., 5 attempts)
+                if attempts >= 5:
+                    self.lock_account(username)
+
+        except sqlite3.Error as e:
+            print(f"Database error while incrementing failed attempts: {e}")
+
+# --- Example Usage ---
+if __name__ == "__main__":
+    db = Database()
+    db.setup_tables()
+    user_handler = UserHandler(db)
+
+    # Clean up old test data if it exists
+    db.execute("DELETE FROM users WHERE username IN (?, ?)", ("testuser", "adminuser"))
+    db.execute("DELETE FROM sessions")
+
+    # 1. Register a new user and an admin user
+    hashed_password = Security.hash_password("secure_password_123")
+    db.execute("INSERT INTO users (username, password) VALUES (?, ?)", ("testuser", hashed_password))
+    db.execute("INSERT INTO users (username, password, is_admin) VALUES (?, ?, 1)", ("adminuser", hashed_password))
+
+    print("--- Test 1: Successful Login ---")
+    # Simulate a web request
+    request_data = {
+        'ip_address': '192.168.1.100',
+        'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+    }
+    
+    login_success = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status: {login_success}")
+    print(f"Is user logged in? {user_handler.is_logged_in()}")
+    print(f"Is user an admin? {user_handler.is_admin()}")
+    print(f"Is session valid? {user_handler.validate_session(request_data)}")
+    print("-" * 20)
+    
+    # 2. Simulate a logout
+    print("--- Test 2: Logout ---")
+    user_handler.logout()
+    print(f"Is user logged in after logout? {user_handler.is_logged_in()}")
+    print("-" * 20)
+
+    # 3. Simulate a failed login and account lock
+    print("--- Test 3: Failed Login and Account Lock ---")
+    # Log in with the wrong password multiple times
+    for i in range(6):
+        user_handler.login("testuser", "wrong_password", request_data)
+    
+    # Now, try to log in with the correct password. It should fail because the account is locked.
+    print("\nAttempting to log in with correct password after lock:")
+    login_attempt_after_lock = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status: {login_attempt_after_lock}")
+    print("-" * 20)
+    
+    # 4. Reset failed attempts for a new login
+    print("--- Test 4: Resetting failed attempts ---")
+    user_handler.reset_failed_attempts("testuser")
+    login_attempt_after_reset = user_handler.login("testuser", "secure_password_123", request_data)
+    print(f"Login attempt status after reset: {login_attempt_after_reset}")
+    
+    db.close()
+    
+    # Optional: Clean up the database file after the run
+    # OLD
+    # os.remove("cms_database.db")
+    # NEW : Clean up the database file after the run:
+    # os.remove(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "app", "cms_database.db"))

main.py

@@ -0,0 +1,202 @@
+# PyFundaments: A Secure Python Architecture
+# Copyright 2008-2025 - Volkan Kücükbudak
+# Apache License V. 2
+# Repo: https://github.com/VolkanSah/PyFundaments
+# main.py
+# This is the main entry point of the application.
+# It now handles asynchronous initialization of the fundament modules.
+import sys
+import logging
+import asyncio
+import os
+from typing import Dict, Any, Optional
+
+import importlib.util
+import datetime
+
+if 'fundaments' in sys.modules:
+    del sys.modules['fundaments']
+
+# We import our core modules from the "fundaments" directory.
+try:
+    from fundaments.config_handler import config_service
+    from fundaments.postgresql import init_db_pool, close_db_pool
+    from fundaments.encryption import Encryption
+    from fundaments.access_control import AccessControl
+    from fundaments.user_handler import UserHandler
+    from fundaments.security import Security
+    from fundaments.debug import PyFundamentsDebug
+except ImportError as e:
+    print(f"Error: Failed to import a fundament module: {e}")
+    print("Please ensure the modules and dependencies are present.")
+    sys.exit(1)
+# Debug run    
+debug = PyFundamentsDebug()
+debug.run()
+
+# Logger configuration - conditional based on ENV
+log_level = os.getenv('LOG_LEVEL', 'INFO').upper()
+log_to_tmp = os.getenv('LOG_TO_TMP', 'false').lower() == 'true'
+enable_public_logs = os.getenv('ENABLE_PUBLIC_LOGS', 'true').lower() == 'true'
+
+if enable_public_logs:
+    if log_to_tmp:
+        log_file = '/tmp/pyfundaments.log'
+        logging.basicConfig(
+            level=getattr(logging, log_level),
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            handlers=[
+                logging.FileHandler(log_file),
+                logging.StreamHandler()
+            ]
+        )
+    else:
+        logging.basicConfig(
+            level=getattr(logging, log_level),
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+else:
+    # Silent mode - only critical errors
+    logging.basicConfig(level=logging.CRITICAL)
+
+logger = logging.getLogger('main_app_loader')
+
+async def initialize_fundaments() -> Dict[str, Any]:
+    """
+    Initializes core application services conditionally based on available ENV variables.
+    Only loads services for which the required configuration is present.
+    """
+    logger.info("Starting conditional initialization of fundament modules...")
+    
+    fundaments = {
+        "config": config_service
+    }
+    
+    # --- Database Initialization (PostgreSQL) ---
+    # Only initialize if DATABASE_URL is available
+    database_url = config_service.get("DATABASE_URL")
+    if database_url and database_url != "your_database_dsn_here":
+        try:
+            db_service = await init_db_pool(database_url)
+            if db_service is not None:
+                fundaments["db"] = db_service
+                logger.info("Database service initialized.")
+            else:
+                # init_db_pool() returns None instead of raising on failure
+                logger.warning("Database pool could not be built, continuing without DB.")
+                fundaments["db"] = None
+        except Exception as e:
+            logger.warning(f"Database initialization failed, continuing without DB: {e}")
+            fundaments["db"] = None
+    else:
+        logger.info("No valid DATABASE_URL found, skipping database initialization.")
+        fundaments["db"] = None
+
+    # --- Encryption Initialization ---
+    # Only initialize if both encryption keys are available
+    master_key = config_service.get("MASTER_ENCRYPTION_KEY")
+    persistent_salt = config_service.get("PERSISTENT_ENCRYPTION_SALT")
+    
+    if master_key and persistent_salt and master_key != "your_256_bit_key_here":
+        try:
+            encryption_service = Encryption(master_key=master_key, salt=persistent_salt)
+            fundaments["encryption"] = encryption_service
+            logger.info("Encryption service initialized.")
+        except Exception as e:
+            logger.warning(f"Encryption initialization failed, continuing without encryption: {e}")
+            fundaments["encryption"] = None
+    else:
+        logger.info("Encryption keys not found or using defaults, skipping encryption initialization.")
+        fundaments["encryption"] = None
+
+    # --- Access Control Initialization ---
+    # Only initialize if we have a database connection
+    if fundaments["db"] is not None:
+        try:
+            access_control_service = AccessControl()
+            fundaments["access_control"] = access_control_service
+            logger.info("Access Control service initialized.")
+        except Exception as e:
+            logger.warning(f"Access Control initialization failed: {e}")
+            fundaments["access_control"] = None
+    else:
+        logger.info("No database available, skipping Access Control initialization.")
+        fundaments["access_control"] = None
+
+    # --- User Handler Initialization ---
+    # UserHandler is SQLite-based (own Database class, see user_handler.py)
+    # and does NOT use the asyncpg pool — wiring it with the Postgres pool
+    # was a bug (pool has no fetchone/execute-sync interface).
+    # SQLite path: SQLITE_PATH env or fallback next to app/ (HF Spaces: read-only FS
+    # may fail — caught below, app continues without user_handler).
+    try:
+        from fundaments.user_handler import Database as UserDB
+        user_db = UserDB()
+        user_db.setup_tables()
+        user_handler_service = UserHandler(user_db)
+        fundaments["user_handler"] = user_handler_service
+        logger.info("User Handler service initialized (SQLite store).")
+    except Exception as e:
+        logger.warning(f"User Handler initialization failed: {e}")
+        fundaments["user_handler"] = None
+
+    # --- Security Manager Initialization ---
+    # Only initialize if we have the required sub-services
+    available_services = {k: v for k, v in fundaments.items() if v is not None and k != "config"}
+    
+    if len(available_services) >= 1:  # At least one service beyond config
+        try:
+            # Filter out None services for Security manager
+            fundament_services = {
+                k: v for k, v in {
+                    "user_handler": fundaments.get("user_handler"),
+                    "access_control": fundaments.get("access_control"),
+                    "encryption": fundaments.get("encryption")
+                }.items() if v is not None
+            }
+            
+            if fundament_services:  # Only if we have actual services
+                security_service = Security(fundament_services)
+                fundaments["security"] = security_service
+                logger.info("Security manager initialized.")
+            else:
+                logger.info("No services available for Security manager, skipping initialization.")
+                fundaments["security"] = None
+        except Exception as e:
+            logger.warning(f"Security manager initialization failed: {e}")
+            fundaments["security"] = None
+    else:
+        logger.info("Insufficient services for Security manager, skipping initialization.")
+        fundaments["security"] = None
+    
+    # Log what was actually initialized
+    initialized_services = [k for k, v in fundaments.items() if v is not None]
+    logger.info(f"Successfully initialized services: {', '.join(initialized_services)}")
+    
+    return fundaments
+
+async def main():
+    """
+    The main asynchronous function of the application.
+    """
+    logger.info("Starting main.py...")
+    
+    fundaments = await initialize_fundaments()
+    
+    try:
+        # Load the actual app logic here.
+        # This is where your 'app/app.py' would be imported and run.
+        logger.info("Fundament modules are ready for the app logic.")
+        # Example:
+        from app.app import start_application
+        await start_application(fundaments)
+    
+    finally:
+        # Ensure the database pool is closed gracefully on exit (if it was initialized)
+        if fundaments.get("db") is not None:
+            await close_db_pool()
+            logger.info("Database pool closed.")
+        logger.info("Application shut down.")
+
+if __name__ == "__main__":
+    asyncio.run(main())

requirements.txt

@@ -0,0 +1,34 @@
+# PyFundaments Core Dependencies (always needed)
+asyncpg
+python-dotenv
+passlib
+cryptography
+
+# MCP Hub Dependencies (needed for app/mcp.py)
+# Code imports mcp.server.fastmcp — the mcp SDK, NOT the fastmcp package.
+mcp>=1.10,<2
+httpx
+quart
+hypercorn
+
+# Internal SQLite IPC (needed for app/db_sync.py)
+aiosqlite    
+
+# HTTP client operations (API calls, webhooks)
+requests
+
+# Additional dependencies for specific app types:
+# Uncomment what your application needs
+
+# File operations (ML, data processing, file uploads)
+#aiofiles
+
+# Web applications (Flask-based apps, APIs)
+#Flask[async]
+
+# Discord bots
+#discord.py
+#PyNaCl
+
+# Alternative PostgreSQL driver (if not using asyncpg)
+#psycopg2-binary