moiryx 0.1.0a1__tar.gz

moiryx-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+Notable changes are recorded here. Versions follow PEP 440; `0.1.0a1` is the
+first alpha.
+
+## 0.1.0a1
+
+### Added
+
+- Markdown agent definitions, YAML model aliases, and the `Agent` and `@tool`
+  public API.
+- Text-agent runtime with tool validation, conservative repair of malformed
+  calls, and separate retry budgets.
+- Pydantic structured results, including nested models, through a synthetic
+  final tool or native JSON schema where the provider supports it.
+- OpenAI-compatible, OpenRouter, Azure OpenAI, Azure Foundry, and Vertex AI
+  adapters.
+- Workspace-scoped file tools and an explicitly enabled `shell` tool.
+- Run events, optional JSONL traces, and centralized secret redaction.
+- Deterministic AC1–AC11 acceptance tests, examples, and a CI matrix.
+
+### Alpha limitations
+
+- No streaming, sessions, multimodal input, or automatic model fallback.
+- `shell` is not a sandbox; use it only in trusted environments.
+- Function calling and JSON-schema behavior of local models depend on the
+  model and its chat template.
+
+See the [alpha release notes](docs/release-notes-alpha.md) for verification
+details and limitations.

moiryx-0.1.0a1/LICENSE

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

moiryx-0.1.0a1/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+recursive-include docs *.md
+recursive-include examples *.md *.py *.yaml

moiryx-0.1.0a1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: moiryx
+Version: 0.1.0a1
+Summary: Thin, config-driven Python runtime for LLM agents.
+Author: Moiryx contributors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/kamilsz713/moiryx
+Project-URL: Issues, https://github.com/kamilsz713/moiryx/issues
+Keywords: agents,llm,tools,structured-output
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docstring-parser<1,>=0.17
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: azure
+Provides-Extra: google
+Requires-Dist: google-genai<2,>=1; extra == "google"
+Provides-Extra: all
+Requires-Dist: google-genai<2,>=1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: mypy<2,>=1.11; extra == "dev"
+Requires-Dist: pytest<10,>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1; extra == "dev"
+Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
+Dynamic: license-file
+
+# Moiryx
+
+Moiryx lets you define an agent in Markdown, select its model in YAML, and call
+it like an async Python object. You can move the same agent from a local
+`llama-server` to OpenRouter, Azure, or Vertex AI without changing Python code.
+
+This project is an alpha. Its deliberately small user-facing API consists of
+`Agent`, `@tool`, and `moiryx.yaml`.
+
+## Installation
+
+Install the alpha from PyPI once it is available:
+
+```bash
+python -m pip install moiryx==0.1.0a1
+```
+
+For development from this checkout:
+
+```bash
+python -m pip install -e .
+```
+
+Vertex AI requires the optional Google Gen AI SDK. For a PyPI installation:
+
+```bash
+python -m pip install "moiryx[google]==0.1.0a1"
+```
+
+From this checkout:
+
+```bash
+python -m pip install -e ".[google]"
+```
+
+## Your first agent with a local llama-server
+
+Start an OpenAI-compatible endpoint and create `moiryx.yaml`:
+
+```yaml
+providers:
+  local:
+    type: openai_compatible
+    base_url: http://127.0.0.1:8080/v1
+
+models:
+  local_chat:
+    provider: local
+    model: local-model
+```
+
+Save the agent as `agents/chat.md`:
+
+```markdown
+---
+model: local_chat
+---
+Answer directly and say when you are uncertain.
+```
+
+Call it from Python:
+
+```python
+import asyncio
+
+from moiryx import Agent
+
+
+async def main() -> None:
+    agent = Agent("agents/chat.md")
+    answer = await agent("What is the difference between a process and a thread?")
+    print(answer)
+
+
+asyncio.run(main())
+```
+
+For a long-lived application, call `await agent.aclose()` when you are done, or
+use `async with Agent(...)`. This releases the provider's HTTP connections. A
+one-off script can simply exit.
+
+## Built-in tools
+
+Tools are opt-in. Add only the ones an agent needs to its frontmatter:
+
+```markdown
+---
+model: local_chat
+tools: [read_file, list_files, grep]
+---
+Inspect files in the workspace and cite the paths you used.
+```
+
+Available tools are `read_file`, `list_files`, `glob_files`, `grep`,
+`write_file`, `edit_file`, and `shell`. File operations stay within
+`runtime.workspace_root` by default.
+
+> `shell` is not a security sandbox. Enable it only for agents and workspaces
+> you trust.
+
+## Custom tools
+
+```python
+from moiryx import tool
+
+
+@tool
+def word_count(text: str) -> int:
+    """Count words in text."""
+    return len(text.split())
+```
+
+Import the module through the configuration, then select the tool in the
+agent definition:
+
+```yaml
+tool_modules: [my_tools]
+```
+
+```markdown
+---
+model: local_chat
+tools: [word_count]
+---
+Use the tool to count words accurately.
+```
+
+## Structured output
+
+Declare the result with an ordinary Pydantic model:
+
+```python
+from pydantic import BaseModel, Field
+
+
+class ReviewResult(BaseModel):
+    accepted: bool
+    score: float = Field(ge=0, le=1)
+    findings: list[str]
+```
+
+Reference it as `module:Class` in the agent:
+
+```markdown
+---
+model: local_chat
+output: review_models:ReviewResult
+---
+Review the change and return a result matching the schema.
+```
+
+`await agent(...)` returns a `ReviewResult` instance. JSON embedded in plain
+text does not count as a structured result.
+
+## Switching providers in YAML
+
+Keep the Python code and agent file; change the model alias configuration:
+
+```yaml
+providers:
+  router:
+    type: openrouter
+    api_key: ${OPENROUTER_API_KEY}
+    headers:
+      HTTP-Referer: https://example.invalid
+      X-OpenRouter-Title: Moiryx example
+
+models:
+  local_chat:
+    provider: router
+    model: anthropic/claude-sonnet-4.5
+```
+
+Supported provider types are `openai_compatible` (including llama-server,
+vLLM, and SGLang), `openrouter`, `azure_openai`, `azure_foundry`, and
+`vertex_ai` (using Application Default Credentials or a service account).
+
+## Logging and traces
+
+```yaml
+logging:
+  level: INFO
+  trace_dir: .moiryx/runs
+  include_raw_response: false
+```
+
+Each run has its own ID and, when tracing is enabled, an
+`.moiryx/runs/<run-id>/events.jsonl` file. Raw provider responses are off by
+default. If enabled, configured secrets and sensitive fields are still
+redacted.
+
+## Examples and development
+
+See [`examples/`](examples/) for runnable definitions and [`docs/`](docs/) for
+architecture, limitations, release notes, and the issue backlog.
+
+Run the local quality checks:
+
+```bash
+python scripts/check.py
+python -m pytest -m acceptance -q
+python -m build
+python scripts/audit_artifacts.py dist
+```
+
+Acceptance tests use deterministic fake providers; they need no network or
+credentials. The live local-endpoint test is opt-in through
+`MOIRYX_OPENAI_COMPATIBLE_LIVE_URL` and `MOIRYX_OPENAI_COMPATIBLE_LIVE_MODEL`.

