talos-runtime 0.1.0__tar.gz

talos_runtime-0.1.0/.env.example

@@ -0,0 +1,143 @@
+# Safe, non-working examples only. Copy to an ignored local environment file.
+TALOS_ENV=development
+TALOS_PUBLIC_URL=http://localhost:3000
+TALOS_API_BASE_URL=http://127.0.0.1:8000
+TALOS_WEB_URL=http://127.0.0.1:3000
+TALOS_WEB_API_BASE_URL=http://api:8000
+TALOS_API_HOST=127.0.0.1
+TALOS_API_PORT=8000
+TALOS_API_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+TALOS_LOG_LEVEL=INFO
+TALOS_REMOTE_ACCESS_ENABLED=false
+TALOS_LOCAL_API_TOKEN=
+TALOS_MODEL_CREDENTIALS_PATH=.talos/model-credentials
+TALOS_MAX_INPUT_CHARACTERS=100000
+
+DATABASE_URL=postgresql+asyncpg://talos:replace-me@postgres-dev:5432/talos_dev
+REDIS_URL=redis://redis-dev:6379/0
+TALOS_REDIS_QUEUE=talos:jobs
+TALOS_WORKER_POLL_SECONDS=2
+TALOS_CLI_MAX_STDIN_BYTES=1048576
+TALOS_COMPOSE_FILE=docker-compose.dev.yaml
+TALOS_COMPOSE_PROJECT_NAME=talos
+TALOS_LOG_TAIL_LINES=200
+TALOS_SHELL_RUNTIME_MODE=service
+TALOS_API_STARTUP_TIMEOUT_SECONDS=120
+TALOS_WEB_STARTUP_TIMEOUT_SECONDS=120
+TALOS_COMPOSE_COMMAND_TIMEOUT_SECONDS=300
+TALOS_COMPOSE_STOP_TIMEOUT_SECONDS=10
+TALOS_ARTIFACT_ROOT=/var/lib/talos/artifacts
+TALOS_LOCAL_CONFIG_PATH=talos.yaml
+TALOS_CREDENTIAL_SERVICE_NAME=TalosAI
+TALOS_LEGACY_CREDENTIAL_FILE_PATH=.talos/credentials.env
+TALOS_HISTORY_PATH=.talos/history
+TALOS_HISTORY_ENABLED=true
+TALOS_PROMPT_NAME=
+
+TALOS_PIPELINE_MANIFEST_PATH=config/pipelines/simple-chat.yaml
+TALOS_PROVIDER_REGISTRY_PATH=config/providers.yaml
+TALOS_MODEL_REGISTRY_PATH=config/models.yaml
+TALOS_TOOL_REGISTRY_PATH=config/tools.yaml
+TALOS_SKILL_REGISTRY_PATH=config/skills.yaml
+TALOS_PROMPT_REGISTRY_PATH=config/prompts.yaml
+TALOS_RAG_CONFIG_PATH=config/rag.yaml
+TALOS_GUARDRAIL_CONFIG_PATH=config/guardrails.yaml
+TALOS_CAPABILITY_REGISTRY_PATH=config/capabilities.yaml
+TALOS_RELIABILITY_CONFIG_PATH=config/reliability.yaml
+TALOS_SKILL_MAX_FILE_BYTES=32768
+
+TALOS_DEFAULT_PROVIDER=openrouter
+TALOS_CHAT_MODEL=openai/gpt-4o-mini
+OPENROUTER_API_BASE=https://openrouter.ai/api/v1
+OPENROUTER_API_KEY=
+OPENAI_API_BASE=https://api.openai.com/v1
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=
+TALOS_PROVIDER_CONNECT_TIMEOUT_SECONDS=5
+TALOS_PROVIDER_READ_TIMEOUT_SECONDS=60
+
+TALOS_EMBEDDING_MODEL=configure-before-rag-phase
+TALOS_RERANK_MODEL=local-lexical-rerank-v1
+TALOS_AGENT_MAX_STEPS=10
+TALOS_MAX_TOOL_CALLS_PER_RUN=5
+TALOS_MAX_TOKENS_PER_RUN=20000
+TALOS_MODEL_MAX_ATTEMPTS=3
+TALOS_MODEL_RETRY_BASE_MILLISECONDS=250
+TALOS_MODEL_RETRY_MAX_MILLISECONDS=2000
+TALOS_MODEL_RETRY_JITTER_RATIO=0.2
+TALOS_MEMORY_SUMMARY_AFTER_MESSAGES=12
+TALOS_MEMORY_KEEP_RECENT_MESSAGES=6
+TALOS_MEMORY_MAX_SUMMARY_CHARACTERS=6000
+TALOS_MEMORY_SUMMARY_STRATEGY=extractive_v1
+TALOS_MEMORY_MAX_LONG_TERM_ITEMS=100
+TALOS_MEMORY_MAX_CHARACTERS=1000
+TALOS_AGENT_TIMEOUT_SECONDS=120
+TALOS_MODEL_MAX_RETRIES=2
+TALOS_MODEL_MAX_OUTPUT_TOKENS=2048
+TALOS_MODEL_CONTEXT_WINDOW_TOKENS=128000
+TALOS_CONTEXT_SAFETY_MARGIN_TOKENS=1024
+TALOS_TOOL_TIMEOUT_SECONDS=15
+TALOS_TOOL_MAX_RESPONSE_BYTES=65536
+TALOS_TOOL_APPROVAL_TTL_SECONDS=600
+TALOS_HTTP_TOOL_ALLOWED_DOMAINS=example.com
+
+TALOS_RAG_CHUNK_SIZE=800
+TALOS_RAG_CHUNK_OVERLAP=120
+TALOS_RAG_TOP_K=6
+TALOS_RAG_SIMILARITY_THRESHOLD=0.20
+TALOS_LOCAL_EMBEDDING_MODEL=local-hashing-v1
+TALOS_RAG_EMBEDDING_ADAPTER=talos.knowledge:HashingEmbedder
+TALOS_RAG_EMBEDDING_API_BASE=https://api.openai.com/v1
+TALOS_RAG_EMBEDDING_API_KEY_NAME=OPENAI_API_KEY
+TALOS_RAG_EMBEDDING_TIMEOUT_SECONDS=30
+TALOS_RAG_ALLOWED_EXTENSIONS=.md,.txt,.py,.rst,.pdf
+TALOS_RAG_MAX_PDF_PAGES=100
+TALOS_RAG_MAX_PDF_PARSE_SECONDS=15
+TALOS_RAG_MAX_QUERY_CHARACTERS=2000
+TALOS_RAG_EMBEDDING_DIMENSIONS=256
+TALOS_RAG_MAX_SOURCE_BYTES=1048576
+TALOS_RAG_MAX_CHUNKS=10000
+TALOS_RAG_MAX_INGESTION_ATTEMPTS=3
+TALOS_RAG_RETRY_BASE_SECONDS=2
+TALOS_RAG_MODE=advanced
+TALOS_RAG_QUERY_REWRITING=true
+TALOS_RAG_QUERY_EXPANSION=true
+TALOS_RAG_MAX_QUERY_VARIANTS=3
+TALOS_RAG_DENSE_ENABLED=true
+TALOS_RAG_SPARSE_ENABLED=true
+TALOS_RAG_RRF_K=60
+TALOS_RAG_RERANK_ENABLED=true
+TALOS_RAG_RERANK_ADAPTER=talos.retrieval:lexical_rerank
+TALOS_RERANK_API_BASE=http://127.0.0.1
+TALOS_RERANK_API_KEY_NAME=TALOS_UNUSED_LOCAL_RERANK_KEY
+TALOS_RERANK_TIMEOUT_SECONDS=10
+TALOS_RAG_EXPANSION_SYNONYMS=bug:error,defect;auth:authentication,login;db:database,postgres
+TALOS_GUARDRAIL_BLOCK_MESSAGE=Sorry, my policies do not allow me to answer that
+TALOS_GUARDRAIL_MAX_CUSTOM_ITEMS=100
+TALOS_GUARDRAIL_MAX_CUSTOM_ITEM_CHARACTERS=200
+
+TALOS_REPO_MAX_FILES=500
+TALOS_REPO_MAX_FILE_BYTES=65536
+TALOS_REPO_MAX_TOTAL_BYTES=2097152
+TALOS_REPO_MAX_LINE_CHARACTERS=2000
+TALOS_REPO_EXTENSIONS=.py,.ts,.tsx,.js,.jsx,.md,.rst,.txt,.json,.yaml,.yml,.toml,.css,.html
+
+TALOS_TRACING_ENABLED=true
+TALOS_USAGE_TRACKING_ENABLED=true
+TALOS_TRACE_RETENTION_MAX_RUNS=500
+TALOS_ALERT_WINDOW_RUNS=20
+TALOS_ALERT_MINIMUM_RUNS=3
+TALOS_ALERT_FAILURE_RATE_THRESHOLD=0.5
+TALOS_ALERT_SLOW_RUN_MILLISECONDS=30000
+TALOS_OTEL_EXPORTER_ENABLED=false
+OTEL_SERVICE_NAME=talos-api
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.invalid:4317
+OTEL_TRACES_SAMPLER=parentbased_traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1
+# Phase 11 evaluation limits and deterministic evaluator identity
+TALOS_EVALUATION_MAX_CASES_PER_DATASET=100
+TALOS_EVALUATION_MAX_INPUT_CHARACTERS=4000
+TALOS_EVALUATION_MAX_EXPECTED_OUTPUT_CHARACTERS=4000
+TALOS_EVALUATION_MAX_ATTEMPTS=2
+TALOS_EVALUATOR_VERSION=exact-citation-v1

