zettcode-server 0.1.0__py3-none-any.whl

zettcode_server/serialize.py

@@ -0,0 +1,292 @@
+"""The SDK's values as the HTTP API's own: one place that decides what crosses the wire.
+
+A conversion lives here rather than in the endpoints so the format is written down once: an SDK field that is not
+meant for a client is left out here, a field the API documents is produced here, and the event stream and the final
+result are shaped by the same rules.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .schemas import (
+    CompactionOut,
+    ContextOut,
+    ContextShareOut,
+    CurrentSessionOut,
+    DayTotalsOut,
+    MentionOut,
+    MessageOut,
+    ModelCheckOut,
+    ModelOut,
+    ModelTotalsOut,
+    ResultOut,
+    SessionOut,
+    SessionStatsOut,
+    SessionTotalsOut,
+    ToolOut,
+    TotalsOut,
+    UsageOut,
+    WorkspaceUsageOut,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.sdk.events import AnyEvent
+    from zettcode.sdk.session import Session
+    from zettcode.sdk.types import (
+        Compaction,
+        ContextReport,
+        MentionInfo,
+        Message,
+        ModelCheck,
+        ModelInfo,
+        RunResult,
+        SessionInfo,
+        SessionStatsInfo,
+        ToolRecord,
+        Totals,
+        Usage,
+        WorkspaceUsage,
+    )
+
+
+def totals_out(totals: Totals) -> TotalsOut:
+    """Return a tally as the API counts it, with the totals the terminal shows worked out."""
+    return TotalsOut(
+        requests=totals.requests,
+        input_tokens=totals.input_tokens,
+        output_tokens=totals.output_tokens,
+        cache_read_tokens=totals.cache_read_tokens,
+        reasoning_tokens=totals.reasoning_tokens,
+        total_tokens=totals.total_tokens,
+        cache_share=totals.cache_share,
+    )
+
+
+def ledger_out(usage: WorkspaceUsage) -> WorkspaceUsageOut:
+    """Return the workspace's usage the way the ``/usage`` page lays it out."""
+    return WorkspaceUsageOut(
+        sessions=[
+            SessionTotalsOut(
+                id=session.id,
+                title=session.title,
+                started=session.started,
+                updated=session.updated,
+                tokens=totals_out(session.tokens),
+                models=list(session.models),
+                entries=session.entries,
+            )
+            for session in usage.sessions
+        ],
+        models=[ModelTotalsOut(model=item.model, tokens=totals_out(item.tokens)) for item in usage.models],
+        days=[DayTotalsOut(day=item.day, tokens=totals_out(item.tokens)) for item in usage.days],
+        total=totals_out(usage.total),
+    )
+
+
+def stats_out(stats: SessionStatsInfo) -> SessionStatsOut:
+    """Return one session's stored totals, with the share the resume panel colours."""
+    return SessionStatsOut(
+        id=stats.id,
+        entries=stats.entries,
+        requests=stats.requests,
+        input_tokens=stats.input_tokens,
+        output_tokens=stats.output_tokens,
+        cache_read_tokens=stats.cache_read_tokens,
+        reasoning_tokens=stats.reasoning_tokens,
+        total_tokens=stats.total_tokens,
+        cache_share=stats.cache_share,
+    )
+
+
+def mention_out(mention: MentionInfo) -> MentionOut:
+    """Return one ``@`` resource as a menu row."""
+    return MentionOut(token=mention.token, kind=mention.kind, name=mention.name, description=mention.description)
+
+
+def check_out(check: ModelCheck) -> ModelCheckOut:
+    """Return one model's doctor result."""
+    return ModelCheckOut(
+        model=check.model,
+        model_id=check.model_id,
+        ok=check.ok,
+        seconds=check.seconds,
+        detail=check.detail,
+        input_tokens=check.input_tokens,
+        output_tokens=check.output_tokens,
+    )
+
+
+def usage_out(usage: Usage) -> UsageOut:
+    """Return the token counts of a session or a run."""
+    return UsageOut(
+        input_tokens=usage.input_tokens,
+        output_tokens=usage.output_tokens,
+        cache_read_tokens=usage.cache_read_tokens,
+        cache_write_tokens=usage.cache_write_tokens,
+        reasoning_tokens=usage.reasoning_tokens,
+        seconds=usage.seconds,
+        requests=usage.requests,
+        context_tokens=usage.context_tokens,
+    )
+
+
+def model_out(model: ModelInfo) -> ModelOut:
+    """Return one configured model, without its token or its address."""
+    return ModelOut(
+        name=model.name,
+        model=model.model,
+        context_window=model.context_window,
+        multimodal=model.multimodal,
+        efforts=list(model.efforts),
+        active=model.active,
+        compact_percent=model.compact_percent,
+    )
+
+
+def session_out(info: SessionInfo, current: str | None = None) -> SessionOut:
+    """Return one stored session: when it changed, and whether it is the one a prompt would continue."""
+    return SessionOut(
+        id=info.id,
+        title=info.title,
+        created_at=info.created_at,
+        updated_at=info.updated_at,
+        current=info.id == current,
+    )
+
+
+def current_session_out(session: Session) -> CurrentSessionOut:
+    """Return the conversation the next prompt continues."""
+    return CurrentSessionOut(
+        id=session.id,
+        title=session.title,
+        locked=session.locked,
+        usage=usage_out(session.usage),
+    )
+
+
+def tool_out(tool: ToolRecord) -> ToolOut:
+    """Return one tool call and how it ended."""
+    return ToolOut(
+        call_id=tool.id,
+        name=tool.name,
+        arguments=dict(tool.arguments),
+        output=tool.output,
+        ok=tool.ok,
+        skipped=tool.skipped,
+    )
+
+
+def message_out(message: Message) -> MessageOut:
+    """Return one message of a stored conversation."""
+    return MessageOut(
+        role=message.role,
+        text=message.text,
+        tool_calls=[
+            ToolOut(call_id=call.id, name=call.name, arguments=dict(call.arguments), output="", ok=True)
+            for call in message.tool_calls
+        ],
+        tool_call_id=message.tool_call_id,
+        tool_name=message.tool_name,
+        ok=message.ok,
+        images=message.images,
+        usage=None if message.usage is None else usage_out(message.usage),
+        seconds=message.seconds,
+    )
+
+
+def compaction_out(compaction: Compaction | None) -> CompactionOut:
+    """Return what a compaction did, or that it applied nothing."""
+    if compaction is None:
+        return CompactionOut(applied=False)
+    return CompactionOut(
+        applied=True,
+        summary=compaction.summary,
+        compressed=compaction.compressed,
+        kept=compaction.kept,
+    )
+
+
+def context_out(report: ContextReport) -> ContextOut:
+    """Return how full the context window is and what is filling it."""
+    return ContextOut(
+        window=report.window,
+        used=report.used,
+        measured_by=report.measured_by,
+        shares=[ContextShareOut(name=share.name, tokens=share.tokens, items=share.items) for share in report.shares],
+        partial=report.partial,
+        from_provider=report.from_provider,
+    )
+
+
+def result_out(result: RunResult) -> ResultOut:
+    """Return what a run came to, with its tool calls but not its raw event log."""
+    return ResultOut(
+        text=result.text,
+        session_id=result.session_id,
+        usage=usage_out(result.usage),
+        tools=[tool_out(tool) for tool in result.tools],
+        stop=result.stop,
+        stop_message=result.stop_message,
+        questions=list(result.questions),
+    )
+
+
+def event_payload(event: AnyEvent) -> dict[str, Any]:
+    """Return one event of a run as the JSON an SSE frame carries.
+
+    Every payload has a ``type``; the rest of the fields depend on it, and are documented with the stream. An event
+    this server does not know is sent as ``{"type": "event", "name": ...}`` rather than dropped, so a newer SDK
+    cannot make a stream look as if nothing happened.
+    """
+    from zettcode.sdk import events
+
+    match event:
+        case events.TextDelta(text=text):
+            return {"type": "text_delta", "text": text}
+        case events.ReasoningDelta(text=text):
+            return {"type": "reasoning_delta", "text": text}
+        case events.ToolStarted(call_id=call_id, name=name, arguments=arguments):
+            return {"type": "tool_started", "call_id": call_id, "name": name, "arguments": dict(arguments)}
+        case events.ToolFinished(call_id=call_id, name=name, output=output, ok=ok, skipped=skipped):
+            return {
+                "type": "tool_finished",
+                "call_id": call_id,
+                "name": name,
+                "output": output,
+                "ok": ok,
+                "skipped": skipped,
+            }
+        case events.ApprovalRequested(call_id=call_id, command=command):
+            return {"type": "approval_requested", "call_id": call_id, "command": command, "approved": event.approved}
+        case events.QuestionAsked(call_id=call_id, question=question, options=options, allow_multiple=allow_multiple):
+            return {
+                "type": "question_asked",
+                "call_id": call_id,
+                "question": question,
+                "options": list(options),
+                "allow_multiple": allow_multiple,
+                "answered": event.answered,
+            }
+        case events.UsageUpdated(usage=usage):
+            return {"type": "usage_updated", "usage": usage_out(usage).model_dump()}
+        case events.CompactionStarted():
+            return {"type": "compaction_started"}
+        case events.CompactionFinished(applied=applied, compaction=compaction):
+            return {
+                "type": "compaction_finished",
+                "applied": applied,
+                "summary": compaction.summary if compaction is not None else "",
+            }
+        case events.ModelStopped(reason=reason, message=message):
+            return {"type": "model_stopped", "reason": reason, "message": message}
+        case events.Steered(text=text):
+            return {"type": "steered", "text": text}
+        case events.Notice(text=text, level=level):
+            return {"type": "notice", "text": text, "level": level}
+        case events.Finished(text=text):
+            return {"type": "finished", "text": text}
+        case events.RawEvent():
+            return {"type": "raw"}
+        case _:
+            return {"type": "event", "name": type(event).__name__}