moiryx-0.1.0a1/README.md

@@ -0,0 +1,208 @@
+# Moiryx
+
+Moiryx lets you define an agent in Markdown, select its model in YAML, and call
+it like an async Python object. You can move the same agent from a local
+`llama-server` to OpenRouter, Azure, or Vertex AI without changing Python code.
+
+This project is an alpha. Its deliberately small user-facing API consists of
+`Agent`, `@tool`, and `moiryx.yaml`.
+
+## Installation
+
+Install the alpha from PyPI once it is available:
+
+```bash
+python -m pip install moiryx==0.1.0a1
+```
+
+For development from this checkout:
+
+```bash
+python -m pip install -e .
+```
+
+Vertex AI requires the optional Google Gen AI SDK. For a PyPI installation:
+
+```bash
+python -m pip install "moiryx[google]==0.1.0a1"
+```
+
+From this checkout:
+
+```bash
+python -m pip install -e ".[google]"
+```
+
+## Your first agent with a local llama-server
+
+Start an OpenAI-compatible endpoint and create `moiryx.yaml`:
+
+```yaml
+providers:
+  local:
+    type: openai_compatible
+    base_url: http://127.0.0.1:8080/v1
+
+models:
+  local_chat:
+    provider: local
+    model: local-model
+```
+
+Save the agent as `agents/chat.md`:
+
+```markdown
+---
+model: local_chat
+---
+Answer directly and say when you are uncertain.
+```
+
+Call it from Python:
+
+```python
+import asyncio
+
+from moiryx import Agent
+
+
+async def main() -> None:
+    agent = Agent("agents/chat.md")
+    answer = await agent("What is the difference between a process and a thread?")
+    print(answer)
+
+
+asyncio.run(main())
+```
+
+For a long-lived application, call `await agent.aclose()` when you are done, or
+use `async with Agent(...)`. This releases the provider's HTTP connections. A
+one-off script can simply exit.
+
+## Built-in tools
+
+Tools are opt-in. Add only the ones an agent needs to its frontmatter:
+
+```markdown
+---
+model: local_chat
+tools: [read_file, list_files, grep]
+---
+Inspect files in the workspace and cite the paths you used.
+```
+
+Available tools are `read_file`, `list_files`, `glob_files`, `grep`,
+`write_file`, `edit_file`, and `shell`. File operations stay within
+`runtime.workspace_root` by default.
+
+> `shell` is not a security sandbox. Enable it only for agents and workspaces
+> you trust.
+
+## Custom tools
+
+```python
+from moiryx import tool
+
+
+@tool
+def word_count(text: str) -> int:
+    """Count words in text."""
+    return len(text.split())
+```
+
+Import the module through the configuration, then select the tool in the
+agent definition:
+
+```yaml
+tool_modules: [my_tools]
+```
+
+```markdown
+---
+model: local_chat
+tools: [word_count]
+---
+Use the tool to count words accurately.
+```
+
+## Structured output
+
+Declare the result with an ordinary Pydantic model:
+
+```python
+from pydantic import BaseModel, Field
+
+
+class ReviewResult(BaseModel):
+    accepted: bool
+    score: float = Field(ge=0, le=1)
+    findings: list[str]
+```
+
+Reference it as `module:Class` in the agent:
+
+```markdown
+---
+model: local_chat
+output: review_models:ReviewResult
+---
+Review the change and return a result matching the schema.
+```
+
+`await agent(...)` returns a `ReviewResult` instance. JSON embedded in plain
+text does not count as a structured result.
+
+## Switching providers in YAML
+
+Keep the Python code and agent file; change the model alias configuration:
+
+```yaml
+providers:
+  router:
+    type: openrouter
+    api_key: ${OPENROUTER_API_KEY}
+    headers:
+      HTTP-Referer: https://example.invalid
+      X-OpenRouter-Title: Moiryx example
+
+models:
+  local_chat:
+    provider: router
+    model: anthropic/claude-sonnet-4.5
+```
+
+Supported provider types are `openai_compatible` (including llama-server,
+vLLM, and SGLang), `openrouter`, `azure_openai`, `azure_foundry`, and
+`vertex_ai` (using Application Default Credentials or a service account).
+
+## Logging and traces
+
+```yaml
+logging:
+  level: INFO
+  trace_dir: .moiryx/runs
+  include_raw_response: false
+```
+
+Each run has its own ID and, when tracing is enabled, an
+`.moiryx/runs/<run-id>/events.jsonl` file. Raw provider responses are off by
+default. If enabled, configured secrets and sensitive fields are still
+redacted.
+
+## Examples and development
+
+See [`examples/`](examples/) for runnable definitions and [`docs/`](docs/) for
+architecture, limitations, release notes, and the issue backlog.
+
+Run the local quality checks:
+
+```bash
+python scripts/check.py
+python -m pytest -m acceptance -q
+python -m build
+python scripts/audit_artifacts.py dist
+```
+
+Acceptance tests use deterministic fake providers; they need no network or
+credentials. The live local-endpoint test is opt-in through
+`MOIRYX_OPENAI_COMPATIBLE_LIVE_URL` and `MOIRYX_OPENAI_COMPATIBLE_LIVE_MODEL`.

