kimss-forge 0.1.0__tar.gz

kimss_forge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kimss
+
+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.

kimss_forge-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: kimss-forge
+Version: 0.1.0
+Summary: Kimss Forge — open-source agent harness: run agents with any model for free; one line to connect Kimss governance when you need production control.
+License-Expression: MIT
+Project-URL: Homepage, https://kimss.ai/open-source
+Project-URL: Documentation, https://kimss.ai/docs/agent_harness
+Project-URL: Repository, https://github.com/kimss-ai/kimss-forge
+Project-URL: Issues, https://github.com/kimss-ai/kimss-forge/issues
+Project-URL: Changelog, https://github.com/kimss-ai/kimss-forge/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# Kimss Forge — open-source agent harness
+
+[![PyPI](https://img.shields.io/pypi/v/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+
+**Build and run agents with any model — free, forever. Connect Kimss when production needs governance.**
+
+**Kimss Forge** (`kimss-forge` on PyPI, `import kimss_forge`) is a small MIT-licensed harness: a local multi-turn tool loop that talks to any OpenAI-compatible endpoint (OpenAI, Azure/Foundry, Anthropic-compatible proxies, Ollama, vLLM). **No Kimss account required** to develop and test.
+
+When your security team needs identity, kill switch, budgets, and audit for production, flip one argument — `gateway="kimss"` — and traffic routes through the [Kimss AI Gateway](https://kimss.ai).
+
+```python
+from kimss_forge import Agent, tool
+
+@tool
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers."""
+    return a * b
+
+# Local — your provider key only
+agent = Agent(model="gpt-4o-mini", tools=[multiply])
+print(agent.run("What is 6 times 7?"))
+
+# Production — one line to the Kimss control plane
+agent = Agent(
+    model="custom:your-vaulted-model",
+    tools=[multiply],
+    gateway="kimss",
+    agent_id="ops_bot",
+    workspace_key="kimss_...",
+)
+```
+
+## Naming (unified)
+
+| Surface | Name |
+|---------|------|
+| Product | **Kimss Forge** |
+| GitHub | [kimss-ai/kimss-forge](https://github.com/kimss-ai/kimss-forge) |
+| PyPI | `kimss-forge` |
+| Import | `import kimss_forge` / `from kimss_forge import Agent` |
+| Monorepo SSOT | `kimssApi/kimss-forge/` |
+
+## Why this exists
+
+| Layer | Cost | What you get |
+|-------|------|----------------|
+| **Forge (this package)** | Free / MIT | Run agents, tools, MCP; any model endpoint |
+| **Kimss Developer gateway** | Free tier (25k governed requests/mo) | Identity, audit trail, **kill switch** |
+| **Kimss Production+** | Paid | Authority Boundary, RBAC, Threat Intercepts, PII scrub |
+| **Kimss Scale / Enterprise** | Paid | SSO, SCIM, retention, schema isolation |
+
+Developers adopt Forge to ship faster. CISOs purchase the control plane when production governance is mandatory — without rewriting the agent.
+
+## Install
+
+```bash
+pip install kimss-forge
+# optional MCP tools:
+pip install 'kimss-forge[mcp]'
+```
+
+## Local (zero Kimss)
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional: OPENAI_BASE_URL=https://your-endpoint/v1
+python examples/01_local_agent.py
+```
+
+## Production via Kimss (one line)
+
+1. Sign up at [kimss.ai](https://kimss.ai/app/signup) (Developer tier is free).
+2. Vault your provider under **Connected Infrastructure**.
+3. Mint a `kimss_...` workspace key.
+4. Set `gateway="kimss"`, `agent_id=...`, and the workspace key.
+
+```python
+Agent(
+    model="custom:your-vaulted-model",
+    gateway="kimss",          # → https://api.kimss.ai/v1
+    agent_id="fleet_reporter",
+    workspace_key="kimss_...",
+)
+```
+
+Every call sends `X-Kimss-Agent-Id`. Disable that agent in the Kimss UI and subsequent hops return **403** (kill switch). Paid tiers add Authority Boundary, Team & Access, SCIM/SSO, and more — see [pricing](https://kimss.ai/pricing).
+
+## Examples
+
+| Script | What it shows |
+|--------|----------------|
+| `examples/01_local_agent.py` | Local chat, no tools |
+| `examples/02_tools.py` | `@tool` functions |
+| `examples/03_mcp.py` | MCP stdio tools (`[mcp]` extra) |
+| `examples/04_production_kimss.py` | Gateway connect |
+
+## Design decision
+
+See [ADR.md](ADR.md) (why Forge is separate from the proprietary Hermis server loop, and why kill switch stays free).
+
+## Related
+
+- Control-plane client (register agents, report usage): [`kimss`](https://pypi.org/project/kimss/) / [kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk)
+- Gateway quickstart: [kimss-python-quickstart](https://github.com/kimss-ai/kimss-python-quickstart)
+- Docs: [Agent harness](https://kimss.ai/docs/agent_harness) · [Open source](https://kimss.ai/open-source)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kimss_forge-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Kimss Forge — open-source agent harness
+
+[![PyPI](https://img.shields.io/pypi/v/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+
+**Build and run agents with any model — free, forever. Connect Kimss when production needs governance.**
+
+**Kimss Forge** (`kimss-forge` on PyPI, `import kimss_forge`) is a small MIT-licensed harness: a local multi-turn tool loop that talks to any OpenAI-compatible endpoint (OpenAI, Azure/Foundry, Anthropic-compatible proxies, Ollama, vLLM). **No Kimss account required** to develop and test.
+
+When your security team needs identity, kill switch, budgets, and audit for production, flip one argument — `gateway="kimss"` — and traffic routes through the [Kimss AI Gateway](https://kimss.ai).
+
+```python
+from kimss_forge import Agent, tool
+
+@tool
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers."""
+    return a * b
+
+# Local — your provider key only
+agent = Agent(model="gpt-4o-mini", tools=[multiply])
+print(agent.run("What is 6 times 7?"))
+
+# Production — one line to the Kimss control plane
+agent = Agent(
+    model="custom:your-vaulted-model",
+    tools=[multiply],
+    gateway="kimss",
+    agent_id="ops_bot",
+    workspace_key="kimss_...",
+)
+```
+
+## Naming (unified)
+
+| Surface | Name |
+|---------|------|
+| Product | **Kimss Forge** |
+| GitHub | [kimss-ai/kimss-forge](https://github.com/kimss-ai/kimss-forge) |
+| PyPI | `kimss-forge` |
+| Import | `import kimss_forge` / `from kimss_forge import Agent` |
+| Monorepo SSOT | `kimssApi/kimss-forge/` |
+
+## Why this exists
+
+| Layer | Cost | What you get |
+|-------|------|----------------|
+| **Forge (this package)** | Free / MIT | Run agents, tools, MCP; any model endpoint |
+| **Kimss Developer gateway** | Free tier (25k governed requests/mo) | Identity, audit trail, **kill switch** |
+| **Kimss Production+** | Paid | Authority Boundary, RBAC, Threat Intercepts, PII scrub |
+| **Kimss Scale / Enterprise** | Paid | SSO, SCIM, retention, schema isolation |
+
+Developers adopt Forge to ship faster. CISOs purchase the control plane when production governance is mandatory — without rewriting the agent.
+
+## Install
+
+```bash
+pip install kimss-forge
+# optional MCP tools:
+pip install 'kimss-forge[mcp]'
+```
+
+## Local (zero Kimss)
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional: OPENAI_BASE_URL=https://your-endpoint/v1
+python examples/01_local_agent.py
+```
+
+## Production via Kimss (one line)
+
+1. Sign up at [kimss.ai](https://kimss.ai/app/signup) (Developer tier is free).
+2. Vault your provider under **Connected Infrastructure**.
+3. Mint a `kimss_...` workspace key.
+4. Set `gateway="kimss"`, `agent_id=...`, and the workspace key.
+
+```python
+Agent(
+    model="custom:your-vaulted-model",
+    gateway="kimss",          # → https://api.kimss.ai/v1
+    agent_id="fleet_reporter",
+    workspace_key="kimss_...",
+)
+```
+
+Every call sends `X-Kimss-Agent-Id`. Disable that agent in the Kimss UI and subsequent hops return **403** (kill switch). Paid tiers add Authority Boundary, Team & Access, SCIM/SSO, and more — see [pricing](https://kimss.ai/pricing).
+
+## Examples
+
+| Script | What it shows |
+|--------|----------------|
+| `examples/01_local_agent.py` | Local chat, no tools |
+| `examples/02_tools.py` | `@tool` functions |
+| `examples/03_mcp.py` | MCP stdio tools (`[mcp]` extra) |
+| `examples/04_production_kimss.py` | Gateway connect |
+
+## Design decision
+
+See [ADR.md](ADR.md) (why Forge is separate from the proprietary Hermis server loop, and why kill switch stays free).
+
+## Related
+
+- Control-plane client (register agents, report usage): [`kimss`](https://pypi.org/project/kimss/) / [kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk)
+- Gateway quickstart: [kimss-python-quickstart](https://github.com/kimss-ai/kimss-python-quickstart)
+- Docs: [Agent harness](https://kimss.ai/docs/agent_harness) · [Open source](https://kimss.ai/open-source)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kimss_forge-0.1.0/kimss_forge/__init__.py

@@ -0,0 +1,20 @@
+"""kimss_forge — Kimss Forge open-source agent harness (MIT).
+
+Run agents against any OpenAI-compatible endpoint with zero Kimss account.
+Connect the Kimss AI Gateway with one line when you need production governance.
+"""
+
+from .agent import Agent, AgentResult
+from .gateway import KIMSS_GATEWAY_BASE_URL, gateway_headers
+from .tools import Tool, tool
+
+__version__ = "0.1.0"
+__all__ = [
+    "Agent",
+    "AgentResult",
+    "Tool",
+    "tool",
+    "gateway_headers",
+    "KIMSS_GATEWAY_BASE_URL",
+    "__version__",
+]

kimss_forge-0.1.0/kimss_forge/agent.py

@@ -0,0 +1,111 @@
+"""High-level Agent API — local by default, Kimss gateway with one line."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .client import ChatClient
+from .gateway import apply_kimss_gateway
+from .loop import AgentResult, run_loop
+from .tools import Tool, coerce_tools
+
+ToolLike = Union[Tool, Any]
+
+
+class Agent:
+    """
+    Standalone agent harness.
+
+    **Local (free, no Kimss account)::**
+
+        agent = Agent(model="gpt-4o-mini", instructions="Be brief.", tools=[...])
+        print(agent.run("Hello"))
+
+    **Production via Kimss gateway (one line)::**
+
+        agent = Agent(
+            model="custom:your-vaulted-model",
+            instructions="Be brief.",
+            gateway="kimss",
+            agent_id="my_agent",
+            workspace_key="kimss_...",
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        instructions: str = "You are a helpful assistant.",
+        tools: Optional[Sequence[ToolLike]] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        gateway: Optional[str] = None,
+        workspace_key: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        max_hops: int = 8,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        timeout: float = 120.0,
+    ) -> None:
+        self.model = (model or "").strip()
+        if not self.model:
+            raise ValueError("model is required")
+        self.instructions = instructions or ""
+        self.tools = coerce_tools(list(tools) if tools else [])
+        self.max_hops = max_hops
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+        gw = (gateway or "").strip().lower()
+        extra_headers: Dict[str, str] = {}
+        resolved_key = api_key
+        resolved_base = base_url
+
+        if gw in ("kimss", "kimss-ai", "true"):
+            resolved_base, resolved_key, extra_headers = apply_kimss_gateway(
+                workspace_key=workspace_key or api_key,
+                agent_id=agent_id,
+                agent_name=agent_name,
+                base_url=base_url,
+            )
+        elif gw:
+            raise ValueError(f"Unsupported gateway={gateway!r}; use None or 'kimss'")
+
+        if resolved_key is None and not gw:
+            resolved_key = os.environ.get("OPENAI_API_KEY")
+        if resolved_base is None and not gw:
+            resolved_base = os.environ.get("OPENAI_BASE_URL")
+
+        self.agent_id = (agent_id or "").strip() or None
+        self._client = ChatClient(
+            api_key=resolved_key,
+            base_url=resolved_base,
+            default_headers=extra_headers,
+            timeout=timeout,
+        )
+
+    def run(
+        self,
+        user_text: str,
+        *,
+        messages: Optional[List[Dict[str, Any]]] = None,
+    ) -> AgentResult:
+        """Run one user turn (multi-hop tool loop). Returns AgentResult (str-compatible)."""
+        history: List[Dict[str, Any]] = []
+        if self.instructions.strip():
+            history.append({"role": "system", "content": self.instructions})
+        if messages:
+            history.extend(messages)
+        history.append({"role": "user", "content": user_text})
+        return run_loop(
+            client=self._client,
+            model=self.model,
+            messages=history,
+            tools=self.tools,
+            max_hops=self.max_hops,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+        )

kimss_forge-0.1.0/kimss_forge/client.py

@@ -0,0 +1,81 @@
+"""Provider-agnostic OpenAI-compatible chat completions client."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1"
+
+
+class CompletionError(RuntimeError):
+    """Raised when the model endpoint returns an error."""
+
+    def __init__(self, status_code: int, body: str):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"chat completions failed ({status_code}): {body[:400]}")
+
+
+class ChatClient:
+    """Minimal OpenAI-compatible `/chat/completions` client (requests only)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+        timeout: float = 120.0,
+    ) -> None:
+        self.api_key = (api_key or os.environ.get("OPENAI_API_KEY") or "").strip()
+        raw_base = (
+            base_url
+            or os.environ.get("OPENAI_BASE_URL")
+            or DEFAULT_OPENAI_BASE_URL
+        ).rstrip("/")
+        self.base_url = raw_base
+        self.default_headers = dict(default_headers or {})
+        self.timeout = timeout
+
+    def chat_completions(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        if not self.api_key:
+            raise ValueError(
+                "API key required: pass api_key=... or set OPENAI_API_KEY "
+                "(or use gateway='kimss' with a Kimss workspace key)"
+            )
+        url = f"{self.base_url}/chat/completions"
+        payload: Dict[str, Any] = {"model": model, "messages": messages}
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = "auto"
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        if temperature is not None:
+            payload["temperature"] = temperature
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            **self.default_headers,
+            **(extra_headers or {}),
+        }
+        resp = requests.post(url, headers=headers, json=payload, timeout=self.timeout)
+        if resp.status_code >= 400:
+            raise CompletionError(resp.status_code, resp.text)
+        try:
+            return resp.json()
+        except json.JSONDecodeError as exc:
+            raise CompletionError(resp.status_code, resp.text) from exc

kimss_forge-0.1.0/kimss_forge/gateway.py

@@ -0,0 +1,68 @@
+"""Kimss AI Gateway connect helpers (one-line production upgrade)."""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional
+
+KIMSS_GATEWAY_BASE_URL = "https://api.kimss.ai/v1"
+KIMSS_GATEWAY_HOST = "https://api.kimss.ai"
+
+# Header names match kimss_sdk / Invisible Proxy conventions.
+HEADER_AGENT_ID = "X-Kimss-Agent-Id"
+HEADER_AGENT_NAME = "X-Kimss-Agent-Name"
+
+
+def gateway_headers(
+    *,
+    agent_id: str,
+    agent_name: Optional[str] = None,
+) -> Dict[str, str]:
+    """Return attribution headers for traffic routed through the Kimss gateway."""
+    aid = (agent_id or "").strip()
+    if not aid:
+        raise ValueError("agent_id is required when using the Kimss gateway")
+    headers: Dict[str, str] = {HEADER_AGENT_ID: aid}
+    name = (agent_name or "").strip()
+    if name:
+        headers[HEADER_AGENT_NAME] = name
+    return headers
+
+
+def resolve_kimss_workspace_key(explicit: Optional[str] = None) -> str:
+    """Resolve workspace key from argument or env (KIMSS_API_KEY / KIMSS_WORKSPACE_KEY)."""
+    key = (explicit or "").strip()
+    if key:
+        return key
+    for env_name in ("KIMSS_API_KEY", "KIMSS_WORKSPACE_KEY"):
+        val = (os.environ.get(env_name) or "").strip()
+        if val:
+            return val
+    raise ValueError(
+        "Kimss workspace key required: pass workspace_key=... or set "
+        "KIMSS_API_KEY / KIMSS_WORKSPACE_KEY"
+    )
+
+
+def apply_kimss_gateway(
+    *,
+    workspace_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> tuple[str, str, Dict[str, str]]:
+    """
+    Resolve base_url, api_key, and extra headers for Kimss gateway mode.
+
+    Returns (base_url, api_key, extra_headers).
+    """
+    key = resolve_kimss_workspace_key(workspace_key)
+    aid = (agent_id or os.environ.get("KIMSS_AGENT_ID") or "").strip()
+    if not aid:
+        raise ValueError(
+            "agent_id is required for gateway='kimss' "
+            "(pass agent_id=... or set KIMSS_AGENT_ID)"
+        )
+    url = (base_url or KIMSS_GATEWAY_BASE_URL).rstrip("/")
+    headers = gateway_headers(agent_id=aid, agent_name=agent_name)
+    return url, key, headers

kimss_forge-0.1.0/kimss_forge/loop.py

@@ -0,0 +1,148 @@
+"""Local multi-turn agent loop (model → tools → model). No Kimss governance logic."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .client import ChatClient
+from .tools import Tool
+
+
+DEFAULT_MAX_HOPS = 8
+
+
+@dataclass
+class AgentResult:
+    """Outcome of a single ``Agent.run`` call."""
+
+    text: str
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    hops: int = 0
+    tool_calls: List[Dict[str, Any]] = field(default_factory=list)
+    raw: Optional[Dict[str, Any]] = None
+
+    def __str__(self) -> str:
+        return self.text
+
+
+def _assistant_message_from_choice(choice: Dict[str, Any]) -> Dict[str, Any]:
+    msg = choice.get("message") or {}
+    out: Dict[str, Any] = {"role": "assistant"}
+    content = msg.get("content")
+    if content is not None:
+        out["content"] = content
+    tool_calls = msg.get("tool_calls")
+    if tool_calls:
+        out["tool_calls"] = tool_calls
+    return out
+
+
+def _stringify_content(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    try:
+        return json.dumps(content, default=str)
+    except TypeError:
+        return str(content)
+
+
+def run_loop(
+    *,
+    client: ChatClient,
+    model: str,
+    messages: List[Dict[str, Any]],
+    tools: List[Tool],
+    max_hops: int = DEFAULT_MAX_HOPS,
+    max_tokens: Optional[int] = None,
+    temperature: Optional[float] = None,
+) -> AgentResult:
+    """
+    Run a multi-turn tool loop until the model returns text or max_hops is hit.
+
+    Pure local orchestration — no Authority Boundary, vault, or plan checks.
+    """
+    tool_map = {t.name: t for t in tools}
+    openai_tools = [t.openai_schema() for t in tools] or None
+    history = list(messages)
+    recorded_calls: List[Dict[str, Any]] = []
+    last_raw: Optional[Dict[str, Any]] = None
+    hops = 0
+
+    for hop in range(max(1, max_hops)):
+        hops = hop + 1
+        raw = client.chat_completions(
+            model=model,
+            messages=history,
+            tools=openai_tools,
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        last_raw = raw
+        choices = raw.get("choices") or []
+        if not choices:
+            return AgentResult(
+                text="",
+                messages=history,
+                hops=hops,
+                tool_calls=recorded_calls,
+                raw=raw,
+            )
+        assistant = _assistant_message_from_choice(choices[0])
+        history.append(assistant)
+        tool_calls = assistant.get("tool_calls") or []
+        if not tool_calls:
+            return AgentResult(
+                text=_stringify_content(assistant.get("content")),
+                messages=history,
+                hops=hops,
+                tool_calls=recorded_calls,
+                raw=raw,
+            )
+
+        for tc in tool_calls:
+            fn = (tc.get("function") or {}) if isinstance(tc, dict) else {}
+            name = str(fn.get("name") or "").strip()
+            args_raw = fn.get("arguments")
+            call_id = str(tc.get("id") or name or "tool")
+            recorded_calls.append({"id": call_id, "name": name, "arguments": args_raw})
+            if name not in tool_map:
+                result_text = json.dumps({"error": f"unknown tool: {name}"})
+            else:
+                try:
+                    result_text = tool_map[name].call(args_raw)
+                except Exception as exc:  # noqa: BLE001 — surface tool errors to the model
+                    result_text = json.dumps({"error": str(exc)})
+            history.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call_id,
+                    "content": result_text,
+                }
+            )
+
+    # Max hops exhausted after tool rounds — ask once more without tools for a final answer.
+    raw = client.chat_completions(
+        model=model,
+        messages=history,
+        tools=None,
+        max_tokens=max_tokens,
+        temperature=temperature,
+    )
+    last_raw = raw
+    choices = raw.get("choices") or []
+    text = ""
+    if choices:
+        assistant = _assistant_message_from_choice(choices[0])
+        history.append(assistant)
+        text = _stringify_content(assistant.get("content"))
+    return AgentResult(
+        text=text,
+        messages=history,
+        hops=hops,
+        tool_calls=recorded_calls,
+        raw=last_raw,
+    )

kimss_forge-0.1.0/kimss_forge/mcp.py

@@ -0,0 +1,94 @@
+"""Optional MCP tool loading (install with ``pip install 'kimss-forge[mcp]'``)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Dict, List, Optional
+
+from .tools import Tool
+
+
+def mcp_tools_from_stdio(
+    command: str,
+    args: Optional[List[str]] = None,
+    *,
+    env: Optional[Dict[str, str]] = None,
+) -> List[Tool]:
+    """
+    Connect to an MCP server over stdio and wrap its tools as harness Tools.
+
+    Requires the optional ``mcp`` extra. Tools execute via a fresh short-lived
+    session per call (simple; suitable for demos and scripts).
+    """
+    try:
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+    except ImportError as exc:
+        raise ImportError(
+            "MCP support requires: pip install 'kimss-forge[mcp]'"
+        ) from exc
+
+    server = StdioServerParameters(command=command, args=args or [], env=env)
+
+    async def _list() -> List[Dict[str, Any]]:
+        async with stdio_client(server) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                listed = await session.list_tools()
+                return [
+                    {
+                        "name": t.name,
+                        "description": (t.description or t.name),
+                        "inputSchema": getattr(t, "inputSchema", None) or {},
+                    }
+                    for t in (listed.tools or [])
+                ]
+
+    specs = asyncio.run(_list())
+    out: List[Tool] = []
+
+    for spec in specs:
+        name = str(spec["name"])
+        description = str(spec["description"])
+        parameters = spec.get("inputSchema") or {
+            "type": "object",
+            "properties": {},
+        }
+
+        def _make_fn(tool_name: str):
+            def _fn(**kwargs: Any) -> str:
+                async def _call() -> str:
+                    async with stdio_client(server) as (read, write):
+                        async with ClientSession(read, write) as session:
+                            await session.initialize()
+                            result = await session.call_tool(tool_name, arguments=kwargs)
+                            parts = []
+                            for block in getattr(result, "content", None) or []:
+                                text = getattr(block, "text", None)
+                                if text is not None:
+                                    parts.append(text)
+                                else:
+                                    parts.append(str(block))
+                            return "\n".join(parts) if parts else json.dumps(
+                                {"ok": True}, default=str
+                            )
+
+                return asyncio.run(_call())
+
+            _fn.__name__ = tool_name
+            _fn.__doc__ = description
+            return _fn
+
+        out.append(
+            Tool(
+                name=name,
+                description=description,
+                parameters=parameters if isinstance(parameters, dict) else {
+                    "type": "object",
+                    "properties": {},
+                },
+                fn=_make_fn(name),
+            )
+        )
+    return out

kimss_forge-0.1.0/kimss_forge/tools.py

@@ -0,0 +1,131 @@
+"""Tool registration for the local agent loop."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, get_args, get_origin, get_type_hints
+
+
+def _json_type(annotation: Any) -> str:
+    origin = get_origin(annotation)
+    if origin is list or annotation is list:
+        return "array"
+    if origin is dict or annotation is dict:
+        return "object"
+    if annotation is bool:
+        return "boolean"
+    if annotation is int:
+        return "integer"
+    if annotation is float:
+        return "number"
+    if annotation is str or annotation is Any or annotation is inspect.Parameter.empty:
+        return "string"
+    # Optional[T] / Union
+    args = get_args(annotation)
+    if args:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _json_type(non_none[0])
+    return "string"
+
+
+@dataclass
+class Tool:
+    """A callable tool with an OpenAI-compatible function schema."""
+
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+    fn: Callable[..., Any]
+
+    def openai_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def call(self, arguments: Dict[str, Any] | str | None) -> str:
+        if arguments is None:
+            args: Dict[str, Any] = {}
+        elif isinstance(arguments, str):
+            try:
+                args = json.loads(arguments) if arguments.strip() else {}
+            except json.JSONDecodeError:
+                args = {"raw": arguments}
+        else:
+            args = dict(arguments)
+        result = self.fn(**args) if args else self.fn()
+        if result is None:
+            return ""
+        if isinstance(result, str):
+            return result
+        try:
+            return json.dumps(result, default=str)
+        except TypeError:
+            return str(result)
+
+
+def tool(
+    fn: Optional[Callable[..., Any]] = None,
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+) -> Any:
+    """Decorator (or wrapper) that turns a Python function into a Tool."""
+
+    def _wrap(f: Callable[..., Any]) -> Tool:
+        hints = {}
+        try:
+            hints = get_type_hints(f)
+        except Exception:
+            hints = getattr(f, "__annotations__", {}) or {}
+        sig = inspect.signature(f)
+        properties: Dict[str, Any] = {}
+        required: List[str] = []
+        for pname, param in sig.parameters.items():
+            if pname in ("self", "cls"):
+                continue
+            ann = hints.get(pname, param.annotation)
+            properties[pname] = {
+                "type": _json_type(ann),
+                "description": pname.replace("_", " "),
+            }
+            if param.default is inspect.Parameter.empty:
+                required.append(pname)
+        schema = {
+            "type": "object",
+            "properties": properties,
+            "additionalProperties": False,
+        }
+        if required:
+            schema["required"] = required
+        doc = (description or inspect.getdoc(f) or f.__name__).strip()
+        return Tool(
+            name=(name or f.__name__).strip(),
+            description=doc.split("\n")[0].strip(),
+            parameters=schema,
+            fn=f,
+        )
+
+    if fn is not None:
+        return _wrap(fn)
+    return _wrap
+
+
+def coerce_tools(tools: Optional[List[Any]]) -> List[Tool]:
+    """Normalize a list of Tool instances or @tool-decorated callables."""
+    out: List[Tool] = []
+    for t in tools or []:
+        if isinstance(t, Tool):
+            out.append(t)
+        elif callable(t):
+            out.append(tool(t))
+        else:
+            raise TypeError(f"Unsupported tool type: {type(t)!r}")
+    return out

kimss_forge-0.1.0/kimss_forge.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: kimss-forge
+Version: 0.1.0
+Summary: Kimss Forge — open-source agent harness: run agents with any model for free; one line to connect Kimss governance when you need production control.
+License-Expression: MIT
+Project-URL: Homepage, https://kimss.ai/open-source
+Project-URL: Documentation, https://kimss.ai/docs/agent_harness
+Project-URL: Repository, https://github.com/kimss-ai/kimss-forge
+Project-URL: Issues, https://github.com/kimss-ai/kimss-forge/issues
+Project-URL: Changelog, https://github.com/kimss-ai/kimss-forge/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# Kimss Forge — open-source agent harness
+
+[![PyPI](https://img.shields.io/pypi/v/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/kimss-forge.svg)](https://pypi.org/project/kimss-forge/)
+
+**Build and run agents with any model — free, forever. Connect Kimss when production needs governance.**
+
+**Kimss Forge** (`kimss-forge` on PyPI, `import kimss_forge`) is a small MIT-licensed harness: a local multi-turn tool loop that talks to any OpenAI-compatible endpoint (OpenAI, Azure/Foundry, Anthropic-compatible proxies, Ollama, vLLM). **No Kimss account required** to develop and test.
+
+When your security team needs identity, kill switch, budgets, and audit for production, flip one argument — `gateway="kimss"` — and traffic routes through the [Kimss AI Gateway](https://kimss.ai).
+
+```python
+from kimss_forge import Agent, tool
+
+@tool
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers."""
+    return a * b
+
+# Local — your provider key only
+agent = Agent(model="gpt-4o-mini", tools=[multiply])
+print(agent.run("What is 6 times 7?"))
+
+# Production — one line to the Kimss control plane
+agent = Agent(
+    model="custom:your-vaulted-model",
+    tools=[multiply],
+    gateway="kimss",
+    agent_id="ops_bot",
+    workspace_key="kimss_...",
+)
+```
+
+## Naming (unified)
+
+| Surface | Name |
+|---------|------|
+| Product | **Kimss Forge** |
+| GitHub | [kimss-ai/kimss-forge](https://github.com/kimss-ai/kimss-forge) |
+| PyPI | `kimss-forge` |
+| Import | `import kimss_forge` / `from kimss_forge import Agent` |
+| Monorepo SSOT | `kimssApi/kimss-forge/` |
+
+## Why this exists
+
+| Layer | Cost | What you get |
+|-------|------|----------------|
+| **Forge (this package)** | Free / MIT | Run agents, tools, MCP; any model endpoint |
+| **Kimss Developer gateway** | Free tier (25k governed requests/mo) | Identity, audit trail, **kill switch** |
+| **Kimss Production+** | Paid | Authority Boundary, RBAC, Threat Intercepts, PII scrub |
+| **Kimss Scale / Enterprise** | Paid | SSO, SCIM, retention, schema isolation |
+
+Developers adopt Forge to ship faster. CISOs purchase the control plane when production governance is mandatory — without rewriting the agent.
+
+## Install
+
+```bash
+pip install kimss-forge
+# optional MCP tools:
+pip install 'kimss-forge[mcp]'
+```
+
+## Local (zero Kimss)
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional: OPENAI_BASE_URL=https://your-endpoint/v1
+python examples/01_local_agent.py
+```
+
+## Production via Kimss (one line)
+
+1. Sign up at [kimss.ai](https://kimss.ai/app/signup) (Developer tier is free).
+2. Vault your provider under **Connected Infrastructure**.
+3. Mint a `kimss_...` workspace key.
+4. Set `gateway="kimss"`, `agent_id=...`, and the workspace key.
+
+```python
+Agent(
+    model="custom:your-vaulted-model",
+    gateway="kimss",          # → https://api.kimss.ai/v1
+    agent_id="fleet_reporter",
+    workspace_key="kimss_...",
+)
+```
+
+Every call sends `X-Kimss-Agent-Id`. Disable that agent in the Kimss UI and subsequent hops return **403** (kill switch). Paid tiers add Authority Boundary, Team & Access, SCIM/SSO, and more — see [pricing](https://kimss.ai/pricing).
+
+## Examples
+
+| Script | What it shows |
+|--------|----------------|
+| `examples/01_local_agent.py` | Local chat, no tools |
+| `examples/02_tools.py` | `@tool` functions |
+| `examples/03_mcp.py` | MCP stdio tools (`[mcp]` extra) |
+| `examples/04_production_kimss.py` | Gateway connect |
+
+## Design decision
+
+See [ADR.md](ADR.md) (why Forge is separate from the proprietary Hermis server loop, and why kill switch stays free).
+
+## Related
+
+- Control-plane client (register agents, report usage): [`kimss`](https://pypi.org/project/kimss/) / [kimss-python-sdk](https://github.com/kimss-ai/kimss-python-sdk)
+- Gateway quickstart: [kimss-python-quickstart](https://github.com/kimss-ai/kimss-python-quickstart)
+- Docs: [Agent harness](https://kimss.ai/docs/agent_harness) · [Open source](https://kimss.ai/open-source)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

kimss_forge-0.1.0/kimss_forge.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+kimss_forge/__init__.py
+kimss_forge/agent.py
+kimss_forge/client.py
+kimss_forge/gateway.py
+kimss_forge/loop.py
+kimss_forge/mcp.py
+kimss_forge/tools.py
+kimss_forge.egg-info/PKG-INFO
+kimss_forge.egg-info/SOURCES.txt
+kimss_forge.egg-info/dependency_links.txt
+kimss_forge.egg-info/requires.txt
+kimss_forge.egg-info/top_level.txt
+tests/test_agent.py

kimss_forge-0.1.0/kimss_forge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kimss_forge-0.1.0/kimss_forge.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.28
+
+[dev]
+pytest>=7
+responses>=0.25
+ruff>=0.4
+
+[mcp]
+mcp>=1.0

kimss_forge-0.1.0/kimss_forge.egg-info/top_level.txt

@@ -0,0 +1 @@
+kimss_forge

kimss_forge-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kimss-forge"
+version = "0.1.0"
+description = "Kimss Forge — open-source agent harness: run agents with any model for free; one line to connect Kimss governance when you need production control."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "requests>=2.28",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://kimss.ai/open-source"
+Documentation = "https://kimss.ai/docs/agent_harness"
+Repository = "https://github.com/kimss-ai/kimss-forge"
+Issues = "https://github.com/kimss-ai/kimss-forge/issues"
+Changelog = "https://github.com/kimss-ai/kimss-forge/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "responses>=0.25",
+    "ruff>=0.4",
+]
+mcp = [
+    "mcp>=1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["kimss_forge*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

kimss_forge-0.1.0/setup.cfg

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

kimss_forge-0.1.0/tests/test_agent.py

@@ -0,0 +1,147 @@
+"""Unit tests for kimss-forge (no live network)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import responses
+
+from kimss_forge import Agent, gateway_headers, tool
+from kimss_forge.gateway import apply_kimss_gateway
+from kimss_forge.tools import coerce_tools
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+
+def test_tool_schema():
+    assert add.name == "add"
+    assert "a" in add.parameters["properties"]
+    assert add.call({"a": 2, "b": 3}) == "5"
+
+
+def test_gateway_headers_require_agent_id():
+    with pytest.raises(ValueError):
+        gateway_headers(agent_id="")
+    h = gateway_headers(agent_id="ops_bot", agent_name="Ops")
+    assert h["X-Kimss-Agent-Id"] == "ops_bot"
+    assert h["X-Kimss-Agent-Name"] == "Ops"
+
+
+def test_apply_kimss_gateway(monkeypatch):
+    monkeypatch.delenv("KIMSS_API_KEY", raising=False)
+    monkeypatch.delenv("KIMSS_WORKSPACE_KEY", raising=False)
+    url, key, headers = apply_kimss_gateway(
+        workspace_key="kimss_test",
+        agent_id="agent_1",
+    )
+    assert url.endswith("/v1")
+    assert key == "kimss_test"
+    assert headers["X-Kimss-Agent-Id"] == "agent_1"
+
+
+@responses.activate
+def test_agent_run_text_only():
+    responses.add(
+        responses.POST,
+        "https://api.openai.com/v1/chat/completions",
+        json={
+            "choices": [
+                {"message": {"role": "assistant", "content": "hello there"}}
+            ]
+        },
+        status=200,
+    )
+    agent = Agent(
+        model="gpt-4o-mini",
+        instructions="Be brief.",
+        api_key="sk-test",
+        base_url="https://api.openai.com/v1",
+    )
+    result = agent.run("Hi")
+    assert str(result) == "hello there"
+    assert result.hops == 1
+
+
+@responses.activate
+def test_agent_tool_loop():
+    # First response: tool call
+    responses.add(
+        responses.POST,
+        "https://api.openai.com/v1/chat/completions",
+        json={
+            "choices": [
+                {
+                    "message": {
+                        "role": "assistant",
+                        "content": None,
+                        "tool_calls": [
+                            {
+                                "id": "call_1",
+                                "type": "function",
+                                "function": {
+                                    "name": "add",
+                                    "arguments": json.dumps({"a": 2, "b": 40}),
+                                },
+                            }
+                        ],
+                    }
+                }
+            ]
+        },
+        status=200,
+    )
+    # Second response: final text
+    responses.add(
+        responses.POST,
+        "https://api.openai.com/v1/chat/completions",
+        json={
+            "choices": [
+                {"message": {"role": "assistant", "content": "The sum is 42"}}
+            ]
+        },
+        status=200,
+    )
+    agent = Agent(
+        model="gpt-4o-mini",
+        tools=[add],
+        api_key="sk-test",
+        base_url="https://api.openai.com/v1",
+    )
+    result = agent.run("What is 2+40?")
+    assert "42" in result.text
+    assert result.tool_calls[0]["name"] == "add"
+
+
+@responses.activate
+def test_agent_kimss_gateway_headers():
+    def _check(request):
+        assert request.headers.get("X-Kimss-Agent-Id") == "fleet_bot"
+        assert request.headers.get("Authorization") == "Bearer kimss_abc"
+        body = {
+            "choices": [{"message": {"role": "assistant", "content": "ok"}}]
+        }
+        return (200, {"Content-Type": "application/json"}, json.dumps(body))
+
+    responses.add_callback(
+        responses.POST,
+        "https://api.kimss.ai/v1/chat/completions",
+        callback=_check,
+    )
+    agent = Agent(
+        model="custom:demo",
+        gateway="kimss",
+        workspace_key="kimss_abc",
+        agent_id="fleet_bot",
+    )
+    assert str(agent.run("ping")) == "ok"
+
+
+def test_coerce_tools():
+    tools = coerce_tools([add])
+    assert len(tools) == 1
+    assert tools[0].name == "add"