Metadata-Version: 2.5
Name: semos-agentura-core
Version: 1.0.1
Summary: Shared MCP + A2A base classes for Semos Agentura agents
Requires-Python: >=3.11
Requires-Dist: a2a-sdk[sqlite]>=0.3
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4.0
Requires-Dist: langchain-core>=1.0
Requires-Dist: mcp<2,>=1.28
Requires-Dist: protobuf>=4
Requires-Dist: pydantic-settings>=2.13
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn>=0.34
Description-Content-Type: text/markdown

# semos-agentura-core

Shared MCP + A2A framework every Semos Agentura agent builds on. An agent is a `BaseAgentService`
subclass plus a list of tools; this package turns that into a FastAPI service speaking both protocols.

## Install

```bash
pip install semos-agentura-core
```

## Minimal agent

```python
from semos.agentura.core import (
    AgentTool,
    BaseAgentService,
    SkillDef,
    agent_tool,
    create_app,
)


@agent_tool(read_only=True)
async def my_tool(param: str) -> str:
    """Does something useful with param."""
    return f"Result: {param}"


class MyAgentService(BaseAgentService):
    @property
    def agent_name(self) -> str:
        return "My Agent"

    @property
    def agent_description(self) -> str:
        return "Does something useful."

    def get_tools(self) -> list[AgentTool]:
        return [my_tool]

    def get_skills(self) -> list[SkillDef]:
        return [SkillDef(id="my-skill", name="My Skill", description="...")]

    async def execute_skill(self, skill_id, message, *, task_id=None) -> str:
        return "result"


app = create_app(MyAgentService())
```

Serve it with `uvicorn module:app`. `create_app` mounts MCP at `/mcp/sse` and A2A at `/a2a` (REST)
and `/a2a/rpc` (JSON-RPC), and serves the agent card at `/.well-known/agent-card.json`.

## What it provides

| Area | Contents |
| --- | --- |
| Service base | `BaseAgentService` - declares tools and skills, resolves file inputs |
| Tools | `AgentTool` (LangChain `BaseTool` subclass), the `@agent_tool` decorator, `ToolResult`, `NamedFile`, `FileAttachment` |
| Transport | `create_app` - FastAPI app serving MCP and A2A from one service |
| Agentic loop | `LLMExecutor` - multi-step tool calling with 5 synthetic tools mapping to A2A task states |
| Clients | `AgenturaClient` (headless, MCP + A2A), `MCPHub`, `AgentConnection` |
| File middleware | `FileRegistry` and symmetric pre/post processing, so the LLM only sees symbolic filenames |
| Settings | `CommonSettings` - loads agent `.env`, falling back to the workspace root |

Tool input schemas are the raw MCP `inputSchema` (LangChain 1.0 accepts raw dicts) and are validated
with `jsonschema`, so `oneOf`/`anyOf`/`const`/`enum` are enforced as published.

## Documentation

- [Agent architecture](https://semos-org.github.io/semos-agentura/agent-architecture/)
- [File handling spec](https://semos-org.github.io/semos-agentura/file-handling-spec/)
- [API reference](https://semos-org.github.io/semos-agentura/api/)

## License

Apache-2.0