moiryx-0.1.0a1/docs/01-vision-and-contract.md

@@ -0,0 +1,41 @@
+# Vision and public contract
+
+Moiryx is a small, configuration-driven Python runtime for LLM agents. It
+handles provider requests, tool calls, validation, retries, and typed results;
+application orchestration remains ordinary Python.
+
+## Public API
+
+```python
+from moiryx import Agent, tool
+
+reviewer = Agent("agents/reviewer.md")
+review = await reviewer("Review src/cache.py")
+```
+
+The v0.1 contract is intentionally narrow:
+
+- `Agent` takes an agent-file path; `await agent(prompt)` starts an isolated run.
+- An agent without `output` returns final text. An agent with `output` returns
+  an instance of the declared Pydantic model.
+- `@tool` registers an ordinary Python function under its function name.
+- Markdown contains instructions, YAML selects the provider and model, and
+  Python controls multi-agent orchestration.
+- No default result wrapper, `run()` method, constructor model override, or
+  JSON-from-prose fallback is part of the public API.
+
+## Scope
+
+The alpha includes text and structured agent loops, custom and workspace
+tools, OpenAI-compatible/OpenRouter/Azure/Vertex AI adapters, bounded retries,
+run events, optional JSONL traces, and deterministic offline tests.
+
+It does not include a workflow DSL, persistent memory, RAG framework, vector
+store, HTTP server, GUI, distributed workers, streaming API, automatic context
+compression, MCP, policy engine, or automatic model fallback. Those should be
+added only when real use cases justify shared abstractions.
+
+Success means a text agent, a tool-using agent, and a nested structured-result
+agent work without special cases; the same agent can switch providers through
+YAML; invalid tool calls cannot cause guessed side effects; concurrent runs do
+not share history; and errors and traces explain what happened.