zettcode_server/settings.py

@@ -0,0 +1,58 @@
+"""What the server was started with: the workspace it serves and the level its runs start at.
+
+One process serves one workspace. The SDK keeps the working directory of the process, so a second workspace in the
+same process is a conflict rather than a feature; a second workspace is a second ``zettcode-server``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: The permission a run starts at. Shell commands are refused, which is what an HTTP endpoint can safely assume:
+#: nobody is at a terminal to answer for one, and whoever calls it names the level they want.
+DEFAULT_PERMISSION = "deny"
+
+#: The interface to bind. Loopback, so starting the server does not put a shell on the network by accident.
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 3290
+
+#: The environment variable that supplies the bearer token, when one is wanted.
+TOKEN_VARIABLE = "ZETTCODE_SERVER_TOKEN"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """The workspace, the socket, and how a run starts.
+
+    Attributes:
+        workspace: The directory the agent works in.
+        host: The interface to bind.
+        port: The port to bind.
+        token: The bearer token every endpoint but ``/health`` requires; ``None`` requires none. It defaults to
+            ``$ZETTCODE_SERVER_TOKEN``, so a token can be kept out of the command line.
+        permission: The shell permission level a run starts at.
+        model: The model to start on, by name, or ``None`` for the first configured one.
+        effort: The reasoning level to start on, or ``None`` for the model's own.
+        config_path: A configuration file to read instead of ``~/.zettcode/config.toml``.
+        title: The ``Server`` header, so a client can tell which server it is talking to.
+        log_level: What uvicorn logs; ``info`` says which requests arrived.
+    """
+
+    workspace: Path
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+    token: str | None = field(default_factory=lambda: os.environ.get(TOKEN_VARIABLE) or None)
+    permission: str = DEFAULT_PERMISSION
+    model: str | None = None
+    effort: str | None = None
+    config_path: Path | None = None
+    title: str = "zettcode-server"
+    log_level: str = "info"
+
+    @property
+    def url(self) -> str:
+        """Return the address the server serves on, as a client writes it."""
+        host = f"[{self.host}]" if ":" in self.host else self.host
+        return f"http://{host}:{self.port}"

zettcode_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: zettcode-server
+Version: 0.1.0
+Summary: The ZettCode coding agent behind an HTTP API: prompts, streaming, sessions and models
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,api,coding-agent,http,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: POSIX :: Linux
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: uvicorn<1,>=0.35
+Requires-Dist: zettcode>=0.1.8
+Description-Content-Type: text/markdown
+
+# zettcode-server
+
+The ZettCode coding agent behind an HTTP API, in the same repository as the terminal program and its SDK.
+
+One process serves one workspace. Every endpoint drives the released `zettcode` SDK — the same tools, plugins, MCP
+servers, skills, project instructions and session store as the terminal — so a conversation begun here can be reopened
+in `zettcode`, and the other way round. The package holds no agent of its own.
+
+```bash
+uv tool install zettcode-server
+zettcode-server --workspace ~/projects/api
+```
+
+```text
+zettcode-server 0.1.0 (zettcode 0.1.8) · http://127.0.0.1:3290 · workspace /home/you/projects/api · permission deny · token off
+```
+
+It binds loopback on port **3290**, denies shell commands by default, and asks for a bearer token only when one is
+configured (`--token`, `$ZETTCODE_SERVER_TOKEN`).
+
+A machine with no model configured is still served: `/health` says `ready: false` and `POST /models` writes the
+`[[models]]` entry (the same one `/config add` writes) and builds the agent, so an editor can set ZettCode up without
+touching a file by hand.
+
+```bash
+curl http://127.0.0.1:3290/health
+curl -N -X POST http://127.0.0.1:3290/prompts \
+  -H 'content-type: application/json' \
+  -d '{"text": "summarize the README", "approvals": {"mode": "deny"}}'
+```
+
+The stream carries the run's events and ends with its result. A run that needs an answer — a shell command, a
+question — is suspended and answered through `POST /runs/approvals` or `POST /runs/questions`, so a client stays in
+the conversation instead of guessing.
+
+- [The guide](https://chang-lehung.github.io/zettcode/server/): install, endpoints, event stream
+- [TypeScript client](../clients/typescript): `npm install zettcode-client`
+- [Python SDK](https://chang-lehung.github.io/zettcode/sdk/): the same agent from Python

zettcode_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+zettcode_server/__init__.py,sha256=LAmx23s5UvWFRobXmQIlr3c5OFGijrJqmLPrRLGKssg,1175
+zettcode_server/app.py,sha256=wg7hNRzVrqRpI7J6UoShB913qE5cn8_Ybhmn_9z0ISM,28380
+zettcode_server/cli.py,sha256=vfo_m6CVoa_MUu3Uji_unBMnthAqPSKFqFqtzAVPB70,4427
+zettcode_server/runner.py,sha256=UkeckWB-Q-WNNhNL4hWAcc90KDcK7f9yuOJ6I4Pe8fA,20479
+zettcode_server/schemas.py,sha256=hNuh1gHWBQQyBVjjlAkoPnlc14x0Hak5ESJAO1g1WIE,15753
+zettcode_server/serialize.py,sha256=hHhY-qgfZWPrVdk4f0GHx8gte7vasCxIcTo6TG5DyDQ,10217
+zettcode_server/settings.py,sha256=TPyytEOxq0ubyZ0bbs6xtgE8b00DYORBCVlNVUxrqL8,2493
+zettcode_server-0.1.0.dist-info/METADATA,sha256=wAsORUS-EA-_pqXelh8DckbDo7qsqrYxOmkfqH_0iTM,2958
+zettcode_server-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+zettcode_server-0.1.0.dist-info/entry_points.txt,sha256=zxhbq2cCa4MMP3_dQAlP_RVEWpGzjh-dse56yoIiIBo,61
+zettcode_server-0.1.0.dist-info/RECORD,,

zettcode_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

zettcode_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zettcode-server = zettcode_server.cli:main