talos_runtime-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+.env
+.env.*
+!.env.example
+talos.yaml
+.talos/
+/tools/
+/skills/*
+!/skills/concise-explainer.md
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.pytest-tmp/
+.coverage
+coverage/
+htmlcov/
+node_modules/
+.next/
+dist/
+build/
+*.egg-info/
+*.tsbuildinfo
+*.db
+*.sqlite*
+*.log
+*.bak
+*.backup
+test-results/
+playwright-report/
+docs/
+benchmarks/
+.sonar/
+.scannerwork/
+AGENTS.md
+CLAUDE.md
+.agents/
+.codex/
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

talos_runtime-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

talos_runtime-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+TalosAI
+Copyright 2026 Samarth Kumar
+
+This product depends on third-party software distributed under its own license terms.
+Dependency manifests and lockfiles identify those components. Their upstream distributions
+include the applicable licenses and notices. The Talos Python wheel and source archive do
+not vendor dependency source or binaries.

talos_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: talos-runtime
+Version: 0.1.0
+Summary: Developer-first AI agent runtime and Python SDK
+Project-URL: Source, https://github.com/SamarthKumar3/TalosAI
+Project-URL: Issues, https://github.com/SamarthKumar3/TalosAI/issues
+Author: Samarth Kumar
+Maintainer: Samarth Kumar
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent,ai,llm,rag,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: cli
+Requires-Dist: keyring<26,>=25; extra == 'cli'
+Requires-Dist: prompt-toolkit<4,>=3.0.48; extra == 'cli'
+Requires-Dist: rich<15,>=13.9; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: types-pyyaml<7,>=6.0.12; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: langgraph<2,>=1.0; extra == 'graph'
+Provides-Extra: pdf
+Requires-Dist: pypdf<7,>=6.19; extra == 'pdf'
+Provides-Extra: service
+Requires-Dist: alembic<2,>=1.14; extra == 'service'
+Requires-Dist: asyncpg<1,>=0.30; extra == 'service'
+Requires-Dist: cryptography==50.0.2; extra == 'service'
+Requires-Dist: fastapi<1,>=0.115; extra == 'service'
+Requires-Dist: greenlet<4,>=3.1; extra == 'service'
+Requires-Dist: langgraph<2,>=1.0; extra == 'service'
+Requires-Dist: pypdf<7,>=6.19; extra == 'service'
+Requires-Dist: redis<7,>=5.2; extra == 'service'
+Requires-Dist: sqlalchemy<3,>=2.0.36; extra == 'service'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'service'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api<2,>=1.45; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.45; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk<2,>=1.45; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# TalosAI
+
+Talos is an AI assistant you can use in Python, in your terminal, or in your browser.
+Ask questions, search your files, understand code, and add your own tools and skills.
+
+This is an early release. Windows is the tested development platform. Mac and Linux
+still need a full first-time setup check.
+
+## Get started
+
+You need Python 3.12. Choose Python, terminal, or browser mode below.
+For terminal and browser mode, download this repository and open a terminal in
+its folder. Also install and start Docker Desktop with Linux containers and
+Docker Compose. You do not need Node.js for normal use.
+
+Create a Python environment:
+
+```sh
+python -m venv .venv
+```
+
+Activate it on Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Or on Mac and Linux:
+
+```sh
+source .venv/bin/activate
+```
+
+Bring pip up to date:
+
+```sh
+python -m pip install --upgrade pip
+```
+
+For terminal or browser mode, install from the downloaded folder:
+
+```sh
+python -m pip install ".[cli]"
+```
+
+For the Python SDK, once the package is published on PyPI, install it directly:
+
+```sh
+python -m pip install talos-runtime
+```
+
+The SDK does not need this repository, Git, Docker, or a browser. Until the first
+PyPI release is published, use `python -m pip install .` from this folder instead.
+Keep your Python environment active when running Talos.
+
+The SDK installs only its core dependencies. Add PDF reading with
+`python -m pip install "talos-runtime[pdf]"`. Custom branching pipelines use
+`"talos-runtime[graph]"`; sending traces to an external service uses
+`"talos-runtime[telemetry]"`. Local run history and traces work with the core SDK.
+Terminal and browser installation above includes their host-side tools; Docker
+installs the server dependencies separately.
+
+### 1. Terminal
+
+Create your local settings once, from the repository folder:
+
+```sh
+cp talos.example.yaml talos.yaml
+```
+
+`cp` also works in PowerShell. Keep your own `talos.yaml` when updating Talos.
+
+Start the assistant:
+
+```sh
+hi talos
+```
+
+On first use, Talos asks for an [OpenRouter API key](https://openrouter.ai/settings/keys).
+Your typing is hidden and the key is saved in your computer's credential store.
+The default model is `openai/gpt-4o-mini`; provider charges may apply.
+The first start downloads and builds the local services, so allow a few minutes.
+
+Type a question and press Enter. Use `/help` for commands, `/new` for a fresh chat,
+`/why` to inspect the last answer, and `/exit` to leave. Ctrl+C cancels a response.
+
+### 2. Browser
+
+Use the same installation and local settings as terminal mode. From the repository folder, run:
+
+```sh
+talos ui
+```
+
+Talos asks for a key if needed and opens the browser when it is ready.
+If the browser does not open, visit `http://127.0.0.1:3000`.
+
+In Settings, use **Runtime** to add model keys and models, then refresh the model list.
+Choose a model beside the microphone in chat. Settings also lets you add tools and
+skills, view run traces, and change appearance. **Debug**, after Runtime, runs the
+same setup checks as `talos doctor`. New model choices start a new chat.
+
+Closing the browser or terminal keeps your chats and local services.
+To stop the services without deleting your data, run `talos stop`.
+Run only one local Talos installation at a time; it uses ports 3000 and 8000.
+
+### 3. Python SDK
+
+After `python -m pip install talos-runtime`, create a project in any folder you choose:
+
+```sh
+talos init my-agent
+cd my-agent
+```
+
+Save this as `hello.py`:
+
+```python
+import asyncio
+from getpass import getpass
+
+from dotenv import dotenv_values
+from talos import TalosAgent
+
+
+async def main():
+    settings = {
+        key: value for key, value in dotenv_values(".env.example").items() if value is not None
+    }
+    settings["OPENROUTER_API_KEY"] = getpass("OpenRouter API key: ")
+    agent = TalosAgent.from_config("talos.yaml", environment=settings)
+    answer = await agent.run("Explain what an AI agent is in two sentences.")
+    print(answer.response)
+
+
+asyncio.run(main())
+```
+
+Run it:
+
+```sh
+python hello.py
+```
+
+For a free, offline setup check, import `FakeModelProvider` from `talos` and add
+`provider=FakeModelProvider("Talos is ready.")` to `from_config(...)`. Skip the key prompt.
+This returns a fixed sample answer; it does not call an AI model.
+
+## Add tools and skills
+
+In the browser, open Settings and use the tool or skill form.
+In the terminal, import your own files:
+
+```sh
+talos tools add path/to/tool.yaml
+talos skills add path/to/skill.md
+talos tools --help
+talos skills --help
+```
+
+YAML tools support limited text formatting and arithmetic. Skills are Markdown
+instructions that guide the assistant. Review files before importing them.
+For reviewed Python tools, build their separate sandbox first:
+
+```sh
+docker build -f Dockerfile.sandbox -t talos-tool-sandbox:1 .
+talos tools add --help
+```
+
+Python tools require explicit trust and a matching file hash. They run in a
+restricted Docker container. SDK callables registered directly by your app
+run with your app's permissions.
+
+## Your data
+
+Talos runs locally. Your chosen AI provider receives the messages, selected file
+excerpts, and tool results needed to answer. Check that provider's privacy terms.
+Optional voice input may send audio to your browser's speech service.
+
+Chats and run records stay in local storage. Stopping Talos preserves them;
+there is no complete erase-all button. Backups and providers can retain copies.
+CLI keys use the computer's credential store; browser-added keys use encrypted
+local files. Protect the files and backups. Keep `.env`, `talos.yaml`, `.talos/`,
+and imported files private. Use the browser on this computer only; this setup is
+for one trusted user and is not ready to be exposed to the Internet.
+
+## When something goes wrong
+
+- Run `talos doctor` or Settings → Debug → Run Talos Doctor to check setup.
+  Run `talos status` to check services.
+- Start Docker Desktop if Talos cannot reach Docker.
+- Run `talos logs --help` for service logs. Remove private information before sharing logs.
+- For failed or slow answers, check Settings → Traces, your model key, provider availability,
+  and usage limits. Retry in a new chat after fixing the cause.
+- If PowerShell blocks environment activation, use `.\.venv\Scripts\python.exe`
+  and `.\.venv\Scripts\talos.exe` directly instead of changing system policy.
+- If a key leaks, revoke it at the provider and replace it in Talos.
+
+## License
+
+TalosAI is licensed under [Apache 2.0](LICENSE). See [NOTICE](NOTICE).