plyngent/doc/architecture.md

# Code Architecture

- plyngent
    - typedef: Shared type aliases.
    - lmproto: Protocols for interacting with LLM service.
        - (common)
            - model: Messages models of specified providers.
            - config: Configurations for specified providers.
            - client: Clients for accessing existent specified services.
            - server: Servers for accepting other clients.
        - openai_compatible: Chat Completions base (``kind=chat_completions``).
        - openai: Platform Responses + chat (``kind=responses``).
        - anthropic: Messages API (``kind=messages``).
        - deepseek
            - openai_compat (``kind=chat_completions``)
            - responses (``kind=responses``; DeepSeek Responses API)
            - anthropic (``kind=messages``; DeepSeek Anthropic-compatible API on
              ``https://api.deepseek.com/anthropic``)
    - utils: Common utilities for code architecture.
        - components: Utilities for class composition.
    - memory: Storage controlling for sessions and messages.
    - config: Plyngent configuration center (TOML), including ``[plugins]`` and
      ``[networking]`` (e.g. fetch SSRF Fake-IP CIDR exemptions). Model entries
      may override provider ``preset`` / ``url`` for mixed API routing.
      ``[skills]`` holds the skill roots, discovery sources, catalog limits, and
      the standing write grant.
    - runtime: ``create_client`` maps effective provider preset → protocol client.
    - skills: Skill discovery (ordered roots, ``SKILL.md`` frontmatter subset,
      mtime-cached store) and the read/write path rules the tools use.
    - agent: Kind-based tool loop, streaming, usage, compact; bridges:
      ``responses_bridge``/``responses_dispatch``, ``messages_bridge``/``messages_dispatch``;
      ``@tool`` / tags / registry. History stays chat-completions-shaped.
    - tools: Workspace file/process/VCS/chat/todo/net/skill tools + directory-access
      grants (`access`); catalog; plugins; instance/session context and views.
    - prompting: Shared ask/choose/form for CLI and tools; the hooks a host uses
      to take over a prompt (output break, SIGINT guard, waiting notification).
    - cli: Click entry, slash registry, REPL, one-shot chat; `notify` announces a
      prompt that waits on the human.
    - web: Web service (Phase H; not implemented).

Plugins (third-party entry points, allowlisted under ``[plugins]``): [plugins.md](./plugins.md).
Conversation units (a *round* = one request→response plus its tool batch, a
*turn* = a user message to the explicit stop): [turns-and-rounds.md](./turns-and-rounds.md).
Images (a turn's pictures, a tool result's pictures, what each wire surface
takes): [images.md](./images.md).
Prompt notifications (a prompt that waits on the human, and how it can be
answered from the notification): [notifications.md](./notifications.md).
Deletes (a `delete_path` call moves the path into the system trash, and what
that does not cover): [trash.md](./trash.md).