yoker 0.1.0__tar.gz

yoker-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: yoker
+Version: 0.1.0
+Summary: A Python agent harness with configurable tools and guardrails - one who yokes agents together
+Author-email: Christophe VG <contact@christophe.vg>
+License: MIT
+Project-URL: Homepage, https://github.com/christophevg/yoker
+Project-URL: Documentation, https://yoker.readthedocs.io/
+Project-URL: Repository, https://github.com/christophevg/yoker
+Project-URL: Issues, https://github.com/christophevg/yoker/issues
+Keywords: agent,llm,ollama,ai,harness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: ollama>=0.6.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
+Requires-Dist: myst-parser>=2.0.0; extra == "dev"
+Requires-Dist: tox>=4.0.0; extra == "dev"
+
+# Yoker
+
+A Python-based agent harness with configurable tools, guardrails, and Ollama backend integration.
+
+## Current Status
+
+**Minimal prototype available!** The basic chat loop with tool calling is working:
+
+```bash
+# Install (requires Python 3.10+)
+pip install -e .
+
+# Run interactive chat
+python -m yoker
+```
+
+The prototype includes:
+- Interactive chat loop with Ollama
+- Basic `read` tool for file reading
+- Streaming responses
+- Structured logging
+
+See [Quick Start](#quick-start) below for details.
+
+## Name
+
+**"yoker"** - One who yokes. A person or device that joins or attaches things together, specifically one who yokes oxen or links things together.
+
+From the agent noun of "yoke", which derives from PIE *\yeug-* meaning "to join" (same root as yoga, conjugate, junction).
+
+Pairs beautifully with "clitic" (both are joining tools - clitic joins words, yoker joins agents).
+
+See `docs/NAME.md` for full naming documentation.
+
+## Vision
+
+Create a lightweight, configurable agent harness that provides a structured environment for AI agents to operate within defined boundaries. The harness manages tool access, enforces guardrails, handles context persistence, and integrates with Ollama as the LLM backend.
+
+## Goals
+
+1. **Safety First**: Guardrails prevent agents from performing unintended operations
+2. **Configurability**: All tools, parameters, and limits configurable via TOML
+3. **Simplicity**: Specific tools instead of generic shell access
+4. **Transparency**: Clear logging and reporting of all agent actions
+5. **Extensibility**: Easy to add new tools while maintaining guardrails
+6. **Compatibility**: Agent definitions compatible with Claude Code format
+
+## Core Components
+
+### 1. Configuration System
+
+- **TOML configuration file**: Harness settings, tool guardrails, Ollama parameters
+- **Markdown agent definitions**: With YAML frontmatter (compatible with Claude Code)
+
+### 2. Tool System
+
+MVP tools (no generic Bash):
+
+| Tool | Purpose | Guardrails |
+|------|---------|------------|
+| List | Directory listing | Path restrictions, pattern filters |
+| Read | File reading | Path restrictions, size limits |
+| Write | File writing | Path restrictions, overwrite protection |
+| Update | File editing | Path restrictions, diff validation |
+| Search | Grep/glob-like | Path restrictions, pattern limits |
+| Agent | Spawn subagents | Recursion depth, tool subset |
+
+### 3. Context Manager
+
+Persists context for consecutive LLM calls:
+- Conversation history (JSONL format - append-friendly)
+- Agent state
+- Working memory
+- Per-session files in configurable location
+
+### 4. Ollama Integration
+
+- Assumes Ollama is running externally
+- All configurable parameters exposed
+- Model selection per agent possible
+
+### 5. Agent Definitions
+
+Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: researcher
+description: Research assistant
+tools: List, Read, Search
+---
+
+# Researcher Agent
+
+You are a research assistant...
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        Yoker                             │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │  Config     │  │  Context    │  │  Logging/       │  │
+│  │  Loader     │  │  Manager    │  │  Reporting      │  │
+│  │  (TOML)     │  │  (JSONL)    │  │                 │  │
+│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │
+│         │                │                  │           │
+│         ▼                ▼                  ▼           │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Tool Execution Layer                   ││
+│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌───────┐  ││
+│  │  │List │ │Read │ │Write│ │Update│ │Search│ │Agent  │  ││
+│  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └───────┘  ││
+│  └─────────────────────────────────────────────────────┘│
+│                          │                              │
+│                          ▼                              │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Ollama Backend Client                  ││
+│  │      (HTTP API, configurable parameters)            ││
+│  └─────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+```
+yoker/
+├── src/yoker/           # Main package
+├── tests/               # Test suite
+├── docs/               # Sphinx documentation
+├── examples/           # Example configurations
+├── analysis/           # Functional analysis
+├── pyproject.toml      # Package configuration
+└── README.md
+```
+
+## Quick Start
+
+### Minimal Prototype
+
+The current prototype provides a basic interactive chat with tool calling:
+
+```bash
+# Install
+pip install -e .
+
+# Run
+python -m yoker
+```
+
+Example session:
+```
+Yoker v0.1.0 - Using model: glm-5:cloud
+Type your message and press Enter. Press Ctrl+D to quit.
+
+> What's in the README.md file?
+
+I'll read the README.md file for you.
+
+[13:49:49] INFO yoker.agent - Tool call: read({'path': 'README.md'})
+[13:49:49] INFO yoker.agent - Tool result: # Yoker...
+
+The README.md file describes **Yoker**, a Python-based agent harness...
+
+> ^D
+Goodbye!
+```
+
+### Planned Full Usage
+
+```bash
+# Create config
+cat > yoker.toml << EOF
+[ollama]
+model = "llama3.2"
+base_url = "http://localhost:11434"
+
+[tools.list]
+allowed_paths = ["/workspace"]
+
+[tools.read]
+allowed_paths = ["/workspace"]
+max_size_kb = 100
+
+[tools.agent]
+max_recursion_depth = 3
+
+[agents]
+directory = "./agents"
+EOF
+
+# Create agent definition
+mkdir agents
+cat > agents/main.md << EOF
+---
+name: main
+description: Default assistant
+tools: List, Read, Write, Update, Search, Agent
+---
+
+You are a helpful assistant.
+EOF
+
+# Run harness (planned)
+yoker --config yoker.toml
+```
+
+## Documentation
+
+- Name documentation: `docs/NAME.md`
+- Functional analysis: `analysis/functional.md`
+- Interview notes: `analysis/interview.md`
+
+## Integration with Clitic
+
+Yoker provides the agent runtime, Clitic provides the TUI:
+
+- Build agents using Yoker APIs
+- Optionally add Clitic-based CLI interface
+- Deploy agents with or without UI (daemon mode)

yoker-0.1.0/README.md

@@ -0,0 +1,222 @@
+# Yoker
+
+A Python-based agent harness with configurable tools, guardrails, and Ollama backend integration.
+
+## Current Status
+
+**Minimal prototype available!** The basic chat loop with tool calling is working:
+
+```bash
+# Install (requires Python 3.10+)
+pip install -e .
+
+# Run interactive chat
+python -m yoker
+```
+
+The prototype includes:
+- Interactive chat loop with Ollama
+- Basic `read` tool for file reading
+- Streaming responses
+- Structured logging
+
+See [Quick Start](#quick-start) below for details.
+
+## Name
+
+**"yoker"** - One who yokes. A person or device that joins or attaches things together, specifically one who yokes oxen or links things together.
+
+From the agent noun of "yoke", which derives from PIE *\yeug-* meaning "to join" (same root as yoga, conjugate, junction).
+
+Pairs beautifully with "clitic" (both are joining tools - clitic joins words, yoker joins agents).
+
+See `docs/NAME.md` for full naming documentation.
+
+## Vision
+
+Create a lightweight, configurable agent harness that provides a structured environment for AI agents to operate within defined boundaries. The harness manages tool access, enforces guardrails, handles context persistence, and integrates with Ollama as the LLM backend.
+
+## Goals
+
+1. **Safety First**: Guardrails prevent agents from performing unintended operations
+2. **Configurability**: All tools, parameters, and limits configurable via TOML
+3. **Simplicity**: Specific tools instead of generic shell access
+4. **Transparency**: Clear logging and reporting of all agent actions
+5. **Extensibility**: Easy to add new tools while maintaining guardrails
+6. **Compatibility**: Agent definitions compatible with Claude Code format
+
+## Core Components
+
+### 1. Configuration System
+
+- **TOML configuration file**: Harness settings, tool guardrails, Ollama parameters
+- **Markdown agent definitions**: With YAML frontmatter (compatible with Claude Code)
+
+### 2. Tool System
+
+MVP tools (no generic Bash):
+
+| Tool | Purpose | Guardrails |
+|------|---------|------------|
+| List | Directory listing | Path restrictions, pattern filters |
+| Read | File reading | Path restrictions, size limits |
+| Write | File writing | Path restrictions, overwrite protection |
+| Update | File editing | Path restrictions, diff validation |
+| Search | Grep/glob-like | Path restrictions, pattern limits |
+| Agent | Spawn subagents | Recursion depth, tool subset |
+
+### 3. Context Manager
+
+Persists context for consecutive LLM calls:
+- Conversation history (JSONL format - append-friendly)
+- Agent state
+- Working memory
+- Per-session files in configurable location
+
+### 4. Ollama Integration
+
+- Assumes Ollama is running externally
+- All configurable parameters exposed
+- Model selection per agent possible
+
+### 5. Agent Definitions
+
+Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: researcher
+description: Research assistant
+tools: List, Read, Search
+---
+
+# Researcher Agent
+
+You are a research assistant...
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        Yoker                             │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │  Config     │  │  Context    │  │  Logging/       │  │
+│  │  Loader     │  │  Manager    │  │  Reporting      │  │
+│  │  (TOML)     │  │  (JSONL)    │  │                 │  │
+│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │
+│         │                │                  │           │
+│         ▼                ▼                  ▼           │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Tool Execution Layer                   ││
+│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌───────┐  ││
+│  │  │List │ │Read │ │Write│ │Update│ │Search│ │Agent  │  ││
+│  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └───────┘  ││
+│  └─────────────────────────────────────────────────────┘│
+│                          │                              │
+│                          ▼                              │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Ollama Backend Client                  ││
+│  │      (HTTP API, configurable parameters)            ││
+│  └─────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+```
+yoker/
+├── src/yoker/           # Main package
+├── tests/               # Test suite
+├── docs/               # Sphinx documentation
+├── examples/           # Example configurations
+├── analysis/           # Functional analysis
+├── pyproject.toml      # Package configuration
+└── README.md
+```
+
+## Quick Start
+
+### Minimal Prototype
+
+The current prototype provides a basic interactive chat with tool calling:
+
+```bash
+# Install
+pip install -e .
+
+# Run
+python -m yoker
+```
+
+Example session:
+```
+Yoker v0.1.0 - Using model: glm-5:cloud
+Type your message and press Enter. Press Ctrl+D to quit.
+
+> What's in the README.md file?
+
+I'll read the README.md file for you.
+
+[13:49:49] INFO yoker.agent - Tool call: read({'path': 'README.md'})
+[13:49:49] INFO yoker.agent - Tool result: # Yoker...
+
+The README.md file describes **Yoker**, a Python-based agent harness...
+
+> ^D
+Goodbye!
+```
+
+### Planned Full Usage
+
+```bash
+# Create config
+cat > yoker.toml << EOF
+[ollama]
+model = "llama3.2"
+base_url = "http://localhost:11434"
+
+[tools.list]
+allowed_paths = ["/workspace"]
+
+[tools.read]
+allowed_paths = ["/workspace"]
+max_size_kb = 100
+
+[tools.agent]
+max_recursion_depth = 3
+
+[agents]
+directory = "./agents"
+EOF
+
+# Create agent definition
+mkdir agents
+cat > agents/main.md << EOF
+---
+name: main
+description: Default assistant
+tools: List, Read, Write, Update, Search, Agent
+---
+
+You are a helpful assistant.
+EOF
+
+# Run harness (planned)
+yoker --config yoker.toml
+```
+
+## Documentation
+
+- Name documentation: `docs/NAME.md`
+- Functional analysis: `analysis/functional.md`
+- Interview notes: `analysis/interview.md`
+
+## Integration with Clitic
+
+Yoker provides the agent runtime, Clitic provides the TUI:
+
+- Build agents using Yoker APIs
+- Optionally add Clitic-based CLI interface
+- Deploy agents with or without UI (daemon mode)

yoker-0.1.0/pyproject.toml

@@ -0,0 +1,135 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yoker"
+version = "0.1.0"
+description = "A Python agent harness with configurable tools and guardrails - one who yokes agents together"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+  {name = "Christophe VG", email = "contact@christophe.vg"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+keywords = ["agent", "llm", "ollama", "ai", "harness"]
+
+dependencies = [
+  "httpx>=0.25.0",
+  "ollama>=0.6.0",
+  "rich>=14.0.0",
+  "structlog>=23.0.0",
+  "pyyaml>=6.0",
+  "tomli>=2.0;python_version<'3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0.0",
+  "pytest-cov>=4.0.0",
+  "pytest-asyncio>=0.21.0",
+  "mypy>=1.0.0",
+  "ruff>=0.1.0",
+  "build>=1.0.0",
+  "twine>=5.0.0",
+  "sphinx>=7.0.0",
+  "sphinx-rtd-theme>=2.0.0",
+  "myst-parser>=2.0.0",
+  "tox>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/christophevg/yoker"
+Documentation = "https://yoker.readthedocs.io/"
+Repository = "https://github.com/christophevg/yoker"
+Issues = "https://github.com/christophevg/yoker/issues"
+
+[project.scripts]
+yoker = "yoker.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+yoker = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-v --cov=yoker --cov-report=term-missing"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "UP",  # pyupgrade
+]
+ignore = [
+  "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["yoker"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "def __repr__",
+  "raise NotImplementedError",
+  "if TYPE_CHECKING:",
+]
+
+[tool.tox]
+env_list = ["py310", "py311", "py312"]
+
+[tool.tox.env_run_base]
+extras = ["dev"]
+commands = [
+  ["pytest", "-v", "--cov=yoker", "--cov-report=term-missing"],
+]
+
+[tool.tox.env.py310]
+base_python = ["python3.10"]
+
+[tool.tox.env.py311]
+base_python = ["python3.11"]
+
+[tool.tox.env.py312]
+base_python = ["python3.12"]

yoker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yoker-0.1.0/src/yoker/__init__.py

@@ -0,0 +1,11 @@
+"""
+yoker - A Python agent harness with configurable tools and guardrails.
+
+One who yokes - the agent noun from "yoke" (PIE *yeug-* meaning "to join").
+Pairs with "clitic" (both are joining tools).
+"""
+
+__version__ = "0.1.0"
+__author__ = "Christophe VG"
+
+# Public API will be exported here as implementation progresses

yoker-0.1.0/src/yoker/__main__.py

@@ -0,0 +1,34 @@
+"""Entry point for running Yoker as a module.
+
+Usage: python -m yoker
+"""
+
+import logging
+
+from rich.logging import RichHandler
+
+from yoker import __version__
+from yoker.agent import Agent
+
+# Configure logging
+logging.basicConfig(
+  level=logging.INFO,
+  format="%(name)s - %(message)s",
+  datefmt="[%X]",
+  handlers=[RichHandler()],
+)
+
+# Silence noisy modules
+for module in ["httpx", "httpcore", "ollama"]:
+  logging.getLogger(module).setLevel(logging.WARNING)
+
+
+def main() -> None:
+  """Run the interactive agent."""
+  print(f"Yoker v{__version__}")
+  print("=" * 40)
+  Agent().start()
+
+
+if __name__ == "__main__":
+  main()

yoker-0.1.0/src/yoker/agent.py

@@ -0,0 +1,89 @@
+"""Minimal Agent implementation for Yoker prototype."""
+
+import logging
+
+from ollama import Client
+
+from yoker.tools import AVAILABLE_TOOLS
+
+logger = logging.getLogger(__name__)
+
+
+class Agent:
+  """Minimal agent that chats with Ollama and uses tools."""
+
+  def __init__(self, model: str = "glm-5:cloud"):
+    self.client = Client()
+    self.model = model
+    self.tools = AVAILABLE_TOOLS
+
+  def start(self) -> None:
+    """Start the interactive chat loop."""
+    messages: list[dict] = [
+      {"role": "system", "content": "You are a helpful assistant."},
+    ]
+
+    print(f"Yoker v0.1.0 - Using model: {self.model}")
+    print("Type your message and press Enter. Press Ctrl+D (or Ctrl+Z on Windows) to quit.\n")
+
+    while True:
+      try:
+        user_input = input("> ")
+      except EOFError:
+        print("\nGoodbye!")
+        break
+
+      if not user_input.strip():
+        continue
+
+      messages.append({"role": "user", "content": user_input})
+
+      # Process with model, handling tool calls in a loop
+      while True:
+        response = self.client.chat(
+          model=self.model,
+          messages=messages,
+          tools=list(self.tools.values()),
+        )
+
+        # Extract response content
+        content = response.message.content or ""
+        tool_calls = response.message.tool_calls or []
+
+        # Show assistant response
+        if content:
+          print(f"\n{content}\n")
+
+        # If no tool calls, we're done with this turn
+        if not tool_calls:
+          break
+
+        # Add assistant message to history
+        messages.append({
+          "role": "assistant",
+          "content": content,
+          "tool_calls": tool_calls,
+        })
+
+        # Process tool calls
+        for call in tool_calls:
+          tool_name = call.function.name
+          tool_args = call.function.arguments
+
+          logger.info(f"Tool call: {tool_name}({tool_args})")
+
+          try:
+            result = self.tools[tool_name](**tool_args)
+          except KeyError:
+            result = f"Error: Unknown tool '{tool_name}'"
+          except Exception as e:
+            result = f"Error executing tool: {e}"
+
+          logger.info(f"Tool result: {result[:100]}...")
+
+          # Add tool result to messages
+          messages.append({
+            "role": "tool",
+            "name": tool_name,
+            "content": str(result),
+          })

yoker-0.1.0/src/yoker/tools.py

@@ -0,0 +1,26 @@
+"""Minimal tools for Yoker prototype."""
+
+from pathlib import Path
+
+
+def read(path: str) -> str:
+  """Read the content of a file.
+
+  Args:
+    path: The path to the file to read.
+
+  Returns:
+    The content of the file.
+  """
+  try:
+    return Path(path).read_text()
+  except FileNotFoundError:
+    return f"Error: File not found: {path}"
+  except Exception as e:
+    return f"Error reading file: {e}"
+
+
+# Tool registry - maps tool names to functions
+AVAILABLE_TOOLS = {
+  "read": read,
+}

yoker-0.1.0/src/yoker.egg-info/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: yoker
+Version: 0.1.0
+Summary: A Python agent harness with configurable tools and guardrails - one who yokes agents together
+Author-email: Christophe VG <contact@christophe.vg>
+License: MIT
+Project-URL: Homepage, https://github.com/christophevg/yoker
+Project-URL: Documentation, https://yoker.readthedocs.io/
+Project-URL: Repository, https://github.com/christophevg/yoker
+Project-URL: Issues, https://github.com/christophevg/yoker/issues
+Keywords: agent,llm,ollama,ai,harness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: ollama>=0.6.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
+Requires-Dist: myst-parser>=2.0.0; extra == "dev"
+Requires-Dist: tox>=4.0.0; extra == "dev"
+
+# Yoker
+
+A Python-based agent harness with configurable tools, guardrails, and Ollama backend integration.
+
+## Current Status
+
+**Minimal prototype available!** The basic chat loop with tool calling is working:
+
+```bash
+# Install (requires Python 3.10+)
+pip install -e .
+
+# Run interactive chat
+python -m yoker
+```
+
+The prototype includes:
+- Interactive chat loop with Ollama
+- Basic `read` tool for file reading
+- Streaming responses
+- Structured logging
+
+See [Quick Start](#quick-start) below for details.
+
+## Name
+
+**"yoker"** - One who yokes. A person or device that joins or attaches things together, specifically one who yokes oxen or links things together.
+
+From the agent noun of "yoke", which derives from PIE *\yeug-* meaning "to join" (same root as yoga, conjugate, junction).
+
+Pairs beautifully with "clitic" (both are joining tools - clitic joins words, yoker joins agents).
+
+See `docs/NAME.md` for full naming documentation.
+
+## Vision
+
+Create a lightweight, configurable agent harness that provides a structured environment for AI agents to operate within defined boundaries. The harness manages tool access, enforces guardrails, handles context persistence, and integrates with Ollama as the LLM backend.
+
+## Goals
+
+1. **Safety First**: Guardrails prevent agents from performing unintended operations
+2. **Configurability**: All tools, parameters, and limits configurable via TOML
+3. **Simplicity**: Specific tools instead of generic shell access
+4. **Transparency**: Clear logging and reporting of all agent actions
+5. **Extensibility**: Easy to add new tools while maintaining guardrails
+6. **Compatibility**: Agent definitions compatible with Claude Code format
+
+## Core Components
+
+### 1. Configuration System
+
+- **TOML configuration file**: Harness settings, tool guardrails, Ollama parameters
+- **Markdown agent definitions**: With YAML frontmatter (compatible with Claude Code)
+
+### 2. Tool System
+
+MVP tools (no generic Bash):
+
+| Tool | Purpose | Guardrails |
+|------|---------|------------|
+| List | Directory listing | Path restrictions, pattern filters |
+| Read | File reading | Path restrictions, size limits |
+| Write | File writing | Path restrictions, overwrite protection |
+| Update | File editing | Path restrictions, diff validation |
+| Search | Grep/glob-like | Path restrictions, pattern limits |
+| Agent | Spawn subagents | Recursion depth, tool subset |
+
+### 3. Context Manager
+
+Persists context for consecutive LLM calls:
+- Conversation history (JSONL format - append-friendly)
+- Agent state
+- Working memory
+- Per-session files in configurable location
+
+### 4. Ollama Integration
+
+- Assumes Ollama is running externally
+- All configurable parameters exposed
+- Model selection per agent possible
+
+### 5. Agent Definitions
+
+Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: researcher
+description: Research assistant
+tools: List, Read, Search
+---
+
+# Researcher Agent
+
+You are a research assistant...
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        Yoker                             │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │  Config     │  │  Context    │  │  Logging/       │  │
+│  │  Loader     │  │  Manager    │  │  Reporting      │  │
+│  │  (TOML)     │  │  (JSONL)    │  │                 │  │
+│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │
+│         │                │                  │           │
+│         ▼                ▼                  ▼           │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Tool Execution Layer                   ││
+│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌───────┐  ││
+│  │  │List │ │Read │ │Write│ │Update│ │Search│ │Agent  │  ││
+│  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └───────┘  ││
+│  └─────────────────────────────────────────────────────┘│
+│                          │                              │
+│                          ▼                              │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │              Ollama Backend Client                  ││
+│  │      (HTTP API, configurable parameters)            ││
+│  └─────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+```
+yoker/
+├── src/yoker/           # Main package
+├── tests/               # Test suite
+├── docs/               # Sphinx documentation
+├── examples/           # Example configurations
+├── analysis/           # Functional analysis
+├── pyproject.toml      # Package configuration
+└── README.md
+```
+
+## Quick Start
+
+### Minimal Prototype
+
+The current prototype provides a basic interactive chat with tool calling:
+
+```bash
+# Install
+pip install -e .
+
+# Run
+python -m yoker
+```
+
+Example session:
+```
+Yoker v0.1.0 - Using model: glm-5:cloud
+Type your message and press Enter. Press Ctrl+D to quit.
+
+> What's in the README.md file?
+
+I'll read the README.md file for you.
+
+[13:49:49] INFO yoker.agent - Tool call: read({'path': 'README.md'})
+[13:49:49] INFO yoker.agent - Tool result: # Yoker...
+
+The README.md file describes **Yoker**, a Python-based agent harness...
+
+> ^D
+Goodbye!
+```
+
+### Planned Full Usage
+
+```bash
+# Create config
+cat > yoker.toml << EOF
+[ollama]
+model = "llama3.2"
+base_url = "http://localhost:11434"
+
+[tools.list]
+allowed_paths = ["/workspace"]
+
+[tools.read]
+allowed_paths = ["/workspace"]
+max_size_kb = 100
+
+[tools.agent]
+max_recursion_depth = 3
+
+[agents]
+directory = "./agents"
+EOF
+
+# Create agent definition
+mkdir agents
+cat > agents/main.md << EOF
+---
+name: main
+description: Default assistant
+tools: List, Read, Write, Update, Search, Agent
+---
+
+You are a helpful assistant.
+EOF
+
+# Run harness (planned)
+yoker --config yoker.toml
+```
+
+## Documentation
+
+- Name documentation: `docs/NAME.md`
+- Functional analysis: `analysis/functional.md`
+- Interview notes: `analysis/interview.md`
+
+## Integration with Clitic
+
+Yoker provides the agent runtime, Clitic provides the TUI:
+
+- Build agents using Yoker APIs
+- Optionally add Clitic-based CLI interface
+- Deploy agents with or without UI (daemon mode)

yoker-0.1.0/src/yoker.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/yoker/__init__.py
+src/yoker/__main__.py
+src/yoker/agent.py
+src/yoker/py.typed
+src/yoker/tools.py
+src/yoker.egg-info/PKG-INFO
+src/yoker.egg-info/SOURCES.txt
+src/yoker.egg-info/dependency_links.txt
+src/yoker.egg-info/entry_points.txt
+src/yoker.egg-info/requires.txt
+src/yoker.egg-info/top_level.txt

yoker-0.1.0/src/yoker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yoker-0.1.0/src/yoker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yoker = yoker.__main__:main

yoker-0.1.0/src/yoker.egg-info/requires.txt

@@ -0,0 +1,21 @@
+httpx>=0.25.0
+ollama>=0.6.0
+rich>=14.0.0
+structlog>=23.0.0
+pyyaml>=6.0
+
+[:python_version < "3.11"]
+tomli>=2.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+pytest-asyncio>=0.21.0
+mypy>=1.0.0
+ruff>=0.1.0
+build>=1.0.0
+twine>=5.0.0
+sphinx>=7.0.0
+sphinx-rtd-theme>=2.0.0
+myst-parser>=2.0.0
+tox>=4.0.0

yoker-0.1.0/src/yoker.egg-info/top_level.txt

@@ -0,0 +1 @@
+yoker