edumatcher 0.1.5__tar.gz

edumatcher-0.1.5/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: edumatcher
+Version: 0.1.5
+Summary: Educational multi-process trading system with order matching
+License: MIT
+Keywords: finance,exchange,matching-engine,trading,education,learning,order-matching,market-microstructure
+Author: Johan Persson
+Author-email: johan162@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: orjson (>=3.11.9,<4.0.0)
+Requires-Dist: prompt_toolkit (>=3.0,<4.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: pyzmq (>=27.1.0,<28.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Project-URL: Repository, https://github.com/johan162/EduMatcher
+Description-Content-Type: text/markdown
+
+# EduMatcher
+
+**Learn how real trading systems work. Build it from first principles.**
+
+| Category          | Link         |
+| ----------------- | ------------ |
+| **Package**       | [![PyPI version](https://img.shields.io/pypi/v/edumatcher.svg)](https://pypi.org/project/edumatcher/) [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/) |
+| **Documentation** | [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://johan162.github.io/EduMatcher/) |
+| **License**       | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  |
+| **Release**       | [![GitHub release](https://img.shields.io/github/v/release/johan162/edumatcher?include_prereleases)](https://github.com/johan162/edumatcher/releases)  |
+| **CI/CD**         | [![Coverage](https://img.shields.io/badge/coverage-84%25-brightgreen.svg)](coverage.svg)   |
+| **Code Quality**  | [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/) [![Linting: flake8](https://img.shields.io/badge/linting-flake8-yellowgreen)](https://flake8.pycqa.org/) |
+| Repo URL          | [![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat-square&logo=github&logoColor=white)](https://github.com/johan162/edumatcher) |
+
+EduMatcher is an educational trading system that teaches market microstructure,
+matching logic, and exchange architecture through runnable code.
+
+Unlike toy examples, it is designed to be both understandable and fast.
+
+## Why EduMatcher?
+
+- Real exchange mechanics: order books, auctions, clearing, and risk controls
+- Multi-process architecture: gateway, engine, audit, clearing, stats, and tooling
+- Performance-aware implementation: ~60,000 orders/second with microsecond latency
+- Practical protocol design: ALF (ALmost Fix) command language for gateway order entry
+- Strong engineering discipline: type hints, linting, and high test coverage
+
+## Key Features
+
+- Complete lifecycle: order entry, matching, clearing, and audit trail
+- Rich order support: MARKET, LIMIT, STOP, STOP_LIMIT, IOC/FOK, ICEBERG, combo, OCO
+- Market mechanisms: opening/closing auctions and circuit breakers
+- Config-driven behavior via `engine_config.yaml` which acts as reference data for EduMatcher
+- Message-based process boundaries with strong observability
+- Implement real risk controls such as prioce-collar, kill-switch, circuit-breaker, and mass-cancel
+
+## Key Limitations
+
+- No spread-order books
+- No implied (synthetic) orders
+- No primary-secondary site failover
+- No load balancing
+- Limited replay for participants that lose the connection
+- No index calculations
+
+## Performance
+
+EduMatcher does not aim to match venues like NYSE or LSE, but it is still
+fast for a pure Python educational project.
+
+
+### Latency (engine-only, n=1,000 each)
+
+| Order type | min (µs) | median (µs) | P80 (µs) | P90 (µs) | max (µs) |
+| ---------- | -------: | ----------: | -------: | -------: | -------: |
+| Limit      |      8.1 |         8.5 |      9.6 |     10.0 |       18 |
+| Market     |      8.1 |         8.5 |      8.8 |      9.3 |       45 |
+
+### Throughput
+
+| Metric        | Value                                               |
+| ------------- | --------------------------------------------------- |
+| **Max TPS**   | ~60,000 orders/second                              |
+| **Order mix** | 20% Market, 30% aggressive Limit, 50% passive Limit |
+
+*Performance note:* price-collar and circuit-breaker checks run in the hot path
+for every match. They are required for realistic risk control and add measurable cost.
+
+
+
+## Explore the Code
+
+Start with these key areas:
+
+- **[src/edumatcher/engine/](src/edumatcher/engine/)** — Core matching logic and order book
+- **[src/edumatcher/gateway/](src/edumatcher/gateway/)** — Message handling and order validation
+- **[src/edumatcher/clearing/](src/edumatcher/clearing/)** — Trade settlement and P&L calculation
+
+## Documentation
+
+Full docs: [EduMatcher Documentation](https://johan162.github.io/edumatcher/)
+
+Additional references:
+
+- [How an Exchange Works](https://johan162.github.io/how-exchange-works/). This is a generic
+document meant for SW developers with no previous financial experience. Reading this document
+will give the necessary background both in finance and the core workings of an exchange.
+- [ALF Protocol Appendix](https://johan162.github.io/user-guide/20-app-alf-protocol.md). `ALF` 
+is the Gatewauy human protocol used to send in orders vi the `ALF` gateway. It is a drastically
+simplified `FIX` inspired protocol (`ALF` = `ALmost Fix`)
+- [Glossary](https://johan162.github.io/glossary/). An extensiv glossary with all commonly used
+financial terms used in these documents.
+
+
+## Who It's For
+
+- Computer science students learning systems design and concurrency
+- Finance students learning market microstructure and trading mechanics
+- Developers building exchange technology or trading systems
+- Anyone curious about how modern markets actually work
+
+
+## Contributing
+
+This is an educational project. If you find bugs, improve the documentation, or make other enhancements PRs are welcome!
+
+
+## Citation
+
+If you use this tool in teaching or courses, please cite:
+
+```text
+@software{edumatcher,
+  title = {EduMatcher},
+  author = {Johan Persson},
+  year = {2026},
+  url = {https://github.com/johan162/edumatcher},
+  version = {0.1.5}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE).
+

edumatcher-0.1.5/README.md

@@ -0,0 +1,124 @@
+# EduMatcher
+
+**Learn how real trading systems work. Build it from first principles.**
+
+| Category          | Link         |
+| ----------------- | ------------ |
+| **Package**       | [![PyPI version](https://img.shields.io/pypi/v/edumatcher.svg)](https://pypi.org/project/edumatcher/) [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/) |
+| **Documentation** | [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://johan162.github.io/EduMatcher/) |
+| **License**       | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)  |
+| **Release**       | [![GitHub release](https://img.shields.io/github/v/release/johan162/edumatcher?include_prereleases)](https://github.com/johan162/edumatcher/releases)  |
+| **CI/CD**         | [![Coverage](https://img.shields.io/badge/coverage-84%25-brightgreen.svg)](coverage.svg)   |
+| **Code Quality**  | [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/) [![Linting: flake8](https://img.shields.io/badge/linting-flake8-yellowgreen)](https://flake8.pycqa.org/) |
+| Repo URL          | [![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat-square&logo=github&logoColor=white)](https://github.com/johan162/edumatcher) |
+
+EduMatcher is an educational trading system that teaches market microstructure,
+matching logic, and exchange architecture through runnable code.
+
+Unlike toy examples, it is designed to be both understandable and fast.
+
+## Why EduMatcher?
+
+- Real exchange mechanics: order books, auctions, clearing, and risk controls
+- Multi-process architecture: gateway, engine, audit, clearing, stats, and tooling
+- Performance-aware implementation: ~60,000 orders/second with microsecond latency
+- Practical protocol design: ALF (ALmost Fix) command language for gateway order entry
+- Strong engineering discipline: type hints, linting, and high test coverage
+
+## Key Features
+
+- Complete lifecycle: order entry, matching, clearing, and audit trail
+- Rich order support: MARKET, LIMIT, STOP, STOP_LIMIT, IOC/FOK, ICEBERG, combo, OCO
+- Market mechanisms: opening/closing auctions and circuit breakers
+- Config-driven behavior via `engine_config.yaml` which acts as reference data for EduMatcher
+- Message-based process boundaries with strong observability
+- Implement real risk controls such as prioce-collar, kill-switch, circuit-breaker, and mass-cancel
+
+## Key Limitations
+
+- No spread-order books
+- No implied (synthetic) orders
+- No primary-secondary site failover
+- No load balancing
+- Limited replay for participants that lose the connection
+- No index calculations
+
+## Performance
+
+EduMatcher does not aim to match venues like NYSE or LSE, but it is still
+fast for a pure Python educational project.
+
+
+### Latency (engine-only, n=1,000 each)
+
+| Order type | min (µs) | median (µs) | P80 (µs) | P90 (µs) | max (µs) |
+| ---------- | -------: | ----------: | -------: | -------: | -------: |
+| Limit      |      8.1 |         8.5 |      9.6 |     10.0 |       18 |
+| Market     |      8.1 |         8.5 |      8.8 |      9.3 |       45 |
+
+### Throughput
+
+| Metric        | Value                                               |
+| ------------- | --------------------------------------------------- |
+| **Max TPS**   | ~60,000 orders/second                              |
+| **Order mix** | 20% Market, 30% aggressive Limit, 50% passive Limit |
+
+*Performance note:* price-collar and circuit-breaker checks run in the hot path
+for every match. They are required for realistic risk control and add measurable cost.
+
+
+
+## Explore the Code
+
+Start with these key areas:
+
+- **[src/edumatcher/engine/](src/edumatcher/engine/)** — Core matching logic and order book
+- **[src/edumatcher/gateway/](src/edumatcher/gateway/)** — Message handling and order validation
+- **[src/edumatcher/clearing/](src/edumatcher/clearing/)** — Trade settlement and P&L calculation
+
+## Documentation
+
+Full docs: [EduMatcher Documentation](https://johan162.github.io/edumatcher/)
+
+Additional references:
+
+- [How an Exchange Works](https://johan162.github.io/how-exchange-works/). This is a generic
+document meant for SW developers with no previous financial experience. Reading this document
+will give the necessary background both in finance and the core workings of an exchange.
+- [ALF Protocol Appendix](https://johan162.github.io/user-guide/20-app-alf-protocol.md). `ALF` 
+is the Gatewauy human protocol used to send in orders vi the `ALF` gateway. It is a drastically
+simplified `FIX` inspired protocol (`ALF` = `ALmost Fix`)
+- [Glossary](https://johan162.github.io/glossary/). An extensiv glossary with all commonly used
+financial terms used in these documents.
+
+
+## Who It's For
+
+- Computer science students learning systems design and concurrency
+- Finance students learning market microstructure and trading mechanics
+- Developers building exchange technology or trading systems
+- Anyone curious about how modern markets actually work
+
+
+## Contributing
+
+This is an educational project. If you find bugs, improve the documentation, or make other enhancements PRs are welcome!
+
+
+## Citation
+
+If you use this tool in teaching or courses, please cite:
+
+```text
+@software{edumatcher,
+  title = {EduMatcher},
+  author = {Johan Persson},
+  year = {2026},
+  url = {https://github.com/johan162/edumatcher},
+  version = {0.1.5}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE).

edumatcher-0.1.5/pyproject.toml

@@ -0,0 +1,159 @@
+# Setup poetry configuration
+# poetry config virtualenvs.in-project true
+# poetry install --with dev,docs
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "edumatcher"
+version = "0.1.5"
+description = "Educational multi-process trading system with order matching"
+authors = ["Johan Persson <johan162@gmail.com>"]
+readme = "README.md"
+packages = [{include = "edumatcher", from = "src"}]
+keywords = ["finance", "exchange", "matching-engine", "trading", "education", "learning", "order-matching", "market-microstructure"]
+license = "MIT"
+repository = "https://github.com/johan162/EduMatcher"
+
+[tool.poetry.dependencies]
+python = "^3.13"
+pyzmq = "^27.1.0"
+rich = "^15.0.0"
+prompt_toolkit = "^3.0"
+pyyaml = "^6.0.3"
+orjson = "^3.11.9"
+
+[tool.poetry.group.dev.dependencies]
+mkdocs = "^1.6"
+mkdocs-material = "^9.0"
+pytest = "^9.0.3"
+types-PyYAML = "^6.0"
+pytest-cov = "^7.1.0"
+pytest-xdist = ">=3.8.0"
+twine = ">=6.2.0"
+types-tabulate = "^0.10.0.20260308"
+pyright = "^1.1.409"
+flake8 = "^7.3.0"
+black = "^26.3.1"
+mypy = "^1.20.2"
+
+
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = ">=1.5.0"
+mkdocs-material = ">=9.7.6"
+mkdocstrings = {extras = ["python"], version = ">=0.22.0"}
+
+[tool.poetry.scripts]
+pm-engine   = "edumatcher.engine.main:main"
+pm-gateway  = "edumatcher.gateway.main:main"
+pm-viewer   = "edumatcher.viewer.main:main"
+pm-board    = "edumatcher.board.main:main"
+pm-orders   = "edumatcher.orders.main:main"
+pm-audit    = "edumatcher.audit.main:main"
+pm-clearing = "edumatcher.clearing.main:main"
+pm-stats    = "edumatcher.stats.main:main"
+pm-ticker   = "edumatcher.ticker.main:main"
+pm-scheduler = "edumatcher.scheduler.main:main"
+pm-ai-trader = "edumatcher.ai_trader.main:main"
+pm-admin     = "edumatcher.commands.console:main"
+pm-admin-cli = "edumatcher.commands.cli:main"
+pm-ai-swarm = "edumatcher.ai_trader.swarm:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "perf: performance / benchmarking tests (deselect with '-m not perf')",
+]
+addopts = [
+    "--strict-markers",
+    "-m",
+    "not heavy and not probabilistic and not probabilistic_full",
+    "--cov=edumatcher",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py313"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_untyped_calls = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = "yaml"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "scipy.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+disallow_incomplete_defs = false
+disallow_untyped_decorators = false
+warn_return_any = false
+check_untyped_defs = false
+disable_error_code = ["arg-type", "assignment", "call-overload", "type-arg"]
+
+
+[tool.pyright]
+pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUntypedFunctionDecorator = false
+reportUntypedBaseClass = false
+reportUnknownLambdaType = false
+executionEnvironments = [
+    { root = "tests", reportPrivateUsage = false, reportUnusedVariable = false, reportUnusedFunction = false, reportUnusedImport = false, reportMissingTypeArgument = false, reportArgumentType = false, reportOptionalOperand = false, reportOptionalMemberAccess = false, reportOperatorIssue = false, reportAttributeAccessIssue = false, reportCallIssue = false, reportReturnType = false },
+    { root = "tools", reportUnusedImport = false, reportMissingTypeArgument = false, reportArgumentType = false, reportOptionalMemberAccess = false },
+    { root = "src" },
+]
+
+
+

edumatcher-0.1.5/src/edumatcher/ai_trader/__init__.py

@@ -0,0 +1,5 @@
+"""AI trader process package."""
+
+from edumatcher.ai_trader.personality import PersonalityProfile, get_profile
+
+__all__ = ["PersonalityProfile", "get_profile"]