autourgos-core

Typed core vocabulary for the Autourgos framework — Message, ToolSpec, ToolBinding, ToolCall, ToolResult, Action, Resource, Decision, Effect, RunState, Budget, ArtifactRef, and the structural protocols (LLMProvider, Capability, Policy, Middleware) that later Autourgos layers are written against.

from autourgos_core import Action, Resource, Risk

action = Action(tool="write_file", arguments={"path": "x"}, targets=[Resource("path", "x")], risk=Risk.WRITE)

Features

• Zero required dependencies, same as autourgos-agent's own zero-dependency core
• Conversation types: Message, ToolCall, ToolResult, ToolSpec, ToolBinding
• Effects/safety types: Risk, Resource, Action, Decision, Effect — the shared vocabulary a policy engine, an audit log, and a capability package all agree on
• Run state: Budget, ArtifactRef, RunState with to_dict()/from_dict() for lossless round-tripping
• Structural protocols (typing.Protocol): an existing class satisfies these by shape, no import or subclassing required — LLMProvider, Capability, Policy, Middleware, ModelResponse

Table of Contents

• Why This Exists
• Install
• What's Here
• Relationship to the Rest of Autourgos
• License

Why This Exists

Every Autourgos package today communicates through plain dicts and duck typing — autourgos-agent's AgentLoopMixin reads its host object entirely through getattr(self, "x", default), and tool calls are {"action": ..., "action_input": ...} dicts with no shared type checked anywhere. That works, but it means every sibling package re-derives its own version of "what is a message" or "what is a tool result", and a misspelled attribute fails silently instead of at import or call time.

autourgos-core doesn't change any of that — it changes nothing about how autourgos-agent's Agent behaves today. It just gives later packages (a kernel, a policy engine, capability packages for filesystem/shell/desktop access) one shared vocabulary to build on, instead of three dialects of duck-typing.

Install

pip install autourgos-core

What's Here

Conversation types (autourgos_core.messages)

• Message — one conversation turn (role, content, tool_calls, tool_call_id), with .to_dict() producing the OpenAI-compatible dict shape
• ToolCall — one tool invocation (id, name, arguments)
• ToolResult — the outcome of executing a ToolCall, with a real ok: bool instead of a stringly-typed "Error executing ..." convention
• ToolSpec — a tool's schema/description, the part shown to the model
• ToolBinding — a ToolSpec paired with its process-local callable; this is what Capability.tools() returns

Effects/safety types (autourgos_core.effects)

These describe "a tool is about to do something in the real world" — there is no policy engine in this package, just the shared shape one will use.

• Risk — an enum from READ to IRREVERSIBLE
• Resource — one thing an action touches (a path, a process, a network destination, ...)
• Action — a tool call reframed as "here is what this would actually do"
• Decision — a policy verdict (allow / confirm / rewrite / deny) on a proposed Action
• Effect — the record of an Action that actually ran

Run state (autourgos_core.run)

• Budget — ceilings on iterations, execution time, tokens, cost, and effect count
• ArtifactRef — a pointer to something a run produced
• RunState — the full serializable state of one agent run, with to_dict()/from_dict() for lossless round-tripping. This is a data shape only — no engine drives it in this package

Protocols (autourgos_core.protocols)

Structural (typing.Protocol) contracts — an existing class satisfies these by shape, without importing this module or changing a line.

• LLMProvider — complete(messages, tools, **kwargs) -> ModelResponse
• Capability — a package of tools plus enough information (describe()) for a policy engine to reason about what each one touches
• Policy — decide(action, context) -> Decision
• Middleware — the event-driven successor to autourgos-agent's CallbackHandler
• ModelResponse — the normalized shape of one LLM call's result, regardless of provider or tool-calling mode

Relationship to the Rest of Autourgos

This package is the typed foundation for autourgos-kernel, autourgos-policy, and the OS-capability packages (autourgos-cap-fs, autourgos-cap-shell, autourgos-cap-desktop, autourgos-cap-web, autourgos-cap-mcp). autourgos-agent depends on it and re-exports its types, but its Agent class and loop are unchanged and don't require you to use them.

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar