commamatrix 0.1.0__tar.gz

commamatrix-0.1.0/.gitignore

@@ -0,0 +1,172 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+
+# 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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# 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
+.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/
+
+/uv.lock
+/opencode.json
+/.commamatrix/*.db
+/.commamatrix/*.sqlite
+/.commamatrix/files/
+/.commamatrix/mcp.json
+/.codex/
+/.commamatrix/

commamatrix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matrixd0t
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commamatrix-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: commamatrix
+Version: 0.1.0
+Summary: AI Agent Orchestration Framework
+Project-URL: Homepage, https://github.com/matrixd0t/commamatrix
+Project-URL: Repository, https://github.com/matrixd0t/commamatrix
+Project-URL: Issues, https://github.com/matrixd0t/commamatrix/issues
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: httpx2<3,>=2.9.1
+Requires-Dist: matrix-fn-schema>=0.1.9
+Requires-Dist: pydantic
+Provides-Extra: all
+Requires-Dist: aiosqlite; extra == 'all'
+Requires-Dist: asyncpg; extra == 'all'
+Requires-Dist: bcrypt; extra == 'all'
+Requires-Dist: bm25s; extra == 'all'
+Requires-Dist: ddgs>=9.14.4; extra == 'all'
+Requires-Dist: matrix-planner>=0.2.1; extra == 'all'
+Requires-Dist: mcp>=2.0.0; extra == 'all'
+Requires-Dist: pyjwt; extra == 'all'
+Requires-Dist: python-dotenv; extra == 'all'
+Requires-Dist: python-multipart; extra == 'all'
+Requires-Dist: sse-starlette<4,>=3.3; extra == 'all'
+Requires-Dist: starlette; extra == 'all'
+Requires-Dist: trafilatura>=2.1.0; extra == 'all'
+Requires-Dist: uvicorn; extra == 'all'
+Provides-Extra: codeact
+Requires-Dist: bm25s; extra == 'codeact'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv; extra == 'dotenv'
+Provides-Extra: http
+Requires-Dist: bcrypt; extra == 'http'
+Requires-Dist: pyjwt; extra == 'http'
+Requires-Dist: python-multipart; extra == 'http'
+Requires-Dist: sse-starlette<4,>=3.3; extra == 'http'
+Requires-Dist: starlette; extra == 'http'
+Requires-Dist: uvicorn; extra == 'http'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0.0; extra == 'mcp'
+Provides-Extra: planner
+Requires-Dist: matrix-planner>=0.2.1; extra == 'planner'
+Provides-Extra: postgres
+Requires-Dist: asyncpg; extra == 'postgres'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite; extra == 'sqlite'
+Provides-Extra: test
+Requires-Dist: aiosqlite; extra == 'test'
+Requires-Dist: bcrypt; extra == 'test'
+Requires-Dist: bm25s; extra == 'test'
+Requires-Dist: ddgs>=9.14.4; extra == 'test'
+Requires-Dist: matrix-planner>=0.2.1; extra == 'test'
+Requires-Dist: pyjwt; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: python-dotenv; extra == 'test'
+Requires-Dist: python-multipart; extra == 'test'
+Requires-Dist: sse-starlette<4,>=3.3; extra == 'test'
+Requires-Dist: starlette; extra == 'test'
+Requires-Dist: trafilatura>=2.1.0; extra == 'test'
+Requires-Dist: uvicorn; extra == 'test'
+Provides-Extra: web
+Requires-Dist: ddgs>=9.14.4; extra == 'web'
+Requires-Dist: trafilatura>=2.1.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+<img src="logo.svg" alt="CommaMatrix logo" width="256">
+
+# CommaMatrix
+
+CommaMatrix is an async-native Python framework for building conversational
+agents. It separates transport connectors, LLM adapters, persistence, tools,
+hooks, instructions, and agent-owned services into explicit extensions that
+can be composed per agent.
+
+The package targets Python 3.13 and later.
+
+## Features
+
+- Async agent lifecycle with transactional startup, refresh, and shutdown.
+- HTTP connector with a web UI, authentication, streaming, and file uploads.
+- OpenAI-compatible, OpenAI Responses, and Anthropic Messages HTTP protocols.
+- Persistent conversation history with SQLite, PostgreSQL, or a custom storage.
+- Discoverable tools, hooks, instructions, services, tables, and connectors.
+- Optional web search, CodeAct execution, planner, subagents, and MCP support.
+- Per-agent extension scopes instead of a process-wide plugin registry.
+
+## Installation
+
+The commands below use [uv](https://docs.astral.sh/uv/), which manages the
+virtual environment, dependencies, and command execution. Install uv first if
+it is not available on your system.
+
+Create a virtual environment with Python 3.13 or newer:
+
+```bash
+uv venv --python 3.13
+```
+
+### Recommended installation
+
+Install the complete built-in integration set. This is the recommended
+installation for trying CommaMatrix or building a first agent:
+
+```bash
+uv pip install "commamatrix[all]"
+```
+
+The `[all]` extra installs optional dependencies. It does not automatically
+enable every integration in every agent. Extensions are still activated
+explicitly in application code, which keeps each agent's runtime scope
+predictable.
+
+### Feature-specific installation
+
+The core package can be installed without optional integrations:
+
+```bash
+uv add commamatrix
+```
+
+Core runtime dependencies are `pydantic`, `httpx2>=2.9.1,<3`, and
+`matrix-fn-schema>=0.1.9`. Optional integrations are kept in extras so an
+application can choose its dependency footprint.
+
+Install only the extras used by an application when the complete set is not
+needed:
+
+| Extra | Provides |
+| --- | --- |
+| `dotenv` | Loading configuration from `.env` files |
+| `sqlite` | Built-in async SQLite storage |
+| `http` | HTTP connector, web UI, authentication, and ASGI server |
+| `web` | Web search and page extraction tools |
+| `codeact` | CodeAct execution support |
+| `planner` | Scheduled tasks and planner integration |
+| `postgres` | PostgreSQL storage support |
+| `mcp` | Model Context Protocol client support |
+| `all` | All built-in integration dependencies |
+| `test` | Test runner plus most integration dependencies |
+
+The declared dependency groups are:
+
+| Group | Packages |
+| --- | --- |
+| Core | `pydantic`, `httpx2>=2.9.1,<3`, `matrix-fn-schema>=0.1.9` |
+| `dotenv` | `python-dotenv` |
+| `sqlite` | `aiosqlite` |
+| `http` | `sse-starlette>=3.3,<4`, `starlette`, `uvicorn`, `bcrypt`, `PyJWT`, `python-multipart` |
+| `web` | `ddgs>=9.14.4`, `trafilatura>=2.1.0` |
+| `codeact` | `bm25s` |
+| `planner` | `matrix-planner>=0.2.1` |
+| `postgres` | `asyncpg` |
+| `mcp` | `mcp>=2.0.0` |
+
+For example:
+
+```bash
+uv pip install "commamatrix[http,sqlite]"
+```
+
+## Quickstart
+
+The following example starts an authenticated HTTP agent backed by an
+OpenAI-compatible API. The same adapter can be configured for other supported
+providers by changing `LLM_API_BASE`, `LLM_API_PROTOCOL`, and the API key
+field.
+
+Set the provider configuration in the environment. CommaMatrix also loads a
+`.env` file when `python-dotenv` is installed:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LLM_API_BASE="https://api.openai.com"
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:OPENAI_API_KEY = "your-api-key"
+$env:LLM_API_BASE = "https://api.openai.com"
+```
+
+Create `quickstart.py`:
+
+```python
+import asyncio
+import os
+
+from commamatrix import *
+
+
+async def main() -> None:
+    agent = Agent(name="my_lovely_assistant")
+    await agent.add_extensions(presets.minimal)
+
+    # See every ConfigField declared by the two active extensions.
+    print(agent.config_fields_info())
+
+    agent.config.set(agentic_model, "deepseek-v4-flash")
+    agent.config.set(api_base, os.environ["LLM_API_BASE"])
+    agent.config.set(openai_api_key, os.environ["OPENAI_API_KEY"])
+
+    # __aenter__ starts the agent; __aexit__ stops it reliably on exit.
+    async with agent:
+        print(f"CommaMatrix is running at {agent.http_server.base_url}")
+        await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`async with agent` starts the agent and always stops it when the block exits,
+including cancellation from `Ctrl+C`. If the application has no work to do
+between startup and shutdown, the same lifecycle can be shortened to:
+
+```python
+await agent.run_forever()
+```
+
+Start it with uv:
+
+```bash
+uv run quickstart.py
+```
+
+Open `http://127.0.0.1:8338/commamatrix` in a browser. On the first start, the HTTP connector creates an administrator account and prints its generated password once. Save that password. The default SQLite database and uploaded files are stored at `.commamatrix/`.
+
+The health endpoint does not require authentication:
+
+```bash
+curl http://127.0.0.1:8338/commamatrix/health
+```
+
+For a non-interactive request, log in first and use the returned bearer token:
+
+```bash
+curl -X POST http://127.0.0.1:8338/commamatrix/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"YOUR_ADMIN_PASSWORD"}'
+```
+
+Then send a message with the token returned as `access_token`:
+
+```bash
+curl -X POST http://127.0.0.1:8338/commamatrix/api/messages \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Explain what CommaMatrix does in one sentence."}'
+```
+
+The response contains the new dialog items, including the assistant output. For streaming, add `?stream=1` to the messages endpoint and consume events from `/commamatrix/api/events`.
+
+`agent.config_fields_markdown()` returns Markdown sections for the currently active extension modules. Each field is rendered as `## name: type (default: value)`, followed by its declaring module and description; the parenthesized default is omitted when no default is declared. Defaults created by a callable are shown as `computed`; configuration values are never included in the output. Call the helper after `add_extensions()` and before `start()` when you want to inspect only the extensions selected by the application. Core fields such as `agentic_model`, `http_host`, and `http_port` are not extension fields and can be imported and configured separately as shown above.
+
+## Configuration
+
+The LLM HTTP adapter reads these environment variables by default:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENAI_API_KEY` | Key for OpenAI-compatible and OpenAI Responses APIs |
+| `ANTHROPIC_API_KEY` | Key for the Anthropic Messages API |
+| `LLM_API_BASE` | Provider base URL |
+| `LLM_API_PROTOCOL` | `chat_completions`, `responses`, or `anthropic_messages` |
+
+The provider must expose a compatible models endpoint. The adapter discovers available models during startup, and `agentic_model` filters the discovered models by substring. The quickstart selects `deepseek-v4-flash`; replace that value with a model available from your provider.
+
+Configuration fields are ordinary Python objects and can be passed as keys in an agent's `config` dictionary on init:
+
+```python
+from commamatrix import *
+
+agent = Agent(
+    "my-agent",
+    config={
+        agentic_model: "my-model",
+        api_base: "https://llm.example.com",
+    },
+)
+```
+
+## Extensions
+
+Extensions are imported and then added to an agent's scope. The recommended preset lists containig built-in features are available in `commamatrix.presets`:
+
+```python
+from commamatrix import Agent
+from commamatrix.presets import assistant
+
+
+async def create_agent() -> Agent:
+    agent = Agent("my_lovely_assistant")
+    await agent.add_extensions(assistant)
+    return agent
+```
+
+Individual extensions can be selected when an agent needs a narrower scope:
+
+```python
+from commamatrix.builtin import data_tools, web_utils
+
+await agent.add_extensions(data_tools, web_utils)
+```
+
+Custom or external extensions can expose normal Python declarations and be activated by import name:
+
+```python
+await agent.add_extensions("my_project.my_extension")
+```
+
+Common declarations include `@tool`, `@instruction`, lifecycle hooks, service subclasses, provider implementations, and `BaseTable` subclasses. See the [extension authoring guide](https://github.com/matrixd0t/commamatrix/blob/master/src/commamatrix/builtin/self_extension/guides) for the complete extension API.
+
+## Security Notes
+
+- Keep `http_host` set to `127.0.0.1` for local development. `0.0.0.0` exposes your HTTP connector to the Internet.
+- HTTP connector passwords are hashed; generated administrator credentials are printed only during initial account creation.
+- CodeAct executes arbitrary Python code with access to the standard library, installed dependencies, and the system terminal. Default subprocess backend is intentionally NOT a security sandbox and must NOT be exposed to untrusted users without an external isolation layer. To enforce configurable limits on the agent’s execution privileges, prefer systemd or Docker-backed implementations.
+- Validate the reverse proxy, TLS, CORS, and network policy before exposing the HTTP connector to the Internet.
+