moiryx-0.1.0a1/docs/02-architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+```text
+Application code ── await agent(prompt) ──> Agent
+                                        ├── Markdown -> AgentSpec
+                                        ├── YAML -> model/provider registry
+                                        └── selected tools/output model
+                                                   │
+                                                   ▼
+                                Runtime + per-call RunContext
+                                  ├── provider retry and limits
+                                  ├── whole-batch tool preflight
+                                  ├── tool execution and repair
+                                  ├── structured result validation
+                                  └── events and trace
+                                                   │
+                                                   ▼
+                                      ProviderAdapter -> API/SDK
+```
+
+`Agent` resolves configuration, model, provider, tools, and output schema at
+construction. It holds no per-run messages. Each call creates its own
+`RunContext`, so one agent instance can serve concurrent calls without mixing
+histories. Call `await agent.aclose()` or use `async with Agent(...)` to release
+its provider client in a long-lived process.
+
+The provider boundary takes a normalized `ModelRequest` and returns a
+`ModelResponse`. Adapters retain malformed raw tool arguments for the shared
+repair layer but do not expose SDK objects to the runtime. The core does not
+branch on provider names, and tools do not import provider adapters.
+
+## One run
+
+1. Start an isolated context with system and user messages.
+2. Request a model response; retries do not consume extra agent steps.
+3. Preflight every tool call before executing any call in the batch.
+4. If the batch is invalid, execute none of it and return bounded repair
+   feedback. Otherwise, execute calls sequentially.
+5. Stop on final text or a validated structured result. Missing content,
+   exhausted repair budgets, and step limits raise explicit errors.
+
+Events observe this flow but never control it. Logging and optional JSONL
+traces redact configured secrets before output.
+
+## Repository layout
+
+- `src/moiryx/agent.py`, `agent_spec.py`, `config.py`: user entry point and
+  configuration loading.
+- `runtime.py`, `messages.py`, `models.py`: provider-neutral execution.
+- `tools/`, `output/`, `providers/`: isolated subsystems.
+- `tests/`: deterministic unit, adapter, acceptance, and opt-in live tests.

moiryx-0.1.0a1/docs/03-configuration-and-agents.md

@@ -0,0 +1,70 @@
+# Configuration and agent definitions
+
+Moiryx reads the path in `MOIRYX_CONFIG` when set, otherwise `./moiryx.yaml`
+from the current working directory. It does not merge files or search parent
+directories. Call `reset_config_cache()` only when deliberately reloading a
+configuration in the same process.
+
+```yaml
+providers:
+  local:
+    type: openai_compatible
+    base_url: http://127.0.0.1:8080/v1
+
+models:
+  reviewer:
+    provider: local
+    model: local-model
+
+runtime:
+  default_max_steps: 20
+  provider_retry_attempts: 3
+  structured_output_retries: 2
+  tool_call_repair_attempts: 2
+  tool_timeout_seconds: 60
+  workspace_root: .
+  allow_paths_outside_workspace: false
+  max_tool_output_chars: 50000
+
+logging:
+  level: INFO
+  trace_dir: .moiryx/runs
+  include_raw_response: false
+```
+
+`providers` keys name connections; `models` keys name logical model aliases.
+Model IDs are opaque strings, including IDs with slashes. String values may
+contain `${ENV_VAR}` references; missing variables fail configuration loading.
+Keep secrets in environment variables rather than committed YAML.
+
+Generation options merge in this order: runtime defaults, model settings,
+then agent overrides. The common options are `temperature`, `max_tokens`,
+`top_p`, and `seed`. Unknown options are rejected. `tool_modules` explicitly
+lists modules to import for custom tools; there is no filesystem scan.
+
+An agent file contains YAML frontmatter followed by Markdown system
+instructions:
+
+```markdown
+---
+name: reviewer
+model: reviewer
+tools: [read_file, grep]
+output: my_project.schemas.review:ReviewOutput
+max_steps: 20
+generation:
+  temperature: 0.2
+---
+Review the code and report specific findings.
+```
+
+Only `model` is required. `name` defaults to the file stem; `tools` defaults
+to an empty list; `output` is an import path to a `BaseModel` subclass;
+`max_steps` defaults to `runtime.default_max_steps`. The constructor catches
+invalid files, aliases, tool names, output models, options, and unsupported
+provider capabilities before the first request.
+
+The `moiryx.run` logger emits run boundaries at INFO, model and successful
+tool steps at DEBUG, retries and repairs at WARNING, and failed runs at ERROR.
+Setting `logging.trace_dir` writes one `events.jsonl` per run. Raw responses
+are disabled by default and remain subject to central redaction when enabled.